|
160
|
1
|
|
|
2 .. _process:
|
|
|
3
|
|
|
4 :c:type:`uv_process_t` --- Process handle
|
|
|
5 =========================================
|
|
|
6
|
|
|
7 Process handles will spawn a new process and allow the user to control it and
|
|
|
8 establish communication channels with it using streams.
|
|
|
9
|
|
|
10
|
|
|
11 Data 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:enum:: 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 * On Windows, if the path to the program to execute, specified in
|
|
|
91 * uv_process_options_t's file field, has a directory component,
|
|
|
92 * search for the exact file name before trying variants with
|
|
|
93 * extensions like '.exe' or '.cmd'.
|
|
|
94 */
|
|
|
95 UV_PROCESS_WINDOWS_FILE_PATH_EXACT_NAME = (1 << 7)
|
|
|
96 };
|
|
|
97
|
|
|
98 .. c:type:: uv_stdio_container_t
|
|
|
99
|
|
|
100 Container for each stdio handle or fd passed to a child process.
|
|
|
101
|
|
|
102 ::
|
|
|
103
|
|
|
104 typedef struct uv_stdio_container_s {
|
|
|
105 uv_stdio_flags flags;
|
|
|
106 union {
|
|
|
107 uv_stream_t* stream;
|
|
|
108 int fd;
|
|
|
109 } data;
|
|
|
110 } uv_stdio_container_t;
|
|
|
111
|
|
|
112 .. c:enum:: uv_stdio_flags
|
|
|
113
|
|
|
114 Flags specifying how a stdio should be transmitted to the child process.
|
|
|
115
|
|
|
116 ::
|
|
|
117
|
|
|
118 typedef enum {
|
|
|
119 /*
|
|
|
120 * The following four options are mutually-exclusive, and define
|
|
|
121 * the operation to perform for the corresponding file descriptor
|
|
|
122 * in the child process:
|
|
|
123 */
|
|
|
124
|
|
|
125 /*
|
|
|
126 * No file descriptor will be provided (or redirected to
|
|
|
127 * `/dev/null` if it is fd 0, 1 or 2).
|
|
|
128 */
|
|
|
129 UV_IGNORE = 0x00,
|
|
|
130
|
|
|
131 /*
|
|
|
132 * Open a new pipe into `data.stream`, per the flags below. The
|
|
|
133 * `data.stream` field must point to a uv_pipe_t object that has
|
|
|
134 * been initialized with `uv_pipe_init(loop, data.stream, ipc);`,
|
|
|
135 * but not yet opened or connected.
|
|
|
136 /*
|
|
|
137 UV_CREATE_PIPE = 0x01,
|
|
|
138
|
|
|
139 /*
|
|
|
140 * The child process will be given a duplicate of the parent's
|
|
|
141 * file descriptor given by `data.fd`.
|
|
|
142 */
|
|
|
143 UV_INHERIT_FD = 0x02,
|
|
|
144
|
|
|
145 /*
|
|
|
146 * The child process will be given a duplicate of the parent's
|
|
|
147 * file descriptor being used by the stream handle given by
|
|
|
148 * `data.stream`.
|
|
|
149 */
|
|
|
150 UV_INHERIT_STREAM = 0x04,
|
|
|
151
|
|
|
152 /*
|
|
|
153 * When UV_CREATE_PIPE is specified, UV_READABLE_PIPE and UV_WRITABLE_PIPE
|
|
|
154 * determine the direction of flow, from the child process' perspective. Both
|
|
|
155 * flags may be specified to create a duplex data stream.
|
|
|
156 */
|
|
|
157 UV_READABLE_PIPE = 0x10,
|
|
|
158 UV_WRITABLE_PIPE = 0x20,
|
|
|
159
|
|
|
160 /*
|
|
|
161 * When UV_CREATE_PIPE is specified, specifying UV_NONBLOCK_PIPE opens the
|
|
|
162 * handle in non-blocking mode in the child. This may cause loss of data,
|
|
|
163 * if the child is not designed to handle to encounter this mode,
|
|
|
164 * but can also be significantly more efficient.
|
|
|
165 */
|
|
|
166 UV_NONBLOCK_PIPE = 0x40
|
|
|
167 } uv_stdio_flags;
|
|
|
168
|
|
|
169
|
|
|
170 Public members
|
|
|
171 ^^^^^^^^^^^^^^
|
|
|
172
|
|
|
173 .. c:member:: int uv_process_t.pid
|
|
|
174
|
|
|
175 The PID of the spawned process. It's set after calling :c:func:`uv_spawn`.
|
|
|
176
|
|
|
177 .. note::
|
|
|
178 The :c:type:`uv_handle_t` members also apply.
|
|
|
179
|
|
|
180 .. c:member:: uv_exit_cb uv_process_options_t.exit_cb
|
|
|
181
|
|
|
182 Callback called after the process exits.
|
|
|
183
|
|
|
184 .. c:member:: const char* uv_process_options_t.file
|
|
|
185
|
|
|
186 Path pointing to the program to be executed.
|
|
|
187
|
|
|
188 .. c:member:: char** uv_process_options_t.args
|
|
|
189
|
|
|
190 Command line arguments. args[0] should be the path to the program. On
|
|
|
191 Windows this uses `CreateProcess` which concatenates the arguments into a
|
|
|
192 string this can cause some strange errors. See the
|
|
|
193 ``UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS`` flag on :c:enum:`uv_process_flags`.
|
|
|
194
|
|
|
195 .. c:member:: char** uv_process_options_t.env
|
|
|
196
|
|
|
197 Environment for the new process. If NULL the parents environment is used.
|
|
|
198
|
|
|
199 .. c:member:: const char* uv_process_options_t.cwd
|
|
|
200
|
|
|
201 Current working directory for the subprocess.
|
|
|
202
|
|
|
203 .. c:member:: unsigned int uv_process_options_t.flags
|
|
|
204
|
|
|
205 Various flags that control how :c:func:`uv_spawn` behaves. See
|
|
|
206 :c:enum:`uv_process_flags`.
|
|
|
207
|
|
|
208 .. c:member:: int uv_process_options_t.stdio_count
|
|
|
209 .. c:member:: uv_stdio_container_t* uv_process_options_t.stdio
|
|
|
210
|
|
|
211 The `stdio` field points to an array of :c:type:`uv_stdio_container_t`
|
|
|
212 structs that describe the file descriptors that will be made available to
|
|
|
213 the child process. The convention is that stdio[0] points to stdin,
|
|
|
214 fd 1 is used for stdout, and fd 2 is stderr.
|
|
|
215
|
|
|
216 .. note::
|
|
|
217 On Windows file descriptors greater than 2 are available to the child process only if
|
|
|
218 the child processes uses the MSVCRT runtime.
|
|
|
219
|
|
|
220 .. c:member:: uv_uid_t uv_process_options_t.uid
|
|
|
221 .. c:member:: uv_gid_t uv_process_options_t.gid
|
|
|
222
|
|
|
223 Libuv can change the child process' user/group id. This happens only when
|
|
|
224 the appropriate bits are set in the flags fields.
|
|
|
225
|
|
|
226 .. note::
|
|
|
227 This is not supported on Windows, :c:func:`uv_spawn` will fail and set the error
|
|
|
228 to ``UV_ENOTSUP``.
|
|
|
229
|
|
|
230 .. c:member:: uv_stdio_flags uv_stdio_container_t.flags
|
|
|
231
|
|
|
232 Flags specifying how the stdio container should be passed to the child.
|
|
|
233
|
|
|
234 .. c:member:: union @0 uv_stdio_container_t.data
|
|
|
235
|
|
|
236 Union containing either the `stream` or `fd` to be passed on to the child
|
|
|
237 process.
|
|
|
238
|
|
|
239
|
|
|
240 API
|
|
|
241 ---
|
|
|
242
|
|
|
243 .. c:function:: void uv_disable_stdio_inheritance(void)
|
|
|
244
|
|
|
245 Disables inheritance for file descriptors / handles that this process
|
|
|
246 inherited from its parent. The effect is that child processes spawned by
|
|
|
247 this process don't accidentally inherit these handles.
|
|
|
248
|
|
|
249 It is recommended to call this function as early in your program as possible,
|
|
|
250 before the inherited file descriptors can be closed or duplicated.
|
|
|
251
|
|
|
252 .. note::
|
|
|
253 This function works on a best-effort basis: there is no guarantee that libuv can discover
|
|
|
254 all file descriptors that were inherited. In general it does a better job on Windows than
|
|
|
255 it does on Unix.
|
|
|
256
|
|
|
257 .. c:function:: int uv_spawn(uv_loop_t* loop, uv_process_t* handle, const uv_process_options_t* options)
|
|
|
258
|
|
|
259 Initializes the process handle and starts the process. If the process is
|
|
|
260 successfully spawned, this function will return 0. Otherwise, the
|
|
|
261 negative error code corresponding to the reason it couldn't spawn is
|
|
|
262 returned.
|
|
|
263
|
|
|
264 Possible reasons for failing to spawn would include (but not be limited to)
|
|
|
265 the file to execute not existing, not having permissions to use the setuid or
|
|
|
266 setgid specified, or not having enough memory to allocate for the new
|
|
|
267 process.
|
|
|
268
|
|
|
269 .. versionchanged:: 1.24.0 Added `UV_PROCESS_WINDOWS_HIDE_CONSOLE` and
|
|
|
270 `UV_PROCESS_WINDOWS_HIDE_GUI` flags.
|
|
|
271
|
|
|
272 .. versionchanged:: 1.48.0 Added the
|
|
|
273 `UV_PROCESS_WINDOWS_FILE_PATH_EXACT_NAME` flag.
|
|
|
274
|
|
|
275 .. c:function:: int uv_process_kill(uv_process_t* handle, int signum)
|
|
|
276
|
|
|
277 Sends the specified signal to the given process handle. Check the documentation
|
|
|
278 on :c:ref:`signal` for signal support, specially on Windows.
|
|
|
279
|
|
|
280 .. c:function:: int uv_kill(int pid, int signum)
|
|
|
281
|
|
|
282 Sends the specified signal to the given PID. Check the documentation
|
|
|
283 on :c:ref:`signal` for signal support, specially on Windows.
|
|
|
284
|
|
|
285 .. c:function:: uv_pid_t uv_process_get_pid(const uv_process_t* handle)
|
|
|
286
|
|
|
287 Returns `handle->pid`.
|
|
|
288
|
|
|
289 .. versionadded:: 1.19.0
|
|
|
290
|
|
|
291 .. seealso:: The :c:type:`uv_handle_t` API functions also apply.
|
