Module base module

module child_process

Subprocess management module

Citation:

1 2
var child_process = require("child_process"); var child = child_process.spawn("ls");

When creating a child process, the options.stdio option is used to configure the pipe established between the parent and child processes. By default, the stdin, stdout, and stderr of the child process are redirected toChildProcessThe corresponding stdin, stdout, and stderr streams on the object. This is equivalent to setting options.stdio to ['pipe', 'pipe', 'pipe'].

For convenience, options.stdio can be one of the following strings:

  • 'pipe': Equivalent to ['pipe', 'pipe', 'pipe'] (default).
  • 'ignore': Equivalent to ['ignore', 'ignore', 'ignore'].
  • 'inherit': Equivalent to ['inherit', 'inherit', 'inherit'] or [0, 1, 2].
  • 'pty': Equivalent to ['pty', 'pty', 'pty']. Windows is not supported.

Otherwise, the value of options.stdio needs to be an array (where each index corresponds to a file descriptor in the child process). File descriptors 0, 1, and 2 correspond to stdin, stdout, and stderr, respectively. Other file descriptors can be specified to create additional pipes between the parent and child processes. The value can be one of the following:

  1. 'pipe': Create a pipe between the child process and the parent process. The parent end of the pipe is exposed to the parent process as the stdio[fd] attribute on the child_process object. Pipes created for file descriptors 0, 1, and 2 are also available as stdin, stdout, and stderr, respectively.
  2. 'ignore': Instructs fibjs to ignore file descriptors in child processes. While fibjs will always have file descriptors 0, 1 and 2 open for its spawned process, setting file descriptors to 'ignore' causes fibjs to open /dev/null and append it to the child process's file descriptor.
  3. 'inherit': Stream the corresponding stdio to or from the parent process. In the first three positions, this is equivalent toprocess.stdin,process.stdoutandprocess.stderr. In any other position, it is equivalent to 'ignore'.
  4. 'pty': The subprocess will be executed in a virtual terminal. Only stdin and stdout are valid at this time.
  5. Positive integer: The integer value is interpreted as the file descriptor currently open in the parent process. It is shared with the child process, similar to share<Stream> object way. Incoming sockets are not supported on Windows.
  6. null or undefined: use the default value. For file descriptors 0, 1, and 2 of stdio (in other words, stdin, stdout, and stderr), pipes will be created. For file descriptors 3 and greater, the default is 'ignore'.
1 2 3 4 5 6 7 8 9 10 11 12 13
const { spawn } = require('child_process'); // 子进程使用父进程的 stdio。 spawn('prg', [], { stdio: 'inherit' }); // 衍生的子进程只共享 stderr。 spawn('prg', [], { stdio: ['pipe', 'pipe', process.stderr] });

For users who use nodejs at the same time, pay attention

  • child_process.exec(command, args)The api of fibjs is similar to the api of the same name of nodejs, but on windows, it does not automatically take cmd.exe as the execution environment of the command parameter;
  • fibjs's child_process.[spawn|exec|execFile|run] is a sync/callback integrated async style function:
    • Synchronous if the last argument is not a function
    • Asynchronous if a function is passed as the last argument;
  • The return result of child_process.[exec|execFile] of fibjs is an object, which is completely different from the object returned by the api of the same name of nodejs
  • There is no corresponding API for fibjs child_process.runin nodejs

static function

spawn

Publish a child process with the given command

1 2 3
static ChildProcess child_process.spawn(String command, Array args, Object options = {});

Call parameters:

  • command: String, specifies the command to run
  • args: Array, specifies a list of string arguments
  • options: Object, specifies the creation parameters

Return result:

The content supported by options is as follows:

1 2 3 4 5 6 7 8 9 10
{ "cwd": "", // 子进程的当前的工作目录,缺省使用当前目录 "stdio": Array | String, // 子进程 stdio 配置 "env": {}, // 环境变量的键值对 "detached": false, // 子进程将会变成一个进程组的领导者,缺省为 false "uid": 0, // 设置用户进程的ID "gid": 0, // 设置进程组的ID "windowsVerbatimArguments": false, // 在 Windows上不执行引号或转义参数。 在 Unix 上被忽略。 当指定外壳且为 CMD 时,此选项将自动设置为true,缺省为 false "windowsHide": false // 隐藏通常在Windows系统上创建的子进程控制台窗口,缺省为 false }

Publish a child process with the given command

1 2
static ChildProcess child_process.spawn(String command, Object options = {});

Call parameters:

  • command: String, specifies the command to run
  • options: Object, specifies the creation parameters

Return result:

The content supported by options is as follows:

1 2 3 4 5 6 7 8 9 10
{ "cwd": "", // 子进程的当前的工作目录,缺省使用当前目录 "stdio": Array | String, // 子进程 stdio 配置 "env": {}, // 环境变量的键值对 "detached": false, // 子进程将会变成一个进程组的领导者,缺省为 false "uid": 0, // 设置用户进程的ID "gid": 0, // 设置进程组的ID "windowsVerbatimArguments": false, // 在 Windows上不执行引号或转义参数。 在 Unix 上被忽略。 当指定外壳且为 CMD 时,此选项将自动设置为true,缺省为 false "windowsHide": false // 隐藏通常在Windows系统上创建的子进程控制台窗口,缺省为 false }

exec

Execute a command in the shell and buffer the output, when executed as a callback, the function will return the subprocess object

1 2
static (Variant stdout, Variant stderr) child_process.exec(String command, Object options = {}) async;

Call parameters:

  • command: String, specifies the command to run
  • options: Object, specifies the creation parameters

Return result:

  • (Variant stdout, Variant stderr), returns the stdio output of the child process

The content supported by options is as follows:

1 2 3 4 5 6 7 8 9 10
{ "cwd": "", // 子进程的当前的工作目录,缺省使用当前目录 "env": {}, // 环境变量的键值对 "encoding": "utf8", // 指定返回结果的编码,缺省为 utf8 "detached": false, // 子进程将会变成一个进程组的领导者,缺省为 false "uid": 0, // 设置用户进程的ID "gid": 0, // 设置进程组的ID "windowsVerbatimArguments": false, // 在 Windows上不执行引号或转义参数。 在 Unix 上被忽略。 当指定外壳且为 CMD 时,此选项将自动设置为true,缺省为 false "windowsHide": false // 隐藏通常在Windows系统上创建的子进程控制台窗口,缺省为 false }

execFile

Execute the specified file directly and buffer the output. When executed in callback mode, the function will return the child process object

1 2 3
static (Variant stdout, Variant stderr) child_process.execFile(String command, Array args, Object options = {}) async;

Call parameters:

  • command: String, specifies the command to run
  • args: Array, specifies a list of string arguments
  • options: Object, specifies the creation parameters

Return result:

  • (Variant stdout, Variant stderr), returns the stdio output of the child process

The content supported by options is as follows:

1 2 3 4 5 6 7 8 9 10
{ "cwd": "", // 子进程的当前的工作目录,缺省使用当前目录 "env": {}, // 环境变量的键值对 "encoding": "utf8", // 指定返回结果的编码,缺省为 utf8 "detached": false, // 子进程将会变成一个进程组的领导者,缺省为 false "uid": 0, // 设置用户进程的ID "gid": 0, // 设置进程组的ID "windowsVerbatimArguments": false, // 在 Windows上不执行引号或转义参数。 在 Unix 上被忽略。 当指定外壳且为 CMD 时,此选项将自动设置为true,缺省为 false "windowsHide": false // 隐藏通常在Windows系统上创建的子进程控制台窗口,缺省为 false }

Execute the specified file directly and buffer the output. When executed in callback mode, the function will return the child process object

1 2
static (Variant stdout, Variant stderr) child_process.execFile(String command, Object options = {}) async;

Call parameters:

  • command: String, specifies the command to run
  • options: Object, specifies the creation parameters

Return result:

  • (Variant stdout, Variant stderr), returns the stdio output of the child process

The content supported by options is as follows:

1 2 3 4 5 6 7 8 9 10
{ "cwd": "", // 子进程的当前的工作目录,缺省使用当前目录 "env": {}, // 环境变量的键值对 "encoding": "utf8", // 指定返回结果的编码,缺省为 utf8 "detached": false, // 子进程将会变成一个进程组的领导者,缺省为 false "uid": 0, // 设置用户进程的ID "gid": 0, // 设置进程组的ID "windowsVerbatimArguments": false, // 在 Windows上不执行引号或转义参数。 在 Unix 上被忽略。 当指定外壳且为 CMD 时,此选项将自动设置为true,缺省为 false "windowsHide": false // 隐藏通常在Windows系统上创建的子进程控制台窗口,缺省为 false }

fork

Execute a module in a child process

1 2 3
static ChildProcess child_process.fork(String module, Array args, Object options = {});

Call parameters:

  • module: String, specifies the command to run
  • args: Array, specifies a list of string arguments
  • options: Object, specifies the creation parameters

Return result:

The content supported by options is as follows:

1 2 3 4 5 6 7 8 9 10
{ "cwd": "", // 子进程的当前的工作目录,缺省使用当前目录 "stdio": Array | String, // 子进程 stdio 配置 "env": {}, // 环境变量的键值对 "detached": false, // 子进程将会变成一个进程组的领导者,缺省为 false "uid": 0, // 设置用户进程的ID "gid": 0, // 设置进程组的ID "windowsVerbatimArguments": false, // 在 Windows上不执行引号或转义参数。 在 Unix 上被忽略。 当指定外壳且为 CMD 时,此选项将自动设置为true,缺省为 false "windowsHide": false // 隐藏通常在Windows系统上创建的子进程控制台窗口,缺省为 false }

Execute a module in a child process

1 2
static ChildProcess child_process.fork(String module, Object options = {});

Call parameters:

  • module: String, specifies the command to run
  • options: Object, specifies the creation parameters

Return result:

The content supported by options is as follows:

1 2 3 4 5 6 7 8 9 10
{ "cwd": "", // 子进程的当前的工作目录,缺省使用当前目录 "stdio": Array | String, // 子进程 stdio 配置 "env": {}, // 环境变量的键值对 "detached": false, // 子进程将会变成一个进程组的领导者,缺省为 false "uid": 0, // 设置用户进程的ID "gid": 0, // 设置进程组的ID "windowsVerbatimArguments": false, // 在 Windows上不执行引号或转义参数。 在 Unix 上被忽略。 当指定外壳且为 CMD 时,此选项将自动设置为true,缺省为 false "windowsHide": false // 隐藏通常在Windows系统上创建的子进程控制台窗口,缺省为 false }

run

Directly execute the specified file and return exitCode, when executed in callback mode, the function will return the child process object

1 2 3
static Integer child_process.run(String command, Array args, Object options = {}) async;

Call parameters:

  • command: String, specifies the command to run
  • args: Array, specifies a list of string arguments
  • options: Object, specifies the creation parameters

Return result:

  • Integer, returns the exitCode of the child process

The content supported by options is as follows:

1 2 3 4 5 6 7 8 9
{ "cwd": "", // 子进程的当前的工作目录,缺省使用当前目录 "env": {}, // 环境变量的键值对 "detached": false, // 子进程将会变成一个进程组的领导者,缺省为 false "uid": 0, // 设置用户进程的ID "gid": 0, // 设置进程组的ID "windowsVerbatimArguments": false, // 在 Windows上不执行引号或转义参数。 在 Unix 上被忽略。 当指定外壳且为 CMD 时,此选项将自动设置为true,缺省为 false "windowsHide": false // 隐藏通常在Windows系统上创建的子进程控制台窗口,缺省为 false }

Directly execute the specified file and return exitCode, when executed in callback mode, the function will return the child process object

1 2
static Integer child_process.run(String command, Object options = {}) async;

Call parameters:

  • command: String, specifies the command to run
  • options: Object, specifies the creation parameters

Return result:

  • Integer, returns the exitCode of the child process

The content supported by options is as follows:

1 2 3 4 5 6 7 8 9
{ "cwd": "", // 子进程的当前的工作目录,缺省使用当前目录 "env": {}, // 环境变量的键值对 "detached": false, // 子进程将会变成一个进程组的领导者,缺省为 false "uid": 0, // 设置用户进程的ID "gid": 0, // 设置进程组的ID "windowsVerbatimArguments": false, // 在 Windows上不执行引号或转义参数。 在 Unix 上被忽略。 当指定外壳且为 CMD 时,此选项将自动设置为true,缺省为 false "windowsHide": false // 隐藏通常在Windows系统上创建的子进程控制台窗口,缺省为 false }