1fbb2e0a3Schristos 2fbb2e0a3Schristos.. _process: 3fbb2e0a3Schristos 4fbb2e0a3Schristos:c:type:`uv_process_t` --- Process handle 5fbb2e0a3Schristos========================================= 6fbb2e0a3Schristos 7fbb2e0a3SchristosProcess handles will spawn a new process and allow the user to control it and 8fbb2e0a3Schristosestablish communication channels with it using streams. 9fbb2e0a3Schristos 10fbb2e0a3Schristos 11fbb2e0a3SchristosData types 12fbb2e0a3Schristos---------- 13fbb2e0a3Schristos 14fbb2e0a3Schristos.. c:type:: uv_process_t 15fbb2e0a3Schristos 16fbb2e0a3Schristos Process handle type. 17fbb2e0a3Schristos 18fbb2e0a3Schristos.. c:type:: uv_process_options_t 19fbb2e0a3Schristos 20fbb2e0a3Schristos Options for spawning the process (passed to :c:func:`uv_spawn`. 21fbb2e0a3Schristos 22fbb2e0a3Schristos :: 23fbb2e0a3Schristos 24fbb2e0a3Schristos typedef struct uv_process_options_s { 25fbb2e0a3Schristos uv_exit_cb exit_cb; 26fbb2e0a3Schristos const char* file; 27fbb2e0a3Schristos char** args; 28fbb2e0a3Schristos char** env; 29fbb2e0a3Schristos const char* cwd; 30fbb2e0a3Schristos unsigned int flags; 31fbb2e0a3Schristos int stdio_count; 32fbb2e0a3Schristos uv_stdio_container_t* stdio; 33fbb2e0a3Schristos uv_uid_t uid; 34fbb2e0a3Schristos uv_gid_t gid; 35fbb2e0a3Schristos } uv_process_options_t; 36fbb2e0a3Schristos 37fbb2e0a3Schristos.. c:type:: void (*uv_exit_cb)(uv_process_t*, int64_t exit_status, int term_signal) 38fbb2e0a3Schristos 39fbb2e0a3Schristos Type definition for callback passed in :c:type:`uv_process_options_t` which 40fbb2e0a3Schristos will indicate the exit status and the signal that caused the process to 41fbb2e0a3Schristos terminate, if any. 42fbb2e0a3Schristos 43fbb2e0a3Schristos.. c:type:: uv_process_flags 44fbb2e0a3Schristos 45fbb2e0a3Schristos Flags to be set on the flags field of :c:type:`uv_process_options_t`. 46fbb2e0a3Schristos 47fbb2e0a3Schristos :: 48fbb2e0a3Schristos 49fbb2e0a3Schristos enum uv_process_flags { 50fbb2e0a3Schristos /* 51fbb2e0a3Schristos * Set the child process' user id. 52fbb2e0a3Schristos */ 53fbb2e0a3Schristos UV_PROCESS_SETUID = (1 << 0), 54fbb2e0a3Schristos /* 55fbb2e0a3Schristos * Set the child process' group id. 56fbb2e0a3Schristos */ 57fbb2e0a3Schristos UV_PROCESS_SETGID = (1 << 1), 58fbb2e0a3Schristos /* 59fbb2e0a3Schristos * Do not wrap any arguments in quotes, or perform any other escaping, when 60fbb2e0a3Schristos * converting the argument list into a command line string. This option is 61fbb2e0a3Schristos * only meaningful on Windows systems. On Unix it is silently ignored. 62fbb2e0a3Schristos */ 63fbb2e0a3Schristos UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS = (1 << 2), 64fbb2e0a3Schristos /* 65fbb2e0a3Schristos * Spawn the child process in a detached state - this will make it a process 66fbb2e0a3Schristos * group leader, and will effectively enable the child to keep running after 67fbb2e0a3Schristos * the parent exits. Note that the child process will still keep the 68fbb2e0a3Schristos * parent's event loop alive unless the parent process calls uv_unref() on 69fbb2e0a3Schristos * the child's process handle. 70fbb2e0a3Schristos */ 71fbb2e0a3Schristos UV_PROCESS_DETACHED = (1 << 3), 72fbb2e0a3Schristos /* 73fbb2e0a3Schristos * Hide the subprocess window that would normally be created. This option is 74fbb2e0a3Schristos * only meaningful on Windows systems. On Unix it is silently ignored. 75fbb2e0a3Schristos */ 76fbb2e0a3Schristos UV_PROCESS_WINDOWS_HIDE = (1 << 4), 77fbb2e0a3Schristos /* 78fbb2e0a3Schristos * Hide the subprocess console window that would normally be created. This 79fbb2e0a3Schristos * option is only meaningful on Windows systems. On Unix it is silently 80fbb2e0a3Schristos * ignored. 81fbb2e0a3Schristos */ 82fbb2e0a3Schristos UV_PROCESS_WINDOWS_HIDE_CONSOLE = (1 << 5), 83fbb2e0a3Schristos /* 84fbb2e0a3Schristos * Hide the subprocess GUI window that would normally be created. This 85fbb2e0a3Schristos * option is only meaningful on Windows systems. On Unix it is silently 86fbb2e0a3Schristos * ignored. 87fbb2e0a3Schristos */ 88fbb2e0a3Schristos UV_PROCESS_WINDOWS_HIDE_GUI = (1 << 6) 89fbb2e0a3Schristos }; 90fbb2e0a3Schristos 91fbb2e0a3Schristos.. c:type:: uv_stdio_container_t 92fbb2e0a3Schristos 93fbb2e0a3Schristos Container for each stdio handle or fd passed to a child process. 94fbb2e0a3Schristos 95fbb2e0a3Schristos :: 96fbb2e0a3Schristos 97fbb2e0a3Schristos typedef struct uv_stdio_container_s { 98fbb2e0a3Schristos uv_stdio_flags flags; 99fbb2e0a3Schristos union { 100fbb2e0a3Schristos uv_stream_t* stream; 101fbb2e0a3Schristos int fd; 102fbb2e0a3Schristos } data; 103fbb2e0a3Schristos } uv_stdio_container_t; 104fbb2e0a3Schristos 105*b29f2fbfSchristos.. c:enum:: uv_stdio_flags 106fbb2e0a3Schristos 107fbb2e0a3Schristos Flags specifying how a stdio should be transmitted to the child process. 108fbb2e0a3Schristos 109fbb2e0a3Schristos :: 110fbb2e0a3Schristos 111fbb2e0a3Schristos typedef enum { 112*b29f2fbfSchristos /* 113*b29f2fbfSchristos * The following four options are mutually-exclusive, and define 114*b29f2fbfSchristos * the operation to perform for the corresponding file descriptor 115*b29f2fbfSchristos * in the child process: 116*b29f2fbfSchristos */ 117*b29f2fbfSchristos 118*b29f2fbfSchristos /* 119*b29f2fbfSchristos * No file descriptor will be provided (or redirected to 120*b29f2fbfSchristos * `/dev/null` if it is fd 0, 1 or 2). 121*b29f2fbfSchristos */ 122fbb2e0a3Schristos UV_IGNORE = 0x00, 123*b29f2fbfSchristos 124*b29f2fbfSchristos /* 125*b29f2fbfSchristos * Open a new pipe into `data.stream`, per the flags below. The 126*b29f2fbfSchristos * `data.stream` field must point to a uv_pipe_t object that has 127*b29f2fbfSchristos * been initialized with `uv_pipe_init(loop, data.stream, ipc);`, 128*b29f2fbfSchristos * but not yet opened or connected. 129*b29f2fbfSchristos /* 130fbb2e0a3Schristos UV_CREATE_PIPE = 0x01, 131*b29f2fbfSchristos 132*b29f2fbfSchristos /* 133*b29f2fbfSchristos * The child process will be given a duplicate of the parent's 134*b29f2fbfSchristos * file descriptor given by `data.fd`. 135*b29f2fbfSchristos */ 136fbb2e0a3Schristos UV_INHERIT_FD = 0x02, 137*b29f2fbfSchristos 138*b29f2fbfSchristos /* 139*b29f2fbfSchristos * The child process will be given a duplicate of the parent's 140*b29f2fbfSchristos * file descriptor being used by the stream handle given by 141*b29f2fbfSchristos * `data.stream`. 142*b29f2fbfSchristos */ 143fbb2e0a3Schristos UV_INHERIT_STREAM = 0x04, 144*b29f2fbfSchristos 145fbb2e0a3Schristos /* 146fbb2e0a3Schristos * When UV_CREATE_PIPE is specified, UV_READABLE_PIPE and UV_WRITABLE_PIPE 147fbb2e0a3Schristos * determine the direction of flow, from the child process' perspective. Both 148fbb2e0a3Schristos * flags may be specified to create a duplex data stream. 149fbb2e0a3Schristos */ 150fbb2e0a3Schristos UV_READABLE_PIPE = 0x10, 151*b29f2fbfSchristos UV_WRITABLE_PIPE = 0x20, 152*b29f2fbfSchristos 153fbb2e0a3Schristos /* 154*b29f2fbfSchristos * When UV_CREATE_PIPE is specified, specifying UV_NONBLOCK_PIPE opens the 155*b29f2fbfSchristos * handle in non-blocking mode in the child. This may cause loss of data, 156*b29f2fbfSchristos * if the child is not designed to handle to encounter this mode, 157*b29f2fbfSchristos * but can also be significantly more efficient. 158fbb2e0a3Schristos */ 159*b29f2fbfSchristos UV_NONBLOCK_PIPE = 0x40 160fbb2e0a3Schristos } uv_stdio_flags; 161fbb2e0a3Schristos 162fbb2e0a3Schristos 163fbb2e0a3SchristosPublic members 164fbb2e0a3Schristos^^^^^^^^^^^^^^ 165fbb2e0a3Schristos 166*b29f2fbfSchristos.. c:member:: int uv_process_t.pid 167fbb2e0a3Schristos 168fbb2e0a3Schristos The PID of the spawned process. It's set after calling :c:func:`uv_spawn`. 169fbb2e0a3Schristos 170fbb2e0a3Schristos.. note:: 171fbb2e0a3Schristos The :c:type:`uv_handle_t` members also apply. 172fbb2e0a3Schristos 173*b29f2fbfSchristos.. c:member:: uv_exit_cb uv_process_options_t.exit_cb 174fbb2e0a3Schristos 175fbb2e0a3Schristos Callback called after the process exits. 176fbb2e0a3Schristos 177*b29f2fbfSchristos.. c:member:: const char* uv_process_options_t.file 178fbb2e0a3Schristos 179fbb2e0a3Schristos Path pointing to the program to be executed. 180fbb2e0a3Schristos 181*b29f2fbfSchristos.. c:member:: char** uv_process_options_t.args 182fbb2e0a3Schristos 183fbb2e0a3Schristos Command line arguments. args[0] should be the path to the program. On 184fbb2e0a3Schristos Windows this uses `CreateProcess` which concatenates the arguments into a 185fbb2e0a3Schristos string this can cause some strange errors. See the 186fbb2e0a3Schristos ``UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS`` flag on :c:type:`uv_process_flags`. 187fbb2e0a3Schristos 188*b29f2fbfSchristos.. c:member:: char** uv_process_options_t.env 189fbb2e0a3Schristos 190fbb2e0a3Schristos Environment for the new process. If NULL the parents environment is used. 191fbb2e0a3Schristos 192*b29f2fbfSchristos.. c:member:: const char* uv_process_options_t.cwd 193fbb2e0a3Schristos 194fbb2e0a3Schristos Current working directory for the subprocess. 195fbb2e0a3Schristos 196*b29f2fbfSchristos.. c:member:: unsigned int uv_process_options_t.flags 197fbb2e0a3Schristos 198fbb2e0a3Schristos Various flags that control how :c:func:`uv_spawn` behaves. See 199fbb2e0a3Schristos :c:type:`uv_process_flags`. 200fbb2e0a3Schristos 201*b29f2fbfSchristos.. c:member:: int uv_process_options_t.stdio_count 202*b29f2fbfSchristos.. c:member:: uv_stdio_container_t* uv_process_options_t.stdio 203fbb2e0a3Schristos 204fbb2e0a3Schristos The `stdio` field points to an array of :c:type:`uv_stdio_container_t` 205fbb2e0a3Schristos structs that describe the file descriptors that will be made available to 206fbb2e0a3Schristos the child process. The convention is that stdio[0] points to stdin, 207fbb2e0a3Schristos fd 1 is used for stdout, and fd 2 is stderr. 208fbb2e0a3Schristos 209fbb2e0a3Schristos .. note:: 210fbb2e0a3Schristos On Windows file descriptors greater than 2 are available to the child process only if 211fbb2e0a3Schristos the child processes uses the MSVCRT runtime. 212fbb2e0a3Schristos 213*b29f2fbfSchristos.. c:member:: uv_uid_t uv_process_options_t.uid 214*b29f2fbfSchristos.. c:member:: uv_gid_t uv_process_options_t.gid 215fbb2e0a3Schristos 216fbb2e0a3Schristos Libuv can change the child process' user/group id. This happens only when 217fbb2e0a3Schristos the appropriate bits are set in the flags fields. 218fbb2e0a3Schristos 219fbb2e0a3Schristos .. note:: 220fbb2e0a3Schristos This is not supported on Windows, :c:func:`uv_spawn` will fail and set the error 221fbb2e0a3Schristos to ``UV_ENOTSUP``. 222fbb2e0a3Schristos 223*b29f2fbfSchristos.. c:member:: uv_stdio_flags uv_stdio_container_t.flags 224fbb2e0a3Schristos 225*b29f2fbfSchristos Flags specifying how the stdio container should be passed to the child. 226fbb2e0a3Schristos 227*b29f2fbfSchristos.. c:member:: union @0 uv_stdio_container_t.data 228fbb2e0a3Schristos 229*b29f2fbfSchristos Union containing either the `stream` or `fd` to be passed on to the child 230fbb2e0a3Schristos process. 231fbb2e0a3Schristos 232fbb2e0a3Schristos 233fbb2e0a3SchristosAPI 234fbb2e0a3Schristos--- 235fbb2e0a3Schristos 236fbb2e0a3Schristos.. c:function:: void uv_disable_stdio_inheritance(void) 237fbb2e0a3Schristos 238fbb2e0a3Schristos Disables inheritance for file descriptors / handles that this process 239fbb2e0a3Schristos inherited from its parent. The effect is that child processes spawned by 240fbb2e0a3Schristos this process don't accidentally inherit these handles. 241fbb2e0a3Schristos 242fbb2e0a3Schristos It is recommended to call this function as early in your program as possible, 243fbb2e0a3Schristos before the inherited file descriptors can be closed or duplicated. 244fbb2e0a3Schristos 245fbb2e0a3Schristos .. note:: 246fbb2e0a3Schristos This function works on a best-effort basis: there is no guarantee that libuv can discover 247fbb2e0a3Schristos all file descriptors that were inherited. In general it does a better job on Windows than 248fbb2e0a3Schristos it does on Unix. 249fbb2e0a3Schristos 250fbb2e0a3Schristos.. c:function:: int uv_spawn(uv_loop_t* loop, uv_process_t* handle, const uv_process_options_t* options) 251fbb2e0a3Schristos 252fbb2e0a3Schristos Initializes the process handle and starts the process. If the process is 253fbb2e0a3Schristos successfully spawned, this function will return 0. Otherwise, the 254fbb2e0a3Schristos negative error code corresponding to the reason it couldn't spawn is 255fbb2e0a3Schristos returned. 256fbb2e0a3Schristos 257fbb2e0a3Schristos Possible reasons for failing to spawn would include (but not be limited to) 258fbb2e0a3Schristos the file to execute not existing, not having permissions to use the setuid or 259fbb2e0a3Schristos setgid specified, or not having enough memory to allocate for the new 260fbb2e0a3Schristos process. 261fbb2e0a3Schristos 262fbb2e0a3Schristos .. versionchanged:: 1.24.0 Added `UV_PROCESS_WINDOWS_HIDE_CONSOLE` and 263fbb2e0a3Schristos `UV_PROCESS_WINDOWS_HIDE_GUI` flags. 264fbb2e0a3Schristos 265fbb2e0a3Schristos.. c:function:: int uv_process_kill(uv_process_t* handle, int signum) 266fbb2e0a3Schristos 267fbb2e0a3Schristos Sends the specified signal to the given process handle. Check the documentation 268fbb2e0a3Schristos on :c:ref:`signal` for signal support, specially on Windows. 269fbb2e0a3Schristos 270fbb2e0a3Schristos.. c:function:: int uv_kill(int pid, int signum) 271fbb2e0a3Schristos 272fbb2e0a3Schristos Sends the specified signal to the given PID. Check the documentation 273fbb2e0a3Schristos on :c:ref:`signal` for signal support, specially on Windows. 274fbb2e0a3Schristos 275fbb2e0a3Schristos.. c:function:: uv_pid_t uv_process_get_pid(const uv_process_t* handle) 276fbb2e0a3Schristos 277fbb2e0a3Schristos Returns `handle->pid`. 278fbb2e0a3Schristos 279fbb2e0a3Schristos .. versionadded:: 1.19.0 280fbb2e0a3Schristos 281fbb2e0a3Schristos.. seealso:: The :c:type:`uv_handle_t` API functions also apply. 282