libuv » API documentation » uv_process_t — Process

`uv_process_t` — Process handle

进程句柄将产生一个新进程并允许用户控制它并使用流与它建立通信通道。

Data types

uv_process_t

进程句柄类型。

uv_process_options_t

传递给函数uv_spawn()，拥有控制生成子进程的选项。

typedef struct uv_process_options_s {
    uv_exit_cb exit_cb;
    const char* file;
    char** args;
    char** env;
    const char* cwd;
    unsigned int flags;
    int stdio_count;
    uv_stdio_container_t* stdio;
    uv_uid_t uid;
    uv_gid_t gid;
} uv_process_options_t;

typedef void (*uv_exit_cb)(uv_process_t*, int64_t exit_status, int term_signal)

在 uv_process_options_t 中传递的回调函数将在进程退出时被被调用，传给其的参数包括：进程退出状态和导致进程终止的信号（如果有）。

uv_process_flags

要在 uv_process_options_t 的 flags 字段上设置的标志:

enum uv_process_flags {
    /*
    * 设置子进程的UID.
    */
    UV_PROCESS_SETUID = (1 << 0),
    /*
    * 设置子进程的GID.
    */
    UV_PROCESS_SETGID = (1 << 1),
    /*
    * 将参数列表转换为命令行字符串时，请勿将任何参数括在引号中或执行任何其他转义。 此选项仅在 Windows 系统上有意义。 在 Unix 上，它被默默地忽略。
    */
    UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS = (1 << 2),
    /*
    * 以分离状态生成子进程 - 这将使其成为进程组领导，并将有效地使子进程在父进程退出后继续运行。 
    * 请注意，除非父进程在子进程句柄上调用 uv_unref()，否则子进程仍将保持父进程的事件循环处于活动状态。
    */
    UV_PROCESS_DETACHED = (1 << 3),
    /*
    * 隐藏通常会创建的子进程窗口。 此选项仅在 Windows 系统上有意义。 在 Unix 上，它被默默地忽略。
    */
    UV_PROCESS_WINDOWS_HIDE = (1 << 4),
    /*
    * 隐藏通常会创建的子进程控制台窗口。 此选项仅在 Windows 系统上有意义。 在 Unix 上，它被默默地忽略。
    */
    UV_PROCESS_WINDOWS_HIDE_CONSOLE = (1 << 5),
    /*
    * 隐藏通常会创建的子进程 GUI 窗口。 此选项仅在 Windows 系统上有意义。 在 Unix 上，它被默默地忽略。
    */
    UV_PROCESS_WINDOWS_HIDE_GUI = (1 << 6)
};

uv_stdio_container_t

传递给子进程的每个 stdio 句柄或 fd 的容器：

typedef struct uv_stdio_container_s {
    uv_stdio_flags flags;
    union {
        uv_stream_t* stream;
        int fd;
    } data;
} uv_stdio_container_t;

uv_stdio_flags

指定如何将 stdio 传输到子进程的标志。

typedef enum {
    /*
    * 以下四个选项是互斥的，定义了在子进程中对对应的文件描述符要执行的操作：
    */

    /*
    * 不会提供文件描述符（如果它是 fd 0、1 或 2，则将其重定向到 `/dev/null`）。
    */
    UV_IGNORE = 0x00,

    /*
    * 根据下面的标志打开一个新的管道到 `data.stream`。 `data.stream` 字段必须指向已使用 `uv_pipe_init(loop, data.stream, ipc);` 初始化但尚未打开或连接的 uv_pipe_t 对象。
    */
    UV_CREATE_PIPE = 0x01,

    /*
    * 子进程将获得由 `data.fd` 给出的父文件描述符的副本。
    */
    UV_INHERIT_FD = 0x02,

    /*
    * 子进程将获得父进程文件描述符的副本，该文件描述符由 `data.stream` 给出的流句柄使用。
    */
    UV_INHERIT_STREAM = 0x04,

    /*
    * 当指定 UV_CREATE_PIPE 时，UV_READABLE_PIPE 和 UV_WRITABLE_PIPE 从子进程的角度确定流的方向。 可以指定这两个标志来创建双工数据流。
    */
    UV_READABLE_PIPE = 0x10,
    UV_WRITABLE_PIPE = 0x20,

    /*
    * 当指定 UV_CREATE_PIPE 时，指定 UV_NONBLOCK_PIPE 在子进程中以非阻塞模式打开句柄。 这可能会导致数据丢失，如果子进程没有设计为处理遇到这种模式，但也可以显着提高效率。
    */
    UV_NONBLOCK_PIPE = 0x40
} uv_stdio_flags;

Public members

int uv_process_t.pid

生成的进程的 PID。它是在调用 uv_spawn() 之后设置的。

uv_exit_cb uv_process_options_t.exit_cb

进程退出后调用的回调。

const char *uv_process_options_t.file

指向要执行的程序的路径。

*char ** uv_process_options_t.args*

命令行参数。 args[0] 应该是程序的路径。在 Windows 上，这使用 CreateProcess 将参数连接成一个字符串，这可能会导致一些奇怪的错误。请参阅 uv_process_flags 上的 UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS 标志。

int uv_process_options_t.env

子进程的的环境变量。如果为 NULL，则使用父进程的环境。

const char *uv_process_options_t.cwd

子进程的当前工作目录。

unsigned int uv_process_options_t.flags

控制 uv_spawn() 行为方式的各种标志。请参阅 uv_process_flags。

int uv_process_options_t.stdio_count

uv_stdio_container_t uv_process_options_t.stdio

stdio 字段指向一个 uv_stdio_container_t 结构的数组，这些结构描述了可供子进程使用的文件描述符。约定是stdio[0]指向stdin，fd 1 用于stdout，fd 2 是stderr。注意，在 Windows 上，只有当子进程使用 MSVCRT 运行时，大于 2 的文件描述符才可用于子进程。

uv_uid_t uv_process_options_t.uid

uv_gid_t uv_process_options_t.gid

Libuv 可以更改子进程的用户/组 ID。仅当在标志字段中设置了适当的位时才会发生这种情况。WIn中并不支持此设置。

uv_stdio_flags uv_stdio_container_t.flags

指定如何将 stdio 容器传递给子级的标志。

union[anonymous]uv_stdio_container_t.data

包含要传递给子进程的流或 fd 的联合。

API

void uv_disable_stdio_inheritance(void)

禁用此进程从其父进程继承的文件描述符/句柄的继承。结果是由该进程产生的子进程不会意外继承这些句柄。

建议在您的程序中尽可能早地调用此函数，然后才能关闭或复制继承的文件描述符。

这个函数在尽力而为的基础上工作：不能保证 libuv 可以发现所有被继承的文件描述符。一般而言，它在 Windows 上的表现比在 Unix 上的表现要好。

int uv_spawn(uv_loop_t *loop, uv_process_t *handle, const uv_process_options_t *options)

初始化进程句柄并启动进程。如果进程成功生成，此函数将返回 0。否则，返回与无法生成的原因相对应的负错误代码。

未能生成的可能原因包括（但不限于）要执行的文件不存在，没有使用指定的 setuid 或 setgid 的权限，或者没有足够的内存来为新进程分配。

在 1.24.0 版更改：添加了 UV_PROCESS_WINDOWS_HIDE_CONSOLE 和 UV_PROCESS_WINDOWS_HIDE_GUI 标志。

int uv_process_kill(uv_process_t *handle, int signum)

将指定的信号发送到给定的进程句柄。查看有关 uv_signal_t 的文档——信号句柄以获得信号支持，特别是在 Windows 上。

int uv_kill(int pid, int signum)

将指定的信号发送到给定的 PID。查看有关 uv_signal_t 的文档——信号句柄以获得信号支持，特别是在 Windows 上。

uv_pid_t uv_process_get_pid(const uv_process_t *handle)

返回句柄->pid。