uv_process_t — プロセスハンドル¶

データ型¶

type uv_process_t¶

プロセスハンドルの型です。

type 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。終了ステータスと、プロセスを終了させたシグナルがあればそのシグナルを通知します。

enum uv_process_flags¶

次の型のflagsフィールドに設定するフラグです: uv_process_options_t。

enum uv_process_flags {
    /*
    * Set the child process' user id.
    */
    UV_PROCESS_SETUID = (1 << 0),
    /*
    * Set the child process' group id.
    */
    UV_PROCESS_SETGID = (1 << 1),
    /*
    * Do not wrap any arguments in quotes, or perform any other escaping, when
    * converting the argument list into a command line string. This option is
    * only meaningful on Windows systems. On Unix it is silently ignored.
    */
    UV_PROCESS_WINDOWS_VERBATIM_ARGUMENTS = (1 << 2),
    /*
    * Spawn the child process in a detached state - this will make it a process
    * group leader, and will effectively enable the child to keep running after
    * the parent exits. Note that the child process will still keep the
    * parent's event loop alive unless the parent process calls uv_unref() on
    * the child's process handle.
    */
    UV_PROCESS_DETACHED = (1 << 3),
    /*
    * Hide the subprocess window that would normally be created. This option is
    * only meaningful on Windows systems. On Unix it is silently ignored.
    */
    UV_PROCESS_WINDOWS_HIDE = (1 << 4),
    /*
    * Hide the subprocess console window that would normally be created. This
    * option is only meaningful on Windows systems. On Unix it is silently
    * ignored.
    */
    UV_PROCESS_WINDOWS_HIDE_CONSOLE = (1 << 5),
    /*
    * Hide the subprocess GUI window that would normally be created. This
    * option is only meaningful on Windows systems. On Unix it is silently
    * ignored.
    */
    UV_PROCESS_WINDOWS_HIDE_GUI = (1 << 6),
    /*
     * On Windows, if the path to the program to execute, specified in
     * uv_process_options_t's file field, has a directory component,
     * search for the exact file name before trying variants with
     * extensions like '.exe' or '.cmd'.
     */
    UV_PROCESS_WINDOWS_FILE_PATH_EXACT_NAME = (1 << 7)
};

type uv_stdio_container_t¶

子プロセスに渡す各stdioハンドルまたはファイルディスクリプターのコンテナーです。

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

enum uv_stdio_flags¶

stdioを子プロセスへどのように渡すか指定するフラグです。

typedef enum {
    /*
    * The following four options are mutually-exclusive, and define
    * the operation to perform for the corresponding file descriptor
    * in the child process:
    */

    /*
    * No file descriptor will be provided (or redirected to
    * `/dev/null` if it is fd 0, 1 or 2).
    */
    UV_IGNORE = 0x00,

    /*
    * Open a new pipe into `data.stream`, per the flags below. The
    * `data.stream` field must point to a uv_pipe_t object that has
    * been initialized with `uv_pipe_init(loop, data.stream, ipc);`,
    * but not yet opened or connected.
    /*
    UV_CREATE_PIPE = 0x01,

    /*
    * The child process will be given a duplicate of the parent's
    * file descriptor given by `data.fd`.
    */
    UV_INHERIT_FD = 0x02,

    /*
    * The child process will be given a duplicate of the parent's
    * file descriptor being used by the stream handle given by
    * `data.stream`.
    */
    UV_INHERIT_STREAM = 0x04,

    /*
    * When UV_CREATE_PIPE is specified, UV_READABLE_PIPE and UV_WRITABLE_PIPE
    * determine the direction of flow, from the child process' perspective. Both
    * flags may be specified to create a duplex data stream.
    */
    UV_READABLE_PIPE = 0x10,
    UV_WRITABLE_PIPE = 0x20,

    /*
    * When UV_CREATE_PIPE is specified, specifying UV_NONBLOCK_PIPE opens the
    * handle in non-blocking mode in the child. This may cause loss of data,
    * if the child is not designed to handle to encounter this mode,
    * but can also be significantly more efficient.
    */
    UV_NONBLOCK_PIPE = 0x40
} uv_stdio_flags;

API¶

void uv_disable_stdio_inheritance(void)¶

このプロセスが親から継承したファイルディスクリプターとハンドルの継承を無効にします。これにより、このプロセスが起動する子プロセスに、これらのハンドルを誤って継承させることを防ぎます。

継承したファイルディスクリプターを閉じたり複製したりする前に、プログラムのできるだけ早い段階でこの関数を呼び出すことを推奨します。

注記

この関数は可能な範囲で動作します。libuvが継承されたすべてのファイルディスクリプターを発見できる保証はありません。一般に、UnixよりWindowsでよりよく機能します。

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

プロセスハンドルを初期化し、プロセスを開始します。起動に成功すると0を返します。失敗すると、起動できなかった理由に対応する負のエラーコードを返します。他のlibuvの初期化関数とは異なり、成功・失敗のいずれの場合も、最終的に次の関数を呼び出す必要があります: uv_close()。ハンドルのメモリーを解放する前に、この関数でハンドルを閉じてください。

起動に失敗する理由には、実行するファイルが存在しない、指定したsetuidやsetgidを使う権限がない、新しいプロセスのためのメモリーを確保できない、などがあります。理由はこれらに限りません。

警告

Unixでは、プロセスがまだ終了していない時点で次の関数、uv_closeを呼び出すと、libuvが回収できないゾンビプロセスを作ってしまいます。ユーザーが後で次の関数を呼び出す責任を負います: waitpid。Windowsには関係ありません。

バージョン1.24.0での変更: 次のフラグを追加しました: UV_PROCESS_WINDOWS_HIDE_CONSOLEおよびUV_PROCESS_WINDOWS_HIDE_GUI。

バージョン1.48.0での変更: 次のフラグを追加しました: UV_PROCESS_WINDOWS_FILE_PATH_EXACT_NAME。

int uv_process_kill(uv_process_t *handle, int signum)¶

指定したシグナルを、指定したプロセスハンドルへ送ります。シグナルのサポートについて、特にWindowsでは、次の文書を確認してください: uv_signal_t — シグナルハンドル。

指定したプロセスがすでに終了している場合、同じPIDを再利用した別のプロセスを終了させることはありません。一方、次の関数、uv_killでは、次の関数で取得した値をキャッシュして使うと、無関係な別のプロセスを終了させる場合があります: uv_process_get_pid()。

int uv_kill(int pid, int signum)¶

指定したシグナルを、指定したPIDへ送ります。シグナルのサポートについて、特にWindowsでは、次の文書を確認してください: uv_signal_t — シグナルハンドル。

uv_pid_t uv_process_get_pid(const uv_process_t *handle)¶

次の値を返します: handle->pid。

バージョン1.19.0で追加。