Blame docs/src/process.rst

Packit b5b901
Packit b5b901
.. _process:
Packit b5b901
Packit b5b901
:c:type:`uv_process_t` --- Process handle
Packit b5b901
=========================================
Packit b5b901
Packit b5b901
Process handles will spawn a new process and allow the user to control it and
Packit b5b901
establish communication channels with it using streams.
Packit b5b901
Packit b5b901
Packit b5b901
Data types
Packit b5b901
----------
Packit b5b901
Packit b5b901
.. c:type:: uv_process_t
Packit b5b901
Packit b5b901
    Process handle type.
Packit b5b901
Packit b5b901
.. c:type:: uv_process_options_t
Packit b5b901
Packit b5b901
    Options for spawning the process (passed to :c:func:`uv_spawn`.
Packit b5b901
Packit b5b901
    ::
Packit b5b901
Packit b5b901
        typedef struct uv_process_options_s {
Packit b5b901
            uv_exit_cb exit_cb;
Packit b5b901
            const char* file;
Packit b5b901
            char** args;
Packit b5b901
            char** env;
Packit b5b901
            const char* cwd;
Packit b5b901
            unsigned int flags;
Packit b5b901
            int stdio_count;
Packit b5b901
            uv_stdio_container_t* stdio;
Packit b5b901
            uv_uid_t uid;
Packit b5b901
            uv_gid_t gid;
Packit b5b901
        } uv_process_options_t;
Packit b5b901
Packit b5b901
.. c:type:: void (*uv_exit_cb)(uv_process_t*, int64_t exit_status, int term_signal)
Packit b5b901
Packit b5b901
    Type definition for callback passed in :c:type:`uv_process_options_t` which
Packit b5b901
    will indicate the exit status and the signal that caused the process to
Packit b5b901
    terminate, if any.
Packit b5b901
Packit b5b901
.. c:type:: uv_process_flags
Packit b5b901
Packit b5b901
    Flags to be set on the flags field of :c:type:`uv_process_options_t`.
Packit b5b901
Packit b5b901
    ::
Packit b5b901
Packit b5b901
        enum uv_process_flags {
Packit b5b901
            /*
Packit b5b901
            * Set the child process' user id.
Packit b5b901
            */
Packit b5b901
            UV_PROCESS_SETUID = (1 << 0),
Packit b5b901
            /*
Packit b5b901
            * Set the child process' group id.
Packit b5b901
            */
Packit b5b901
            UV_PROCESS_SETGID = (1 << 1),
Packit b5b901
            /*
Packit b5b901
            * Do not wrap any arguments in quotes, or perform any other escaping, when
Packit b5b901
            * converting the argument list into a command line string. This option is
Packit b5b901
            * only meaningful on Windows systems. On Unix it is silently ignored.
Packit b5b901
            */
Packit b5b901
            UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS = (1 << 2),
Packit b5b901
            /*
Packit b5b901
            * Spawn the child process in a detached state - this will make it a process
Packit b5b901
            * group leader, and will effectively enable the child to keep running after
Packit b5b901
            * the parent exits. Note that the child process will still keep the
Packit b5b901
            * parent's event loop alive unless the parent process calls uv_unref() on
Packit b5b901
            * the child's process handle.
Packit b5b901
            */
Packit b5b901
            UV_PROCESS_DETACHED = (1 << 3),
Packit b5b901
            /*
Packit Service e08953
            * Hide the subprocess window that would normally be created. This option is
Packit Service e08953
            * only meaningful on Windows systems. On Unix it is silently ignored.
Packit Service e08953
            */
Packit Service e08953
            UV_PROCESS_WINDOWS_HIDE = (1 << 4),
Packit Service e08953
            /*
Packit Service e08953
            * Hide the subprocess console window that would normally be created. This 
Packit Service e08953
            * option is only meaningful on Windows systems. On Unix it is silently
Packit Service e08953
            * ignored.
Packit Service e08953
            */
Packit Service e08953
            UV_PROCESS_WINDOWS_HIDE_CONSOLE = (1 << 5),
Packit Service e08953
            /*
Packit Service e08953
            * Hide the subprocess GUI window that would normally be created. This 
Packit b5b901
            * option is only meaningful on Windows systems. On Unix it is silently
Packit b5b901
            * ignored.
Packit b5b901
            */
Packit Service e08953
            UV_PROCESS_WINDOWS_HIDE_GUI = (1 << 6)
Packit b5b901
        };
Packit b5b901
Packit b5b901
.. c:type:: uv_stdio_container_t
Packit b5b901
Packit b5b901
    Container for each stdio handle or fd passed to a child process.
Packit b5b901
Packit b5b901
    ::
Packit b5b901
Packit b5b901
        typedef struct uv_stdio_container_s {
Packit b5b901
            uv_stdio_flags flags;
Packit b5b901
            union {
Packit b5b901
                uv_stream_t* stream;
Packit b5b901
                int fd;
Packit b5b901
            } data;
Packit b5b901
        } uv_stdio_container_t;
Packit b5b901
Packit b5b901
.. c:type:: uv_stdio_flags
Packit b5b901
Packit b5b901
    Flags specifying how a stdio should be transmitted to the child process.
Packit b5b901
Packit b5b901
    ::
Packit b5b901
Packit b5b901
        typedef enum {
Packit b5b901
            UV_IGNORE = 0x00,
Packit b5b901
            UV_CREATE_PIPE = 0x01,
Packit b5b901
            UV_INHERIT_FD = 0x02,
Packit b5b901
            UV_INHERIT_STREAM = 0x04,
Packit b5b901
            /*
Packit b5b901
            * When UV_CREATE_PIPE is specified, UV_READABLE_PIPE and UV_WRITABLE_PIPE
Packit b5b901
            * determine the direction of flow, from the child process' perspective. Both
Packit b5b901
            * flags may be specified to create a duplex data stream.
Packit b5b901
            */
Packit b5b901
            UV_READABLE_PIPE = 0x10,
Packit b5b901
            UV_WRITABLE_PIPE = 0x20
Packit b5b901
            /*
Packit b5b901
             * Open the child pipe handle in overlapped mode on Windows.
Packit b5b901
             * On Unix it is silently ignored.
Packit b5b901
             */
Packit b5b901
            UV_OVERLAPPED_PIPE = 0x40
Packit b5b901
        } uv_stdio_flags;
Packit b5b901
Packit b5b901
Packit b5b901
Public members
Packit b5b901
^^^^^^^^^^^^^^
Packit b5b901
Packit b5b901
.. c:member:: uv_process_t.pid
Packit b5b901
Packit b5b901
    The PID of the spawned process. It's set after calling :c:func:`uv_spawn`.
Packit b5b901
Packit b5b901
.. note::
Packit b5b901
    The :c:type:`uv_handle_t` members also apply.
Packit b5b901
Packit b5b901
.. c:member:: uv_process_options_t.exit_cb
Packit b5b901
Packit b5b901
    Callback called after the process exits.
Packit b5b901
Packit b5b901
.. c:member:: uv_process_options_t.file
Packit b5b901
Packit b5b901
    Path pointing to the program to be executed.
Packit b5b901
Packit b5b901
.. c:member:: uv_process_options_t.args
Packit b5b901
Packit b5b901
    Command line arguments. args[0] should be the path to the program. On
Packit b5b901
    Windows this uses `CreateProcess` which concatenates the arguments into a
Packit b5b901
    string this can cause some strange errors. See the
Packit b5b901
    ``UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS`` flag on :c:type:`uv_process_flags`.
Packit b5b901
Packit b5b901
.. c:member:: uv_process_options_t.env
Packit b5b901
Packit b5b901
    Environment for the new process. If NULL the parents environment is used.
Packit b5b901
Packit b5b901
.. c:member:: uv_process_options_t.cwd
Packit b5b901
Packit b5b901
    Current working directory for the subprocess.
Packit b5b901
Packit b5b901
.. c:member:: uv_process_options_t.flags
Packit b5b901
Packit b5b901
    Various flags that control how :c:func:`uv_spawn` behaves. See
Packit b5b901
    :c:type:`uv_process_flags`.
Packit b5b901
Packit b5b901
.. c:member:: uv_process_options_t.stdio_count
Packit b5b901
.. c:member:: uv_process_options_t.stdio
Packit b5b901
Packit b5b901
    The `stdio` field points to an array of :c:type:`uv_stdio_container_t`
Packit b5b901
    structs that describe the file descriptors that will be made available to
Packit b5b901
    the child process. The convention is that stdio[0] points to stdin,
Packit b5b901
    fd 1 is used for stdout, and fd 2 is stderr.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        On Windows file descriptors greater than 2 are available to the child process only if
Packit b5b901
        the child processes uses the MSVCRT runtime.
Packit b5b901
Packit b5b901
.. c:member:: uv_process_options_t.uid
Packit b5b901
.. c:member:: uv_process_options_t.gid
Packit b5b901
Packit b5b901
    Libuv can change the child process' user/group id. This happens only when
Packit b5b901
    the appropriate bits are set in the flags fields.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        This is not supported on Windows, :c:func:`uv_spawn` will fail and set the error
Packit b5b901
        to ``UV_ENOTSUP``.
Packit b5b901
Packit b5b901
.. c:member:: uv_stdio_container_t.flags
Packit b5b901
Packit b5b901
    Flags specifying how the stdio container should be passed to the child. See
Packit b5b901
    :c:type:`uv_stdio_flags`.
Packit b5b901
Packit b5b901
.. c:member:: uv_stdio_container_t.data
Packit b5b901
Packit b5b901
    Union containing either the stream or fd to be passed on to the child
Packit b5b901
    process.
Packit b5b901
Packit b5b901
Packit b5b901
API
Packit b5b901
---
Packit b5b901
Packit b5b901
.. c:function:: void uv_disable_stdio_inheritance(void)
Packit b5b901
Packit b5b901
    Disables inheritance for file descriptors / handles that this process
Packit b5b901
    inherited from its parent. The effect is that child processes spawned by
Packit b5b901
    this process don't accidentally inherit these handles.
Packit b5b901
Packit b5b901
    It is recommended to call this function as early in your program as possible,
Packit b5b901
    before the inherited file descriptors can be closed or duplicated.
Packit b5b901
Packit b5b901
    .. note::
Packit b5b901
        This function works on a best-effort basis: there is no guarantee that libuv can discover
Packit b5b901
        all file descriptors that were inherited. In general it does a better job on Windows than
Packit b5b901
        it does on Unix.
Packit b5b901
Packit b5b901
.. c:function:: int uv_spawn(uv_loop_t* loop, uv_process_t* handle, const uv_process_options_t* options)
Packit b5b901
Packit b5b901
    Initializes the process handle and starts the process. If the process is
Packit b5b901
    successfully spawned, this function will return 0. Otherwise, the
Packit b5b901
    negative error code corresponding to the reason it couldn't spawn is
Packit b5b901
    returned.
Packit b5b901
Packit b5b901
    Possible reasons for failing to spawn would include (but not be limited to)
Packit b5b901
    the file to execute not existing, not having permissions to use the setuid or
Packit b5b901
    setgid specified, or not having enough memory to allocate for the new
Packit b5b901
    process.
Packit b5b901
Packit Service e08953
    .. versionchanged:: 1.24.0 Added `UV_PROCESS_WINDOWS_HIDE_CONSOLE` and
Packit Service e08953
                        `UV_PROCESS_WINDOWS_HIDE_GUI` flags.
Packit Service e08953
Packit b5b901
.. c:function:: int uv_process_kill(uv_process_t* handle, int signum)
Packit b5b901
Packit b5b901
    Sends the specified signal to the given process handle. Check the documentation
Packit b5b901
    on :c:ref:`signal` for signal support, specially on Windows.
Packit b5b901
Packit b5b901
.. c:function:: int uv_kill(int pid, int signum)
Packit b5b901
Packit b5b901
    Sends the specified signal to the given PID. Check the documentation
Packit b5b901
    on :c:ref:`signal` for signal support, specially on Windows.
Packit b5b901
Packit b5b901
.. c:function:: uv_pid_t uv_process_get_pid(const uv_process_t* handle)
Packit b5b901
Packit b5b901
    Returns `handle->pid`.
Packit b5b901
Packit b5b901
    .. versionadded:: 1.19.0
Packit b5b901
Packit b5b901
.. seealso:: The :c:type:`uv_handle_t` API functions also apply.