|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. _process:
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
:c:type:`uv_process_t` --- Process handle
|
|
Packit |
b5b901 |
=========================================
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Process handles will spawn a new process and allow the user to control it and
|
|
Packit |
b5b901 |
establish communication channels with it using streams.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Data types
|
|
Packit |
b5b901 |
----------
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:type:: uv_process_t
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Process handle type.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:type:: uv_process_options_t
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Options for spawning the process (passed to :c:func:`uv_spawn`.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
::
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
typedef struct uv_process_options_s {
|
|
Packit |
b5b901 |
uv_exit_cb exit_cb;
|
|
Packit |
b5b901 |
const char* file;
|
|
Packit |
b5b901 |
char** args;
|
|
Packit |
b5b901 |
char** env;
|
|
Packit |
b5b901 |
const char* cwd;
|
|
Packit |
b5b901 |
unsigned int flags;
|
|
Packit |
b5b901 |
int stdio_count;
|
|
Packit |
b5b901 |
uv_stdio_container_t* stdio;
|
|
Packit |
b5b901 |
uv_uid_t uid;
|
|
Packit |
b5b901 |
uv_gid_t gid;
|
|
Packit |
b5b901 |
} uv_process_options_t;
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:type:: void (*uv_exit_cb)(uv_process_t*, int64_t exit_status, int term_signal)
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Type definition for callback passed in :c:type:`uv_process_options_t` which
|
|
Packit |
b5b901 |
will indicate the exit status and the signal that caused the process to
|
|
Packit |
b5b901 |
terminate, if any.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:type:: uv_process_flags
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Flags to be set on the flags field of :c:type:`uv_process_options_t`.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
::
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
enum uv_process_flags {
|
|
Packit |
b5b901 |
/*
|
|
Packit |
b5b901 |
* Set the child process' user id.
|
|
Packit |
b5b901 |
*/
|
|
Packit |
b5b901 |
UV_PROCESS_SETUID = (1 << 0),
|
|
Packit |
b5b901 |
/*
|
|
Packit |
b5b901 |
* Set the child process' group id.
|
|
Packit |
b5b901 |
*/
|
|
Packit |
b5b901 |
UV_PROCESS_SETGID = (1 << 1),
|
|
Packit |
b5b901 |
/*
|
|
Packit |
b5b901 |
* Do not wrap any arguments in quotes, or perform any other escaping, when
|
|
Packit |
b5b901 |
* converting the argument list into a command line string. This option is
|
|
Packit |
b5b901 |
* only meaningful on Windows systems. On Unix it is silently ignored.
|
|
Packit |
b5b901 |
*/
|
|
Packit |
b5b901 |
UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS = (1 << 2),
|
|
Packit |
b5b901 |
/*
|
|
Packit |
b5b901 |
* Spawn the child process in a detached state - this will make it a process
|
|
Packit |
b5b901 |
* group leader, and will effectively enable the child to keep running after
|
|
Packit |
b5b901 |
* the parent exits. Note that the child process will still keep the
|
|
Packit |
b5b901 |
* parent's event loop alive unless the parent process calls uv_unref() on
|
|
Packit |
b5b901 |
* the child's process handle.
|
|
Packit |
b5b901 |
*/
|
|
Packit |
b5b901 |
UV_PROCESS_DETACHED = (1 << 3),
|
|
Packit |
b5b901 |
/*
|
|
Packit Service |
e08953 |
* Hide the subprocess window that would normally be created. This option is
|
|
Packit Service |
e08953 |
* only meaningful on Windows systems. On Unix it is silently ignored.
|
|
Packit Service |
e08953 |
*/
|
|
Packit Service |
e08953 |
UV_PROCESS_WINDOWS_HIDE = (1 << 4),
|
|
Packit Service |
e08953 |
/*
|
|
Packit Service |
e08953 |
* Hide the subprocess console window that would normally be created. This
|
|
Packit Service |
e08953 |
* option is only meaningful on Windows systems. On Unix it is silently
|
|
Packit Service |
e08953 |
* ignored.
|
|
Packit Service |
e08953 |
*/
|
|
Packit Service |
e08953 |
UV_PROCESS_WINDOWS_HIDE_CONSOLE = (1 << 5),
|
|
Packit Service |
e08953 |
/*
|
|
Packit Service |
e08953 |
* Hide the subprocess GUI window that would normally be created. This
|
|
Packit |
b5b901 |
* option is only meaningful on Windows systems. On Unix it is silently
|
|
Packit |
b5b901 |
* ignored.
|
|
Packit |
b5b901 |
*/
|
|
Packit Service |
e08953 |
UV_PROCESS_WINDOWS_HIDE_GUI = (1 << 6)
|
|
Packit |
b5b901 |
};
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:type:: uv_stdio_container_t
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Container for each stdio handle or fd passed to a child process.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
::
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
typedef struct uv_stdio_container_s {
|
|
Packit |
b5b901 |
uv_stdio_flags flags;
|
|
Packit |
b5b901 |
union {
|
|
Packit |
b5b901 |
uv_stream_t* stream;
|
|
Packit |
b5b901 |
int fd;
|
|
Packit |
b5b901 |
} data;
|
|
Packit |
b5b901 |
} uv_stdio_container_t;
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:type:: uv_stdio_flags
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Flags specifying how a stdio should be transmitted to the child process.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
::
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
typedef enum {
|
|
Packit |
b5b901 |
UV_IGNORE = 0x00,
|
|
Packit |
b5b901 |
UV_CREATE_PIPE = 0x01,
|
|
Packit |
b5b901 |
UV_INHERIT_FD = 0x02,
|
|
Packit |
b5b901 |
UV_INHERIT_STREAM = 0x04,
|
|
Packit |
b5b901 |
/*
|
|
Packit |
b5b901 |
* When UV_CREATE_PIPE is specified, UV_READABLE_PIPE and UV_WRITABLE_PIPE
|
|
Packit |
b5b901 |
* determine the direction of flow, from the child process' perspective. Both
|
|
Packit |
b5b901 |
* flags may be specified to create a duplex data stream.
|
|
Packit |
b5b901 |
*/
|
|
Packit |
b5b901 |
UV_READABLE_PIPE = 0x10,
|
|
Packit |
b5b901 |
UV_WRITABLE_PIPE = 0x20
|
|
Packit |
b5b901 |
/*
|
|
Packit |
b5b901 |
* Open the child pipe handle in overlapped mode on Windows.
|
|
Packit |
b5b901 |
* On Unix it is silently ignored.
|
|
Packit |
b5b901 |
*/
|
|
Packit |
b5b901 |
UV_OVERLAPPED_PIPE = 0x40
|
|
Packit |
b5b901 |
} uv_stdio_flags;
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Public members
|
|
Packit |
b5b901 |
^^^^^^^^^^^^^^
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:member:: uv_process_t.pid
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
The PID of the spawned process. It's set after calling :c:func:`uv_spawn`.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. note::
|
|
Packit |
b5b901 |
The :c:type:`uv_handle_t` members also apply.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:member:: uv_process_options_t.exit_cb
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Callback called after the process exits.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:member:: uv_process_options_t.file
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Path pointing to the program to be executed.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:member:: uv_process_options_t.args
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Command line arguments. args[0] should be the path to the program. On
|
|
Packit |
b5b901 |
Windows this uses `CreateProcess` which concatenates the arguments into a
|
|
Packit |
b5b901 |
string this can cause some strange errors. See the
|
|
Packit |
b5b901 |
``UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS`` flag on :c:type:`uv_process_flags`.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:member:: uv_process_options_t.env
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Environment for the new process. If NULL the parents environment is used.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:member:: uv_process_options_t.cwd
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Current working directory for the subprocess.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:member:: uv_process_options_t.flags
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Various flags that control how :c:func:`uv_spawn` behaves. See
|
|
Packit |
b5b901 |
:c:type:`uv_process_flags`.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:member:: uv_process_options_t.stdio_count
|
|
Packit |
b5b901 |
.. c:member:: uv_process_options_t.stdio
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
The `stdio` field points to an array of :c:type:`uv_stdio_container_t`
|
|
Packit |
b5b901 |
structs that describe the file descriptors that will be made available to
|
|
Packit |
b5b901 |
the child process. The convention is that stdio[0] points to stdin,
|
|
Packit |
b5b901 |
fd 1 is used for stdout, and fd 2 is stderr.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. note::
|
|
Packit |
b5b901 |
On Windows file descriptors greater than 2 are available to the child process only if
|
|
Packit |
b5b901 |
the child processes uses the MSVCRT runtime.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:member:: uv_process_options_t.uid
|
|
Packit |
b5b901 |
.. c:member:: uv_process_options_t.gid
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Libuv can change the child process' user/group id. This happens only when
|
|
Packit |
b5b901 |
the appropriate bits are set in the flags fields.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. note::
|
|
Packit |
b5b901 |
This is not supported on Windows, :c:func:`uv_spawn` will fail and set the error
|
|
Packit |
b5b901 |
to ``UV_ENOTSUP``.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:member:: uv_stdio_container_t.flags
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Flags specifying how the stdio container should be passed to the child. See
|
|
Packit |
b5b901 |
:c:type:`uv_stdio_flags`.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:member:: uv_stdio_container_t.data
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Union containing either the stream or fd to be passed on to the child
|
|
Packit |
b5b901 |
process.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
API
|
|
Packit |
b5b901 |
---
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:function:: void uv_disable_stdio_inheritance(void)
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Disables inheritance for file descriptors / handles that this process
|
|
Packit |
b5b901 |
inherited from its parent. The effect is that child processes spawned by
|
|
Packit |
b5b901 |
this process don't accidentally inherit these handles.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
It is recommended to call this function as early in your program as possible,
|
|
Packit |
b5b901 |
before the inherited file descriptors can be closed or duplicated.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. note::
|
|
Packit |
b5b901 |
This function works on a best-effort basis: there is no guarantee that libuv can discover
|
|
Packit |
b5b901 |
all file descriptors that were inherited. In general it does a better job on Windows than
|
|
Packit |
b5b901 |
it does on Unix.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:function:: int uv_spawn(uv_loop_t* loop, uv_process_t* handle, const uv_process_options_t* options)
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Initializes the process handle and starts the process. If the process is
|
|
Packit |
b5b901 |
successfully spawned, this function will return 0. Otherwise, the
|
|
Packit |
b5b901 |
negative error code corresponding to the reason it couldn't spawn is
|
|
Packit |
b5b901 |
returned.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Possible reasons for failing to spawn would include (but not be limited to)
|
|
Packit |
b5b901 |
the file to execute not existing, not having permissions to use the setuid or
|
|
Packit |
b5b901 |
setgid specified, or not having enough memory to allocate for the new
|
|
Packit |
b5b901 |
process.
|
|
Packit |
b5b901 |
|
|
Packit Service |
e08953 |
.. versionchanged:: 1.24.0 Added `UV_PROCESS_WINDOWS_HIDE_CONSOLE` and
|
|
Packit Service |
e08953 |
`UV_PROCESS_WINDOWS_HIDE_GUI` flags.
|
|
Packit Service |
e08953 |
|
|
Packit |
b5b901 |
.. c:function:: int uv_process_kill(uv_process_t* handle, int signum)
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Sends the specified signal to the given process handle. Check the documentation
|
|
Packit |
b5b901 |
on :c:ref:`signal` for signal support, specially on Windows.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:function:: int uv_kill(int pid, int signum)
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Sends the specified signal to the given PID. Check the documentation
|
|
Packit |
b5b901 |
on :c:ref:`signal` for signal support, specially on Windows.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. c:function:: uv_pid_t uv_process_get_pid(const uv_process_t* handle)
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
Returns `handle->pid`.
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. versionadded:: 1.19.0
|
|
Packit |
b5b901 |
|
|
Packit |
b5b901 |
.. seealso:: The :c:type:`uv_handle_t` API functions also apply.
|