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 pipeline established between the parent process and the child process. 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 other pipes between the parent and child processes. Value can be one of the following:

'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 a stdio[fd] attribute on the child_process object. The pipes created for file descriptors 0, 1, and 2 are also available as stdin, stdout, and stderr, respectively.
'ignore': instructs fibjs to ignore file descriptors in child processes. While fibjs will always open file descriptors 0, 1, and 2 for its spawned processes, setting file descriptors to 'ignore' causes fibjs to open /dev/null and attach it to the child's file descriptor.
'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'.
'pty': The subprocess will be executed in a virtual terminal. Only stdin and stdout are available at this time.
Positive integers: Integer values are interpreted as file descriptors currently open in the parent process. It is shared with child processes, similar to sharing <Stream> Object mode. Incoming sockets are not supported on Windows.
null or undefined: use the default value. For file descriptors 0, 1, and 2 of stdio (in other words, stdin, stdout, and stderr), pipes are created. For file descriptors 3 and higher, 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

The function child_process.exec(command, args)of fibjs is similar to the API of the same name of nodejs, but on windows, cmd.exe is not automatically used as the execution environment of the command parameter;
child_process.[spawn|exec|execFile|run] of fibjs is an async style function integrating synchronization/callback:
- 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 nodejs API with the same name
fibjs has no corresponding API child_process.runin nodejs

static function

spawn

Launch 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 the list of string parameters
options: Object, specifies the creation parameters

return result:

ChildProcess, returns the child process object

The supported content of 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
}

Launch 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:

ChildProcess, returns the child process object

The supported content of 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

Executes a command in the shell and buffers the output. When executed as a callback, the function returns 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 supported content of 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

Directly execute the specified file and buffer the output. When executed as a callback, 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 the list of string parameters
options: Object, specifies the creation parameters

return result:

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

The supported content of 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
}

Directly execute the specified file and buffer the output. When executed as a callback, 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 supported content of 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 subprocess

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 the list of string parameters
options: Object, specifies the creation parameters

return result:

ChildProcess, returns the child process object

The supported content of 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 subprocess

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:

ChildProcess, returns the child process object

The supported content of 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

Execute the specified file directly and return the exitCode, when executed as a callback, 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 the list of string parameters
options: Object, specifies the creation parameters

return result:

Integer, returns the exitCode of the child process

The supported content of 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
}

Execute the specified file directly and return the exitCode, when executed as a callback, 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 supported content of 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
}

development guide

Basic module

built-in object

community module

module child_process

static function

spawn

exec

execFile

fork

run