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