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:type:: 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 * Open the child pipe handle in overlapped mode on Windows. 125 * On Unix it is silently ignored. 126 */ 127 UV_OVERLAPPED_PIPE = 0x40 128 } uv_stdio_flags; 129 130 131Public members 132^^^^^^^^^^^^^^ 133 134.. c:member:: uv_process_t.pid 135 136 The PID of the spawned process. It's set after calling :c:func:`uv_spawn`. 137 138.. note:: 139 The :c:type:`uv_handle_t` members also apply. 140 141.. c:member:: uv_process_options_t.exit_cb 142 143 Callback called after the process exits. 144 145.. c:member:: uv_process_options_t.file 146 147 Path pointing to the program to be executed. 148 149.. c:member:: uv_process_options_t.args 150 151 Command line arguments. args[0] should be the path to the program. On 152 Windows this uses `CreateProcess` which concatenates the arguments into a 153 string this can cause some strange errors. See the 154 ``UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS`` flag on :c:type:`uv_process_flags`. 155 156.. c:member:: uv_process_options_t.env 157 158 Environment for the new process. If NULL the parents environment is used. 159 160.. c:member:: uv_process_options_t.cwd 161 162 Current working directory for the subprocess. 163 164.. c:member:: uv_process_options_t.flags 165 166 Various flags that control how :c:func:`uv_spawn` behaves. See 167 :c:type:`uv_process_flags`. 168 169.. c:member:: uv_process_options_t.stdio_count 170.. c:member:: uv_process_options_t.stdio 171 172 The `stdio` field points to an array of :c:type:`uv_stdio_container_t` 173 structs that describe the file descriptors that will be made available to 174 the child process. The convention is that stdio[0] points to stdin, 175 fd 1 is used for stdout, and fd 2 is stderr. 176 177 .. note:: 178 On Windows file descriptors greater than 2 are available to the child process only if 179 the child processes uses the MSVCRT runtime. 180 181.. c:member:: uv_process_options_t.uid 182.. c:member:: uv_process_options_t.gid 183 184 Libuv can change the child process' user/group id. This happens only when 185 the appropriate bits are set in the flags fields. 186 187 .. note:: 188 This is not supported on Windows, :c:func:`uv_spawn` will fail and set the error 189 to ``UV_ENOTSUP``. 190 191.. c:member:: uv_stdio_container_t.flags 192 193 Flags specifying how the stdio container should be passed to the child. See 194 :c:type:`uv_stdio_flags`. 195 196.. c:member:: uv_stdio_container_t.data 197 198 Union containing either the stream or fd to be passed on to the child 199 process. 200 201 202API 203--- 204 205.. c:function:: void uv_disable_stdio_inheritance(void) 206 207 Disables inheritance for file descriptors / handles that this process 208 inherited from its parent. The effect is that child processes spawned by 209 this process don't accidentally inherit these handles. 210 211 It is recommended to call this function as early in your program as possible, 212 before the inherited file descriptors can be closed or duplicated. 213 214 .. note:: 215 This function works on a best-effort basis: there is no guarantee that libuv can discover 216 all file descriptors that were inherited. In general it does a better job on Windows than 217 it does on Unix. 218 219.. c:function:: int uv_spawn(uv_loop_t* loop, uv_process_t* handle, const uv_process_options_t* options) 220 221 Initializes the process handle and starts the process. If the process is 222 successfully spawned, this function will return 0. Otherwise, the 223 negative error code corresponding to the reason it couldn't spawn is 224 returned. 225 226 Possible reasons for failing to spawn would include (but not be limited to) 227 the file to execute not existing, not having permissions to use the setuid or 228 setgid specified, or not having enough memory to allocate for the new 229 process. 230 231 .. versionchanged:: 1.24.0 Added `UV_PROCESS_WINDOWS_HIDE_CONSOLE` and 232 `UV_PROCESS_WINDOWS_HIDE_GUI` flags. 233 234.. c:function:: int uv_process_kill(uv_process_t* handle, int signum) 235 236 Sends the specified signal to the given process handle. Check the documentation 237 on :c:ref:`signal` for signal support, specially on Windows. 238 239.. c:function:: int uv_kill(int pid, int signum) 240 241 Sends the specified signal to the given PID. Check the documentation 242 on :c:ref:`signal` for signal support, specially on Windows. 243 244.. c:function:: uv_pid_t uv_process_get_pid(const uv_process_t* handle) 245 246 Returns `handle->pid`. 247 248 .. versionadded:: 1.19.0 249 250.. seealso:: The :c:type:`uv_handle_t` API functions also apply. 251