Ruff 1.6.0 Documentation
Table of Contents
Child Process#
The child_process
module provides the ability to spawn child processes
By default, pipes for stdin
, stdout
and stderr
are established between
the parent process and the spawned child.
The [child_process.spawn()
][] method spawns the child process asynchronously,
without blocking the event loop.
child_process.spawn(command[, args][, options])#
command
String The command to runargs
Array List of string argumentsoptions
Objectcwd
String Current working directory of the child processenv
Object Environment key-value pairsargv0
String Explicitly set the value ofargv[0]
sent to the child process. This will be set tocommand
if not specified.stdio
Array|String Child's stdio configuration. (See [options.stdio
][stdio
])detached
Boolean Prepare child to run independently of its parent process. Specific behavior depends on the platform, see [options.detached
][])uid
Number Sets the user identity of the process. (See setuid(2).)gid
Number Sets the group identity of the process. (See setgid(2).)
- return: ChildProcess
The child_process.spawn()
method spawns a new process using the given
command
, with command line arguments in args
. If omitted, args
defaults
to an empty array.
A third argument may be used to specify additional options, with these defaults:
{
cwd: undefined,
env: process.env
}
Use cwd
to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory.
Use env
to specify environment variables that will be visible to the new
process, the default is [process.env
][].
Example of running ls -lh /
, capturing stdout
, stderr
, and the
exit code:
const spawn = require('child_process').spawn;
const ls = spawn('ls', ['-lh', '/']);
ls.stdout.on('data', function (data) {
console.log('stdout:', data);
});
ls.stderr.on('data', function (data) {
console.log('stderr:', data);
});
ls.on('exit', function (code) {
console.log('child process exited with code:', code);
});
options.stdio#
The options.stdio
option is used to configure the pipes that are established
between the parent and child process. By default, the child's stdin, stdout,
and stderr are redirected to corresponding [child.stdin
][], [child.stdout
][], and
[child.stderr
][] streams on the [ChildProcess
][] object. This is equivalent to
setting the options.stdio
equal to ['pipe', 'pipe', 'pipe']
.
For convenience, options.stdio
may be one of the following strings:
'pipe'
- equivalent to['pipe', 'pipe', 'pipe']
(the default)'ignore'
- equivalent to['ignore', 'ignore', 'ignore']
'inherit'
- equivalent to[process.stdin, process.stdout, process.stderr]
or[0,1,2]
Otherwise, the value of options.stdio
is an array where each index corresponds
to an fd in the child. The fds 0, 1, and 2 correspond to stdin, stdout,
and stderr, respectively. Additional fds can be specified to create additional
pipes between the parent and child. The value is 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 as a property on thechild_process
object as [child.stdio[fd]
][stdio
]. Pipes created for fds 0 - 2 are also available as [child.stdin
][], [child.stdout
][] and [child.stderr
][], respectively.'ignore'
- Instructs Node.js to ignore the fd in the child. While Node.js will always open fds 0 - 2 for the processes it spawns, setting the fd to'ignore'
will cause Node.js to open/dev/null
and attach it to the child's fd. corresponds to the index in thestdio
array. Note that the stream must have an underlying descriptor (file streams do not until the'open'
event has occurred).- Positive integer - The integer value is interpreted as a file descriptor that is is currently open in the parent process. It is shared with the child process, similar to how {Stream} objects can be shared.
null
,undefined
- Use default value. For stdio fds 0, 1 and 2 (in other words, stdin, stdout, and stderr) a pipe is created. For fd 3 and up, the default is'ignore'
.
Class: ChildProcess#
Instances of the ChildProcess
class are [EventEmitters
][EventEmitter
] that represent
spawned child processes.
Instances of ChildProcess
are not intended to be created directly. Rather,
use the [child_process.spawn()
][], [child_process.exec()
][],
[child_process.execFile()
][], or [child_process.fork()
][] methods to create
instances of ChildProcess
.
Event: 'error'#
err
Error the error.
The 'error'
event is emitted whenever:
- The process could not be spawned, or
- The process could not be killed, or
- Sending a message to the child process failed.
Note that the 'exit'
event may or may not fire after an error has occurred.
If you are listening to both the 'exit'
and 'error'
events, it is important
to guard against accidentally invoking handler functions multiple times.
Event: 'exit'#
code
Number the exit code if the child exited on its own.signal
String the signal by which the child process was terminated.
The 'exit'
event is emitted after the child process ends. If the process
exited, code
is the final exit code of the process, otherwise null
. If the
process terminated due to receipt of a signal, signal
is the string name of
the signal, otherwise null
. One of the two will always be non-null.
child.kill([signal])#
signal
String
child.stderr#
- Stream
A Readable Stream
that represents the child process's stderr
.
child.stdin#
- Stream
A Writable Stream
that represents the child process's stdin
.
child.stdout#
- Stream
A Readable Stream
that represents the child process's stdout
.