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