Mercurial

comparison third_party/libuv/docs/src/process.rst @ 160:948de3f54cea

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[ThirdParty] Added libuv
author June Park <parkjune1995@gmail.com>
date Wed, 14 Jan 2026 19:39:52 -0800
parents
children
comparison
equal deleted inserted replaced
159:05cf9467a1c3 160:948de3f54cea
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.