1
2.. _process:
3
4:c:type:`uv_process_t` --- Process handle
5=========================================
6
7Process handles will spawn a new process and allow the user to control it and
8establish communication channels with it using streams.
9
10
11Data types
12----------
13
14.. c:type:: uv_process_t
15
16    Process handle type.
17
18.. c:type:: uv_process_options_t
19
20    Options for spawning the process (passed to :c:func:`uv_spawn`.
21
22    ::
23
24        typedef struct uv_process_options_s {
25            uv_exit_cb exit_cb;
26            const char* file;
27            char** args;
28            char** env;
29            const char* cwd;
30            unsigned int flags;
31            int stdio_count;
32            uv_stdio_container_t* stdio;
33            uv_uid_t uid;
34            uv_gid_t gid;
35        } uv_process_options_t;
36
37.. c:type:: void (*uv_exit_cb)(uv_process_t*, int64_t exit_status, int term_signal)
38
39    Type definition for callback passed in :c:type:`uv_process_options_t` which
40    will indicate the exit status and the signal that caused the process to
41    terminate, if any.
42
43.. c:type:: uv_process_flags
44
45    Flags to be set on the flags field of :c:type:`uv_process_options_t`.
46
47    ::
48
49        enum uv_process_flags {
50            /*
51            * Set the child process' user id.
52            */
53            UV_PROCESS_SETUID = (1 << 0),
54            /*
55            * Set the child process' group id.
56            */
57            UV_PROCESS_SETGID = (1 << 1),
58            /*
59            * Do not wrap any arguments in quotes, or perform any other escaping, when
60            * converting the argument list into a command line string. This option is
61            * only meaningful on Windows systems. On Unix it is silently ignored.
62            */
63            UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS = (1 << 2),
64            /*
65            * Spawn the child process in a detached state - this will make it a process
66            * group leader, and will effectively enable the child to keep running after
67            * the parent exits. Note that the child process will still keep the
68            * parent's event loop alive unless the parent process calls uv_unref() on
69            * the child's process handle.
70            */
71            UV_PROCESS_DETACHED = (1 << 3),
72            /*
73            * Hide the subprocess window that would normally be created. This option is
74            * only meaningful on Windows systems. On Unix it is silently ignored.
75            */
76            UV_PROCESS_WINDOWS_HIDE = (1 << 4),
77            /*
78            * Hide the subprocess console window that would normally be created. This
79            * option is only meaningful on Windows systems. On Unix it is silently
80            * ignored.
81            */
82            UV_PROCESS_WINDOWS_HIDE_CONSOLE = (1 << 5),
83            /*
84            * Hide the subprocess GUI window that would normally be created. This
85            * option is only meaningful on Windows systems. On Unix it is silently
86            * ignored.
87            */
88            UV_PROCESS_WINDOWS_HIDE_GUI = (1 << 6)
89        };
90
91.. c:type:: uv_stdio_container_t
92
93    Container for each stdio handle or fd passed to a child process.
94
95    ::
96
97        typedef struct uv_stdio_container_s {
98            uv_stdio_flags flags;
99            union {
100                uv_stream_t* stream;
101                int fd;
102            } data;
103        } uv_stdio_container_t;
104
105.. c:enum:: uv_stdio_flags
106
107    Flags specifying how a stdio should be transmitted to the child process.
108
109    ::
110
111        typedef enum {
112            UV_IGNORE = 0x00,
113            UV_CREATE_PIPE = 0x01,
114            UV_INHERIT_FD = 0x02,
115            UV_INHERIT_STREAM = 0x04,
116            /*
117            * When UV_CREATE_PIPE is specified, UV_READABLE_PIPE and UV_WRITABLE_PIPE
118            * determine the direction of flow, from the child process' perspective. Both
119            * flags may be specified to create a duplex data stream.
120            */
121            UV_READABLE_PIPE = 0x10,
122            UV_WRITABLE_PIPE = 0x20,
123            /*
124            * When UV_CREATE_PIPE is specified, specifying UV_NONBLOCK_PIPE opens the
125            * handle in non-blocking mode in the child. This may cause loss of data,
126            * if the child is not designed to handle to encounter this mode,
127            * but can also be significantly more efficient.
128            */
129            UV_NONBLOCK_PIPE = 0x40
130        } uv_stdio_flags;
131
132
133Public members
134^^^^^^^^^^^^^^
135
136.. c:member:: int uv_process_t.pid
137
138    The PID of the spawned process. It's set after calling :c:func:`uv_spawn`.
139
140.. note::
141    The :c:type:`uv_handle_t` members also apply.
142
143.. c:member:: uv_exit_cb uv_process_options_t.exit_cb
144
145    Callback called after the process exits.
146
147.. c:member:: const char* uv_process_options_t.file
148
149    Path pointing to the program to be executed.
150
151.. c:member:: char** uv_process_options_t.args
152
153    Command line arguments. args[0] should be the path to the program. On
154    Windows this uses `CreateProcess` which concatenates the arguments into a
155    string this can cause some strange errors. See the
156    ``UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS`` flag on :c:type:`uv_process_flags`.
157
158.. c:member:: char** uv_process_options_t.env
159
160    Environment for the new process. If NULL the parents environment is used.
161
162.. c:member:: const char* uv_process_options_t.cwd
163
164    Current working directory for the subprocess.
165
166.. c:member:: unsigned int uv_process_options_t.flags
167
168    Various flags that control how :c:func:`uv_spawn` behaves. See
169    :c:type:`uv_process_flags`.
170
171.. c:member:: int uv_process_options_t.stdio_count
172.. c:member:: uv_stdio_container_t* uv_process_options_t.stdio
173
174    The `stdio` field points to an array of :c:type:`uv_stdio_container_t`
175    structs that describe the file descriptors that will be made available to
176    the child process. The convention is that stdio[0] points to stdin,
177    fd 1 is used for stdout, and fd 2 is stderr.
178
179    .. note::
180        On Windows file descriptors greater than 2 are available to the child process only if
181        the child processes uses the MSVCRT runtime.
182
183.. c:member:: uv_uid_t uv_process_options_t.uid
184.. c:member:: uv_gid_t uv_process_options_t.gid
185
186    Libuv can change the child process' user/group id. This happens only when
187    the appropriate bits are set in the flags fields.
188
189    .. note::
190        This is not supported on Windows, :c:func:`uv_spawn` will fail and set the error
191        to ``UV_ENOTSUP``.
192
193.. c:member:: uv_stdio_flags uv_stdio_container_t.flags
194
195    Flags specifying how the stdio container should be passed to the child.
196
197.. c:member:: union @0 uv_stdio_container_t.data
198
199    Union containing either the `stream` or `fd` to be passed on to the child
200    process.
201
202
203API
204---
205
206.. c:function:: void uv_disable_stdio_inheritance(void)
207
208    Disables inheritance for file descriptors / handles that this process
209    inherited from its parent. The effect is that child processes spawned by
210    this process don't accidentally inherit these handles.
211
212    It is recommended to call this function as early in your program as possible,
213    before the inherited file descriptors can be closed or duplicated.
214
215    .. note::
216        This function works on a best-effort basis: there is no guarantee that libuv can discover
217        all file descriptors that were inherited. In general it does a better job on Windows than
218        it does on Unix.
219
220.. c:function:: int uv_spawn(uv_loop_t* loop, uv_process_t* handle, const uv_process_options_t* options)
221
222    Initializes the process handle and starts the process. If the process is
223    successfully spawned, this function will return 0. Otherwise, the
224    negative error code corresponding to the reason it couldn't spawn is
225    returned.
226
227    Possible reasons for failing to spawn would include (but not be limited to)
228    the file to execute not existing, not having permissions to use the setuid or
229    setgid specified, or not having enough memory to allocate for the new
230    process.
231
232    .. versionchanged:: 1.24.0 Added `UV_PROCESS_WINDOWS_HIDE_CONSOLE` and
233                        `UV_PROCESS_WINDOWS_HIDE_GUI` flags.
234
235.. c:function:: int uv_process_kill(uv_process_t* handle, int signum)
236
237    Sends the specified signal to the given process handle. Check the documentation
238    on :c:ref:`signal` for signal support, specially on Windows.
239
240.. c:function:: int uv_kill(int pid, int signum)
241
242    Sends the specified signal to the given PID. Check the documentation
243    on :c:ref:`signal` for signal support, specially on Windows.
244
245.. c:function:: uv_pid_t uv_process_get_pid(const uv_process_t* handle)
246
247    Returns `handle->pid`.
248
249    .. versionadded:: 1.19.0
250
251.. seealso:: The :c:type:`uv_handle_t` API functions also apply.
252