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 * 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 170Public 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:type:`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:type:`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 240API 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. 292
