module child_process

Subprocess management module

Quote:

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 process and the child process. By default, the child process's stdin, stdout, and stderr 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 process and the child process. The 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 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.
'ignore': Instructs fibjs to ignore file descriptors in child processes. Although fibjs will always open file descriptors 0, 1, and 2 for its spawned processes, setting the file descriptor to 'ignore' causes fibjs to open /dev/null and append it to the child process'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, equivalent to 'ignore'.
'pty': The child process will be executed in a virtual terminal. At this time only stdin and stdout are valid.
Positive integer: The integer value will be interpreted as the file descriptor currently open in the parent process. It is shared with the child process, similar to sharing <Stream> Object way. Incoming sockets are not supported on Windows.
null or undefined: use the default value. Pipes are created for file descriptors 0, 1, and 2 of stdio (in other words, stdin, stdout, and stderr). For file descriptors 3 and above, the default is 'ignore'.

1
2
3
4
5
6
7
8
9
10
11
12
13
const {
    spawn
} = require('child_process');

// child process uses parent's stdio
spawn('prg', [], {
    stdio: 'inherit'
});

// child process uses parent's stderr
spawn('prg', [], {
    stdio: ['pipe', 'pipe', process.stderr]
});

For users who also use nodejs, please note that

The function of fibjs's child_process.exec(command, args)API with the same name is similar to that of nodejs, but on Windows, cmd.exe will not be automatically used as the execution environment of the command parameter;
fibjs's child_process.[spawn|exec|execFile|run] is an async style function that integrates synchronization/callback:
- If the last parameter is not a function, it is synchronized
- If a function is passed as the last parameter, it is asynchronous;
The return result of fibjs's child_process.[exec|execFile] is an object, which is completely different from the object returned by the nodejs API with the same name.
fibjs child_process.runhas no corresponding API in 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 the string parameter list
options: Object, specify creation parameters

Return results:

ChildProcess, returns the child process object

The options supported are as follows:

1
2
3
4
5
6
7
8
9
10{
    "cwd": "", // working directory of the child process, default to current directory
    "stdio": Array | String, // working directory of the child process, default to current directory
    "env": {}, // key-value pairs of environment variables to add to the child's environment
    "detached": false, // child process will be a leader of a new process group, default to false
    "uid": 0, // configure the user identity of the process
    "gid": 0, // configure the group identity of the process
    "windowsVerbatimArguments": false, // do not execute any quote or escape processing on Windows. Ignored on Unix. When specified, the command line string is passed directly to the underlying operating system shell without any processing whatsoever. This is set to true automatically when the shell option is specified and is CMD.
    "windowsHide": false // hide the subprocess console window that would normally be created on Windows systems. This option has no effect on non-Windows systems.
}

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, specify creation parameters

Return results:

ChildProcess, returns the child process object

The options supported are as follows:

1
2
3
4
5
6
7
8
9
10{
    "cwd": "", // working directory of the child process, default to current directory
    "stdio": Array | String, // working directory of the child process, default to current directory
    "env": {}, // key-value pairs of environment variables to add to the child's environment
    "detached": false, // child process will be a leader of a new process group, default to false
    "uid": 0, // configure the user identity of the process
    "gid": 0, // con
    "windowsVerbatimArguments": false, // do not execute any quote or escape processing on Windows. Ignored on Unix. When specified, the command line string is passed directly to the underlying operating system shell without any processing whatsoever. This is set to true automatically when the shell option is specified and is CMD.
    "windowsHide": false // hide the subprocess console window that would normally be created on Windows systems. This option has no effect on non-Windows systems.
}

exec

Execute a command in the shell 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.exec(String command,
    Object options = {}) async;

Call parameters:

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

Return results:

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

The options supported are as follows:

1
2
3
4
5
6
7
8
9
10{
    "cwd": "", // working directory of the child process, default to current directory
    "env": {}, // key-value pairs of environment variables to add to the child's environment
    "encoding": "utf8", // specify the character encoding used to decode the stdout and stderr output
    "detached": false, // child process will be a leader of a new process group, default to false
    "uid": 0, // configure the user identity of the process
    "gid": 0, // con
    "windowsVerbatimArguments": false, // do not execute any quote or escape processing on Windows. Ignored on Unix. When specified, the command line string is passed directly to the underlying operating system shell without any processing whatsoever. This is set to true automatically when the shell option is specified and is CMD.
    "windowsHide": false // hide the subprocess console window that would normally be created on Windows systems. This option has no effect on non-Windows systems.
}

execFile

Directly execute the specified file 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 the string parameter list
options: Object, specify creation parameters

Return results:

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

The options supported are as follows:

1
2
3
4
5
6
7
8
9
10{
    "cwd": "", // working directory of the child process, default to current directory
    "env": {}, // key-value pairs of environment variables to add to the child's environment
    "encoding": "utf8", // specify the character encoding used to decode the stdout and stderr output
    "detached": false, // child process will be a leader of a new process group, default to false
    "uid": 0, // configure the user identity of the process
    "gid": 0, // con
    "windowsVerbatimArguments": false, // do not execute any quote or escape processing on Windows. Ignored on Unix. When specified, the command line string is passed directly to the underlying operating system shell without any processing whatsoever. This is set to true automatically when the shell option is specified and is CMD.
    "windowsHide": false // hide the subprocess console window that would normally be created on Windows systems. This option has no effect on non-Windows systems.
}

Directly execute the specified file 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, specify creation parameters

Return results:

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

The options supported are as follows:

1
2
3
4
5
6
7
8
9
10{
    "cwd": "", // working directory of the child process, default to current directory
    "env": {}, // key-value pairs of environment variables to add to the child's environment
    "encoding": "utf8", // specify the character encoding used to decode the stdout and stderr output
    "detached": false, // child process will be a leader of a new process group, default to false
    "uid": 0, // configure the user identity of the process
    "gid": 0, // con
    "windowsVerbatimArguments": false, // do not execute any quote or escape processing on Windows. Ignored on Unix. When specified, the command line string is passed directly to the underlying operating system shell without any processing whatsoever. This is set to true automatically when the shell option is specified and is CMD.
    "windowsHide": false // hide the subprocess console window that would normally be created on Windows systems. This option has no effect on non-Windows systems.
}

spawnSync

Publish a child process with the given command

1
2
3
static (Integer pid, NArray output, Variant stdout, Variant stderr, Integer status, Variant error) child_process.spawnSync(String command,
    Array args,
    Object options = {}) async;

Call parameters:

command: String, specifies the command to run
args: Array, specifies the string parameter list
options: Object, specify creation parameters

Return results:

(Integer pid, NArray output, Variant stdout, Variant stderr, Integer status, Variant error), returns the child process running result

The options supported are as follows:

1
2
3
4
5
6
7
8
9
10{
    "cwd": "", // working directory of the child process, default to current directory
    "stdio": Array | String, // working directory of the child process, default to current directory
    "env": {}, // key-value pairs of environment variables to add to the child's environment
    "detached": false, // child process will be a leader of a new process group, default to false
    "uid": 0, // configure the user identity of the process
    "gid": 0, // configure the group identity of the process
    "windowsVerbatimArguments": false, // do not execute any quote or escape processing on Windows. Ignored on Unix. When specified, the command line string is passed directly to the underlying operating system shell without any processing whatsoever. This is set to true automatically when the shell option is specified and is CMD.
    "windowsHide": false // hide the subprocess console window that would normally be created on Windows systems. This option has no effect on non-Windows systems.
}

Publish a child process with the given command

1
2
static (Integer pid, NArray output, Variant stdout, Variant stderr, Integer status, Variant error) child_process.spawnSync(String command,
    Object options = {}) async;

Call parameters:

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

Return results:

(Integer pid, NArray output, Variant stdout, Variant stderr, Integer status, Variant error), returns the child process running result

The options supported are as follows:

1
2
3
4
5
6
7
8
9
10{
    "cwd": "", // working directory of the child process, default to current directory
    "stdio": Array | String, // working directory of the child process, default to current directory
    "env": {}, // key-value pairs of environment variables to add to the child's environment
    "detached": false, // child process will be a leader of a new process group, default to false
    "uid": 0, // configure the user identity of the process
    "gid": 0, // con
    "windowsVerbatimArguments": false, // do not execute any quote or escape processing on Windows. Ignored on Unix. When specified, the command line string is passed directly to the underlying operating system shell without any processing whatsoever. This is set to true automatically when the shell option is specified and is CMD.
    "windowsHide": false // hide the subprocess console window that would normally be created on Windows systems. This option has no effect on non-Windows systems.
}

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

Return results:

ChildProcess, returns the child process object

The options supported are as follows:

1
2
3
4
5
6
7
8
9
10{
    "cwd": "", // working directory of the child process, default to current directory
    "stdio": Array | String, // working directory of the child process, default to current directory
    "env": {}, // key-value pairs of environment variables to add to the child's environment
    "detached": false, // child process will be a leader of a new process group, default to false
    "uid": 0, // configure the user identity of the process
    "gid": 0, // con
    "windowsVerbatimArguments": false, // do not execute any quote or escape processing on Windows. Ignored on Unix. When specified, the command line string is passed directly to the underlying operating system shell without any processing whatsoever. This is set to true automatically when the shell option is specified and is CMD.
    "windowsHide": false // hide the subprocess console window that would normally be created on Windows systems. This option has no effect on non-Windows systems.
}

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, specify creation parameters

Return results:

ChildProcess, returns the child process object

The options supported are as follows:

1
2
3
4
5
6
7
8
9
10{
    "cwd": "", // working directory of the child process, default to current directory
    "stdio": Array | String, // working directory of the child process, default to current directory
    "env": {}, // key-value pairs of environment variables to add to the child's environment
    "detached": false, // child process will be a leader of a new process group, default to false
    "uid": 0, // configure the user identity of the process
    "gid": 0, // con
    "windowsVerbatimArguments": false, // do not execute any quote or escape processing on Windows. Ignored on Unix. When specified, the command line string is passed directly to the underlying operating system shell without any processing whatsoever. This is set to true automatically when the shell option is specified and is CMD.
    "windowsHide": false // hide the subprocess console window that would normally be created on Windows systems. This option has no effect on non-Windows systems.
}

run

Directly execute the specified file and return the 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 the string parameter list
options: Object, specify creation parameters

Return results:

Integer, returns the exitCode of the child process

The options supported are as follows:

1
2
3
4
5
6
7
8
9{
    "cwd": "", // working directory of the child process, default to current directory
    "env": {}, // key-value pairs of environment variables to add to the child's environment
    "detached": false, // child process will be a leader of a new process group, default to false
    "uid": 0, // configure the user identity of the process
    "gid": 0, // con
    "windowsVerbatimArguments": false, // do not execute any quote or escape processing on Windows. Ignored on Unix. When specified, the command line string is passed directly to the underlying operating system shell without any processing whatsoever. This is set to true automatically when the shell option is specified and is CMD.
    "windowsHide": false // hide the subprocess console window that would normally be created on Windows systems. This option has no effect on non-Windows systems.
}

Directly execute the specified file and return the 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, specify creation parameters

Return results:

Integer, returns the exitCode of the child process

The options supported are as follows:

1
2
3
4
5
6
7
8
9{
    "cwd": "", // working directory of the child process, default to current directory
    "env": {}, // key-value pairs of environment variables to add to the child's environment
    "detached": false, // child process will be a leader of a new process group, default to false
    "uid": 0, // configure the user identity of the process
    "gid": 0, // con
    "windowsVerbatimArguments": false, // do not execute any quote or escape processing on Windows. Ignored on Unix. When specified, the command line string is passed directly to the underlying operating system shell without any processing whatsoever. This is set to true automatically when the shell option is specified and is CMD.
    "windowsHide": false // hide the subprocess console window that would normally be created on Windows systems. This option has no effect on non-Windows systems.
}

Development Guide

Basic module

built-in objects

community module

module child_process

static function

spawn

exec

execFile

spawnSync

fork

run