doc: improvements to child_process, process docs
Sort links in lexical order. Add missing links. Add `disconnect` event description in Process doc. Fix typos. R-URL: https://github.com/nodejs/node/pull/5075 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Robert Jefe Lindstädt <robert.lindstaedt@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io>
This commit is contained in:
Alexander Makarenko
James M Snell
parent
f6d90a912b
commit
f85412d49b
@ -3,8 +3,8 @@
|
||||
Stability: 2 - Stable
|
||||
|
||||
The `child_process` module provides the ability to spawn child processes in
|
||||
a manner that is similar, but not identical, to [`popen(3)`][]. This capability
|
||||
is primarily provided by the `child_process.spawn()` function:
|
||||
a manner that is similar, but not identical, to popen(3). This capability
|
||||
is primarily provided by the [`child_process.spawn()`][] function:
|
||||
|
||||
```js
|
||||
const spawn = require('child_process').spawn;
|
||||
@ -29,27 +29,27 @@ through these pipes in a non-blocking way. *Note, however, that some programs
|
||||
use line-buffered I/O internally. While that does not affect Node.js, it can
|
||||
mean that data sent to the child process may not be immediately consumed.*
|
||||
|
||||
The `child_process.spawn()` method spawns the child process asynchronously,
|
||||
without blocking the Node.js event loop. The `child_process.spawnSync()`
|
||||
The [`child_process.spawn()`][] method spawns the child process asynchronously,
|
||||
without blocking the Node.js event loop. The [`child_process.spawnSync()`][]
|
||||
function provides equivalent functionality in a synchronous manner that blocks
|
||||
the event loop until the spawned process either exits or is terminated.
|
||||
|
||||
For convenience, the `child_process` module provides a handful of synchronous
|
||||
and asynchronous alternatives to [`child_process.spawn()`][] and
|
||||
[`child_process.spawnSync()`][]. *Note that each of these alternatives are
|
||||
implemented on top of `child_process.spawn()` or `child_process.spawnSync()`.*
|
||||
implemented on top of [`child_process.spawn()`][] or [`child_process.spawnSync()`][].*
|
||||
|
||||
* `child_process.exec()`: spawns a shell and runs a command within that shell,
|
||||
* [`child_process.exec()`][]: spawns a shell and runs a command within that shell,
|
||||
passing the `stdout` and `stderr` to a callback function when complete.
|
||||
* `child_process.execFile()`: similar to `child_process.exec()` except that
|
||||
* [`child_process.execFile()`][]: similar to [`child_process.exec()`][] except that
|
||||
it spawns the command directly without first spawning a shell.
|
||||
* `child_process.fork()`: spawns a new Node.js process and invokes a
|
||||
* [`child_process.fork()`][]: spawns a new Node.js process and invokes a
|
||||
specified module with an IPC communication channel established that allows
|
||||
sending messages between parent and child.
|
||||
* `child_process.execSync()`: a synchronous version of
|
||||
`child_process.exec()` that *will* block the Node.js event loop.
|
||||
* `child_process.execFileSync()`: a synchronous version of
|
||||
`child_process.execFile()` that *will* block the Node.js event loop.
|
||||
* [`child_process.execSync()`][]: a synchronous version of
|
||||
[`child_process.exec()`][] that *will* block the Node.js event loop.
|
||||
* [`child_process.execFileSync()`][]: a synchronous version of
|
||||
[`child_process.execFile()`][] that *will* block the Node.js event loop.
|
||||
|
||||
For certain use cases, such as automating shell scripts, the
|
||||
[synchronous counterparts][] may be more convenient. In many cases, however,
|
||||
@ -58,8 +58,8 @@ stalling the event loop while spawned processes complete.
|
||||
|
||||
## Asynchronous Process Creation
|
||||
|
||||
The `child_process.spawn()`, `child_process.fork()`, `child_process.exec()`,
|
||||
and `child_process.execFile()` methods all follow the idiomatic asynchronous
|
||||
The [`child_process.spawn()`][], [`child_process.fork()`][], [`child_process.exec()`][],
|
||||
and [`child_process.execFile()`][] methods all follow the idiomatic asynchronous
|
||||
programming pattern typical of other Node.js APIs.
|
||||
|
||||
Each of the methods returns a [`ChildProcess`][] instance. These objects
|
||||
@ -67,22 +67,22 @@ implement the Node.js [`EventEmitter`][] API, allowing the parent process to
|
||||
register listener functions that are called when certain events occur during
|
||||
the life cycle of the child process.
|
||||
|
||||
The `child_process.exec()` and `child_process.execFile()` methods additionally
|
||||
The [`child_process.exec()`][] and [`child_process.execFile()`][] methods additionally
|
||||
allow for an optional `callback` function to be specified that is invoked
|
||||
when the child process terminates.
|
||||
|
||||
### Spawning `.bat` and `.cmd` files on Windows
|
||||
|
||||
The importance of the distinction between `child_process.exec()` and
|
||||
`child_process.execFile()` can vary based on platform. On Unix-type operating
|
||||
systems (Unix, Linux, OSX) `child_process.execFile()` can be more efficient
|
||||
The importance of the distinction between [`child_process.exec()`][] and
|
||||
[`child_process.execFile()`][] can vary based on platform. On Unix-type operating
|
||||
systems (Unix, Linux, OSX) [`child_process.execFile()`][] can be more efficient
|
||||
because it does not spawn a shell. On Windows, however, `.bat` and `.cmd`
|
||||
files are not executable on their own without a terminal, and therefore cannot
|
||||
be launched using `child_process.execFile()`. When running on Windows, `.bat`
|
||||
and `.cmd` files can be invoked using `child_process.spawn()` with the `shell`
|
||||
option set, with `child_process.exec()`, or by spawning `cmd.exe` and passing
|
||||
be launched using [`child_process.execFile()`][]. When running on Windows, `.bat`
|
||||
and `.cmd` files can be invoked using [`child_process.spawn()`][] with the `shell`
|
||||
option set, with [`child_process.exec()`][], or by spawning `cmd.exe` and passing
|
||||
the `.bat` or `.cmd` file as an argument (which is what the `shell` option and
|
||||
`child_process.exec()` do).
|
||||
[`child_process.exec()`][] do).
|
||||
|
||||
```js
|
||||
// On Windows Only ...
|
||||
@ -118,15 +118,15 @@ exec('my.bat', (err, stdout, stderr) => {
|
||||
* `options` {Object}
|
||||
* `cwd` {String} Current working directory of the child process
|
||||
* `env` {Object} Environment key-value pairs
|
||||
* `encoding` {String} (Default: 'utf8')
|
||||
* `encoding` {String} (Default: `'utf8'`)
|
||||
* `shell` {String} Shell to execute the command with
|
||||
(Default: '/bin/sh' on UNIX, 'cmd.exe' on Windows, The shell should
|
||||
(Default: `'/bin/sh'` on UNIX, `'cmd.exe'` on Windows, The shell should
|
||||
understand the `-c` switch on UNIX or `/s /c` on Windows. On Windows,
|
||||
command line parsing should be compatible with `cmd.exe`.)
|
||||
* `timeout` {Number} (Default: 0)
|
||||
* `timeout` {Number} (Default: `0`)
|
||||
* [`maxBuffer`][] {Number} largest amount of data (in bytes) allowed on
|
||||
stdout or stderr - if exceeded child process is killed (Default: `200*1024`)
|
||||
* `killSignal` {String} (Default: 'SIGTERM')
|
||||
stdout or stderr - if exceeded child process is killed (Default: `200\*1024`)
|
||||
* `killSignal` {String} (Default: `'SIGTERM'`)
|
||||
* `uid` {Number} Sets the user identity of the process. (See setuid(2).)
|
||||
* `gid` {Number} Sets the group identity of the process. (See setgid(2).)
|
||||
* `callback` {Function} called with the output when process terminates
|
||||
@ -182,7 +182,7 @@ If `timeout` is greater than `0`, the parent will send the the signal
|
||||
identified by the `killSignal` property (the default is `'SIGTERM'`) if the
|
||||
child runs longer than `timeout` milliseconds.
|
||||
|
||||
*Note: Unlike the `exec()` POSIX system call, `child_process.exec()` does not
|
||||
*Note: Unlike the exec(3) POSIX system call, `child_process.exec()` does not
|
||||
replace the existing process and uses a shell to execute the command.*
|
||||
|
||||
### child_process.execFile(file[, args][, options][, callback])
|
||||
@ -192,11 +192,11 @@ replace the existing process and uses a shell to execute the command.*
|
||||
* `options` {Object}
|
||||
* `cwd` {String} Current working directory of the child process
|
||||
* `env` {Object} Environment key-value pairs
|
||||
* `encoding` {String} (Default: 'utf8')
|
||||
* `timeout` {Number} (Default: 0)
|
||||
* `encoding` {String} (Default: `'utf8'`)
|
||||
* `timeout` {Number} (Default: `0`)
|
||||
* [`maxBuffer`][] {Number} largest amount of data (in bytes) allowed on
|
||||
stdout or stderr - if exceeded child process is killed (Default: 200\*1024)
|
||||
* `killSignal` {String} (Default: 'SIGTERM')
|
||||
stdout or stderr - if exceeded child process is killed (Default: `200\*1024`)
|
||||
* `killSignal` {String} (Default: `'SIGTERM'`)
|
||||
* `uid` {Number} Sets the user identity of the process. (See setuid(2).)
|
||||
* `gid` {Number} Sets the group identity of the process. (See setgid(2).)
|
||||
* `callback` {Function} called with the output when process terminates
|
||||
@ -210,7 +210,7 @@ except that it does not spawn a shell. Rather, the specified executable `file`
|
||||
is spawned directly as a new process making it slightly more efficient than
|
||||
[`child_process.exec()`][].
|
||||
|
||||
The same options as `child_process.exec()` are supported. Since a shell is not
|
||||
The same options as [`child_process.exec()`][] are supported. Since a shell is not
|
||||
spawned, behaviors such as I/O redirection and file globbing are not supported.
|
||||
|
||||
```js
|
||||
@ -240,20 +240,20 @@ the callback instead.
|
||||
* `execPath` {String} Executable used to create the child process
|
||||
* `execArgv` {Array} List of string arguments passed to the executable
|
||||
(Default: `process.execArgv`)
|
||||
* `silent` {Boolean} If true, stdin, stdout, and stderr of the child will be
|
||||
* `silent` {Boolean} If `true`, stdin, stdout, and stderr of the child will be
|
||||
piped to the parent, otherwise they will be inherited from the parent, see
|
||||
the `'pipe'` and `'inherit'` options for [`child_process.spawn()`][]'s
|
||||
[`stdio`][] for more details (default is false)
|
||||
[`stdio`][] for more details (Default: `false`)
|
||||
* `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.fork()` method is a special case of
|
||||
[`child_process.spawn()`][] used specifically to spawn new Node.js processes.
|
||||
Like `child_process.spawn()`, a `ChildProcess` object is returned. The returned
|
||||
`ChildProcess` will have an additional communication channel built-in that
|
||||
Like [`child_process.spawn()`][], a [`ChildProcess`][] object is returned. The returned
|
||||
[`ChildProcess`][] will have an additional communication channel built-in that
|
||||
allows messages to be passed back and forth between the parent and child. See
|
||||
[`ChildProcess#send()`][] for details.
|
||||
[`child.send()`][] for details.
|
||||
|
||||
It is important to keep in mind that spawned Node.js child processes are
|
||||
independent of the parent with exception of the IPC communication channel
|
||||
@ -263,7 +263,7 @@ required, spawning a large number of child Node.js processes is not
|
||||
recommended.
|
||||
|
||||
By default, `child_process.fork()` will spawn new Node.js instances using the
|
||||
`process.execPath` of the parent process. The `execPath` property in the
|
||||
[`process.execPath`][] of the parent process. The `execPath` property in the
|
||||
`options` object allows for an alternative execution path to be used.
|
||||
|
||||
Node.js processes launched with a custom `execPath` will communicate with the
|
||||
@ -271,7 +271,7 @@ parent process using the file descriptor (fd) identified using the
|
||||
environment variable `NODE_CHANNEL_FD` on the child process. The input and
|
||||
output on this fd is expected to be line delimited JSON objects.
|
||||
|
||||
*Note: Unlike the `fork()` POSIX system call, [`child_process.fork()`][] does
|
||||
*Note: Unlike the fork(2) POSIX system call, `child_process.fork()` does
|
||||
not clone the current process.*
|
||||
|
||||
### child_process.spawn(command[, args][, options])
|
||||
@ -282,14 +282,14 @@ not clone the current process.*
|
||||
* `cwd` {String} Current working directory of the child process
|
||||
* `env` {Object} Environment key-value pairs
|
||||
* `stdio` {Array|String} Child's stdio configuration. (See
|
||||
[`options.stdio`][])
|
||||
[`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).)
|
||||
* `shell` {Boolean|String} If `true`, runs `command` inside of a shell. Uses
|
||||
'/bin/sh' on UNIX, and 'cmd.exe' on Windows. A different shell can be
|
||||
`'/bin/sh'` on UNIX, and `'cmd.exe'` on Windows. A different shell can be
|
||||
specified as a string. The shell should understand the `-c` switch on UNIX,
|
||||
or `/s /c` on Windows. Defaults to `false` (no shell).
|
||||
* return: {ChildProcess}
|
||||
@ -311,7 +311,7 @@ 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`.
|
||||
process, the default is [`process.env`][].
|
||||
|
||||
Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
|
||||
exit code:
|
||||
@ -334,7 +334,7 @@ ls.on('close', (code) => {
|
||||
```
|
||||
|
||||
|
||||
Example: A very elaborate way to run 'ps ax | grep ssh'
|
||||
Example: A very elaborate way to run `ps ax | grep ssh`
|
||||
|
||||
```js
|
||||
const spawn = require('child_process').spawn;
|
||||
@ -393,7 +393,7 @@ disabled*.
|
||||
On non-Windows platforms, if `options.detached` is set to `true`, the child
|
||||
process will be made the leader of a new process group and session. Note that
|
||||
child processes may continue running after the parent exits regardless of
|
||||
whether they are detached or not. See `setsid(2)` for more information.
|
||||
whether they are detached or not. See setsid(2) for more information.
|
||||
|
||||
By default, the parent will wait for the detached child to exit. To prevent
|
||||
the parent from waiting for a given `child`, use the `child.unref()` method.
|
||||
@ -441,8 +441,8 @@ child.unref();
|
||||
|
||||
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
|
||||
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:
|
||||
@ -452,29 +452,29 @@ For convenience, `options.stdio` may be one of the following strings:
|
||||
* `'inherit'` - equivalent to `[process.stdin, process.stdout, process.stderr]`
|
||||
or `[0,1,2]`
|
||||
|
||||
Otherwise, the value of `option.stdio` is an array where each index corresponds
|
||||
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:
|
||||
|
||||
1. `'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 the
|
||||
`child_process` object as `ChildProcess.stdio[fd]`. Pipes created for
|
||||
fds 0 - 2 are also available as ChildProcess.stdin, ChildProcess.stdout
|
||||
and ChildProcess.stderr, respectively.
|
||||
`child_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.
|
||||
2. `'ipc'` - Create an IPC channel for passing messages/file descriptors
|
||||
between parent and child. A ChildProcess may have at most *one* IPC stdio
|
||||
file descriptor. Setting this option enables the ChildProcess.send() method.
|
||||
between parent and child. A [`ChildProcess`][] may have at most *one* IPC stdio
|
||||
file descriptor. Setting this option enables the [`child.send()`][] method.
|
||||
If the child writes JSON messages to this file descriptor, the
|
||||
`ChildProcess.on('message')` event handler will be triggered in the parent.
|
||||
[`child.on('message')`][`'message'`] event handler will be triggered in the parent.
|
||||
If the child is a Node.js process, the presence of an IPC channel will enable
|
||||
`process.send()`, `process.disconnect()`, `process.on('disconnect')`, and
|
||||
`process.on('message')` within the child.
|
||||
[`process.send()`][], [`process.disconnect()`][], [`process.on('disconnect')`][], and
|
||||
[`process.on('message')`] within the child.
|
||||
3. `'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.
|
||||
4. `Stream` object - Share a readable or writable stream that refers to a tty,
|
||||
4. {Stream} object - Share a readable or writable stream that refers to a tty,
|
||||
file, socket, or a pipe with the child process. The stream's underlying
|
||||
file descriptor is duplicated in the child process to the fd that
|
||||
corresponds to the index in the `stdio` array. Note that the stream must
|
||||
@ -482,7 +482,7 @@ pipes between the parent and child. The value is one of the following:
|
||||
event has occurred).
|
||||
5. 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.
|
||||
process, similar to how {Stream} objects can be shared.
|
||||
6. `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'`.
|
||||
@ -506,7 +506,7 @@ spawn('prg', [], { stdio: ['pipe', null, null, null, 'pipe'] });
|
||||
*It is worth noting that when an IPC channel is established between the
|
||||
parent and child processes, and the child is a Node.js process, the child
|
||||
is launched with the IPC channel unreferenced (using `unref()`) until the
|
||||
child registers an event handler for the `process.on('disconnected')` event.
|
||||
child registers an event handler for the [`process.on('disconnect')`][] event.
|
||||
This allows the child to exit normally without the process being held open
|
||||
by the open IPC channel.*
|
||||
|
||||
@ -514,8 +514,8 @@ See also: [`child_process.exec()`][] and [`child_process.fork()`][]
|
||||
|
||||
## Synchronous Process Creation
|
||||
|
||||
The `child_process.spawnSync()`, `child_process.execSync()`, and
|
||||
`child_process.execFileSync()` methods are **synchronous** and **WILL** block
|
||||
The [`child_process.spawnSync()`][], [`child_process.execSync()`][], and
|
||||
[`child_process.execFileSync()`][] methods are **synchronous** and **WILL** block
|
||||
the Node.js event loop, pausing execution of any additional code until the
|
||||
spawned process exits.
|
||||
|
||||
@ -532,23 +532,23 @@ configuration at startup.
|
||||
* `input` {String|Buffer} The value which will be passed as stdin to the
|
||||
spawned process
|
||||
- supplying this value will override `stdio[0]`
|
||||
* `stdio` {Array} Child's stdio configuration. (Default: 'pipe')
|
||||
* `stdio` {Array} Child's stdio configuration. (Default: `'pipe'`)
|
||||
- `stderr` by default will be output to the parent process' stderr unless
|
||||
`stdio` is specified
|
||||
* `env` {Object} Environment key-value pairs
|
||||
* `uid` {Number} Sets the user identity of the process. (See setuid(2).)
|
||||
* `gid` {Number} Sets the group identity of the process. (See setgid(2).)
|
||||
* `timeout` {Number} In milliseconds the maximum amount of time the process
|
||||
is allowed to run. (Default: undefined)
|
||||
is allowed to run. (Default: `undefined`)
|
||||
* `killSignal` {String} The signal value to be used when the spawned process
|
||||
will be killed. (Default: 'SIGTERM')
|
||||
will be killed. (Default: `'SIGTERM'`)
|
||||
* [`maxBuffer`][] {Number} largest amount of data (in bytes) allowed on
|
||||
stdout or stderr - if exceeded child process is killed
|
||||
* `encoding` {String} The encoding used for all stdio inputs and outputs. (Default: 'buffer')
|
||||
* `encoding` {String} The encoding used for all stdio inputs and outputs. (Default: `'buffer'`)
|
||||
* return: {Buffer|String} The stdout from the command
|
||||
|
||||
The `child_process.execFileSync()` method is generally identical to
|
||||
`child_process.execFile()` with the exception that the method will not return
|
||||
[`child_process.execFile()`][] with the exception that the method will not return
|
||||
until the child process has fully closed. When a timeout has been encountered
|
||||
and `killSignal` is sent, the method won't return until the process has
|
||||
completely exited. *Note that if the child process intercepts and handles
|
||||
@ -567,28 +567,28 @@ throw. The [`Error`][] object will contain the entire result from
|
||||
* `input` {String|Buffer} The value which will be passed as stdin to the
|
||||
spawned process
|
||||
- supplying this value will override `stdio[0]`
|
||||
* `stdio` {Array} Child's stdio configuration. (Default: 'pipe')
|
||||
* `stdio` {Array} Child's stdio configuration. (Default: `'pipe'`)
|
||||
- `stderr` by default will be output to the parent process' stderr unless
|
||||
`stdio` is specified
|
||||
* `env` {Object} Environment key-value pairs
|
||||
* `shell` {String} Shell to execute the command with
|
||||
(Default: '/bin/sh' on UNIX, 'cmd.exe' on Windows, The shell should
|
||||
(Default: `'/bin/sh'` on UNIX, `'cmd.exe'` on Windows, The shell should
|
||||
understand the `-c` switch on UNIX or `/s /c` on Windows. On Windows,
|
||||
command line parsing should be compatible with `cmd.exe`.)
|
||||
* `uid` {Number} Sets the user identity of the process. (See setuid(2).)
|
||||
* `gid` {Number} Sets the group identity of the process. (See setgid(2).)
|
||||
* `timeout` {Number} In milliseconds the maximum amount of time the process
|
||||
is allowed to run. (Default: undefined)
|
||||
is allowed to run. (Default: `undefined`)
|
||||
* `killSignal` {String} The signal value to be used when the spawned process
|
||||
will be killed. (Default: 'SIGTERM')
|
||||
will be killed. (Default: `'SIGTERM'`)
|
||||
* [`maxBuffer`][] {Number} largest amount of data (in bytes) allowed on
|
||||
stdout or stderr - if exceeded child process is killed
|
||||
* `encoding` {String} The encoding used for all stdio inputs and outputs.
|
||||
(Default: 'buffer')
|
||||
(Default: `'buffer'`)
|
||||
* return: {Buffer|String} The stdout from the command
|
||||
|
||||
The `child_process.execSync()` method is generally identical to
|
||||
`child_process.exec()` with the exception that the method will not return until
|
||||
[`child_process.exec()`][] with the exception that the method will not return until
|
||||
the child process has fully closed. When a timeout has been encountered and
|
||||
`killSignal` is sent, the method won't return until the process has completely
|
||||
exited. *Note that if the child process intercepts and handles the `SIGTERM`
|
||||
@ -613,15 +613,15 @@ throw. The [`Error`][] object will contain the entire result from
|
||||
* `uid` {Number} Sets the user identity of the process. (See setuid(2).)
|
||||
* `gid` {Number} Sets the group identity of the process. (See setgid(2).)
|
||||
* `timeout` {Number} In milliseconds the maximum amount of time the process
|
||||
is allowed to run. (Default: undefined)
|
||||
is allowed to run. (Default: `undefined`)
|
||||
* `killSignal` {String} The signal value to be used when the spawned process
|
||||
will be killed. (Default: 'SIGTERM')
|
||||
will be killed. (Default: `'SIGTERM'`)
|
||||
* [`maxBuffer`][] {Number} largest amount of data (in bytes) allowed on
|
||||
stdout or stderr - if exceeded child process is killed
|
||||
* `encoding` {String} The encoding used for all stdio inputs and outputs.
|
||||
(Default: 'buffer')
|
||||
(Default: `'buffer'`)
|
||||
* `shell` {Boolean|String} If `true`, runs `command` inside of a shell. Uses
|
||||
'/bin/sh' on UNIX, and 'cmd.exe' on Windows. A different shell can be
|
||||
`'/bin/sh'` on UNIX, and `'cmd.exe'` on Windows. A different shell can be
|
||||
specified as a string. The shell should understand the `-c` switch on UNIX,
|
||||
or `/s /c` on Windows. Defaults to `false` (no shell).
|
||||
* return: {Object}
|
||||
@ -634,7 +634,7 @@ throw. The [`Error`][] object will contain the entire result from
|
||||
* `error` {Error} The error object if the child process failed or timed out
|
||||
|
||||
The `child_process.spawnSync()` method is generally identical to
|
||||
`child_process.spawn()` with the exception that the function will not return
|
||||
[`child_process.spawn()`][] with the exception that the function will not return
|
||||
until the child process has fully closed. When a timeout has been encountered
|
||||
and `killSignal` is sent, the method won't return until the process has
|
||||
completely exited. Note that if the process intercepts and handles the
|
||||
@ -643,7 +643,7 @@ process has exited.
|
||||
|
||||
## Class: ChildProcess
|
||||
|
||||
Instances of the `ChildProcess` class are [`EventEmitters`][] that represent
|
||||
Instances of the `ChildProcess` class are [`EventEmitters`][`EventEmitter`] that represent
|
||||
spawned child processes.
|
||||
|
||||
Instances of `ChildProcess` are not intended to be created directly. Rather,
|
||||
@ -657,15 +657,15 @@ instances of `ChildProcess`.
|
||||
* `signal` {String} the signal by which the child process was terminated.
|
||||
|
||||
The `'close'` event is emitted when the stdio streams of a child process have
|
||||
been closed. This is distinct from the `'exit'` event, since multiple
|
||||
been closed. This is distinct from the [`'exit'`][] event, since multiple
|
||||
processes might share the same stdio streams.
|
||||
|
||||
### Event: 'disconnect'
|
||||
|
||||
The `'disconnect'` event is emitted after calling the
|
||||
`ChildProcess.disconnect()` method in the parent or child process. After
|
||||
[`child.disconnect()`][] method in parent process or [`process.disconnect()`][] in child process. After
|
||||
disconnecting it is no longer possible to send or receive messages, and the
|
||||
`ChildProcess.connected` property is false.
|
||||
[`child.connected`][] property is `false`.
|
||||
|
||||
### Event: 'error'
|
||||
|
||||
@ -681,7 +681,7 @@ 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.
|
||||
|
||||
See also [`ChildProcess#kill()`][] and [`ChildProcess#send()`][].
|
||||
See also [`child.kill()`][] and [`child.send()`][].
|
||||
|
||||
### Event: 'exit'
|
||||
|
||||
@ -701,7 +701,7 @@ Also, note that Node.js establishes signal handlers for `SIGINT` and
|
||||
of those signals. Rather, Node.js will perform a sequence of cleanup actions
|
||||
and then will re-raise the handled signal.
|
||||
|
||||
See `waitpid(2)`.
|
||||
See waitpid(2).
|
||||
|
||||
### Event: 'message'
|
||||
|
||||
@ -709,15 +709,15 @@ See `waitpid(2)`.
|
||||
* `sendHandle` {Handle} a [`net.Socket`][] or [`net.Server`][] object, or
|
||||
undefined.
|
||||
|
||||
The `'message'` event is triggered when a child process uses `process.send()`
|
||||
The `'message'` event is triggered when a child process uses [`process.send()`][]
|
||||
to send messages.
|
||||
|
||||
### child.connected
|
||||
|
||||
* {Boolean} Set to false after `.disconnect` is called
|
||||
* {Boolean} Set to `false` after `child.disconnect()` is called
|
||||
|
||||
The `child.connected` property indicates whether it is still possible to send
|
||||
and receive messages from a child process. When `child.connected` is false, it
|
||||
and receive messages from a child process. When `child.connected` is `false`, it
|
||||
is no longer possible to send or receive messages.
|
||||
|
||||
### child.disconnect()
|
||||
@ -757,7 +757,7 @@ grep.on('close', (code, signal) => {
|
||||
grep.kill('SIGHUP');
|
||||
```
|
||||
|
||||
The `ChildProcess` object may emit an `'error'` event if the signal cannot be
|
||||
The [`ChildProcess`][] object may emit an [`'error'`][] event if the signal cannot be
|
||||
delivered. Sending a signal to a child process that has already exited is not
|
||||
an error but may have unforeseen consequences. Specifically, if the process
|
||||
identifier (PID) has been reassigned to another process, the signal will be
|
||||
@ -766,7 +766,7 @@ delivered to that process instead which can have unexpected results.
|
||||
Note that while the function is called `kill`, the signal delivered to the
|
||||
child process may not actually terminate the process.
|
||||
|
||||
See `kill(2)` for reference.
|
||||
See kill(2) for reference.
|
||||
|
||||
Also note: on Linux, child processes of child processes will not be terminated
|
||||
when attempting to kill their parent. This is likely to happen when running a
|
||||
@ -817,7 +817,7 @@ grep.stdin.end();
|
||||
When an IPC channel has been established between the parent and child (
|
||||
i.e. when using [`child_process.fork()`][]), the `child.send()` method can be
|
||||
used to send messages to the child process. When the child process is a Node.js
|
||||
instance, these messages can be received via the `process.on('message')` event.
|
||||
instance, these messages can be received via the [`process.on('message')`][] event.
|
||||
|
||||
For example, in the parent script:
|
||||
|
||||
@ -842,13 +842,13 @@ process.on('message', (m) => {
|
||||
process.send({ foo: 'bar' });
|
||||
```
|
||||
|
||||
Child Node.js processes will have a `process.send()` method of their own that
|
||||
Child Node.js processes will have a [`process.send()`][] method of their own that
|
||||
allows the child to send messages back to the parent.
|
||||
|
||||
There is a special case when sending a `{cmd: 'NODE_foo'}` message. All messages
|
||||
containing a `NODE_` prefix in its `cmd` property are considered to be reserved
|
||||
for use within Node.js core and will not be emitted in the child's
|
||||
`process.on('message')` event. Rather, such messages are emitted using the
|
||||
[`process.on('message')`][] event. Rather, such messages are emitted using the
|
||||
`process.on('internalMessage')` event and are consumed internally by Node.js.
|
||||
Applications should avoid using such messages or listening for
|
||||
`'internalMessage'` events as it is subject to change without notice.
|
||||
@ -856,7 +856,7 @@ Applications should avoid using such messages or listening for
|
||||
The optional `sendHandle` argument that may be passed to `child.send()` is for
|
||||
passing a TCP server or socket object to the child process. The child will
|
||||
receive the object as the second argument passed to the callback function
|
||||
registered on the `process.on('message')` event.
|
||||
registered on the [`process.on('message')`][] event.
|
||||
|
||||
The `options` argument, if present, is an object used to parameterize the
|
||||
sending of certain types of handles. `options` supports the following
|
||||
@ -871,7 +871,7 @@ sent but before the child may have received it. The function is called with a
|
||||
single argument: `null` on success, or an [`Error`][] object on failure.
|
||||
|
||||
If no `callback` function is provided and the message cannot be sent, an
|
||||
`'error'` event will be emitted by the `ChildProcess` object. This can happen,
|
||||
`'error'` event will be emitted by the [`ChildProcess`][] object. This can happen,
|
||||
for instance, when the child process has already exited.
|
||||
|
||||
`child.send()` will return `false` if the channel has closed or when the
|
||||
@ -914,8 +914,8 @@ can be handled by the parent and some by the child.
|
||||
|
||||
While the example above uses a server created using the `net` module, `dgram`
|
||||
module servers use exactly the same workflow with the exceptions of listening on
|
||||
a `'message'` event instead of `'connection'` and using `server.bind` instead of
|
||||
`server.listen`. This is, however, currently only supported on UNIX platforms.
|
||||
a `'message'` event instead of `'connection'` and using `server.bind()` instead of
|
||||
`server.listen()`. This is, however, currently only supported on UNIX platforms.
|
||||
|
||||
#### Example: sending a socket object
|
||||
|
||||
@ -1050,23 +1050,36 @@ although there are only 4 characters:
|
||||
console.log('中文测试');
|
||||
```
|
||||
|
||||
[`popen(3)`]: http://linux.die.net/man/3/popen
|
||||
[`ChildProcess`]: #child_process_child_process
|
||||
[`'error'`]: #child_process_event_error
|
||||
[`'exit'`]: #child_process_event_exit
|
||||
[`'message'`]: #child_process_event_message
|
||||
[`child.connected`]: #child_process_child_connected
|
||||
[`child.disconnect()`]: #child_process_child_disconnect
|
||||
[`child.kill()`]: #child_process_child_kill_signal
|
||||
[`child.send()`]: #child_process_child_send_message_sendhandle_options_callback
|
||||
[`child.stderr`]: #child_process_child_stderr
|
||||
[`child.stdin`]: #child_process_child_stdin
|
||||
[`child.stdout`]: #child_process_child_stdout
|
||||
[`child_process.exec()`]: #child_process_child_process_exec_command_options_callback
|
||||
[`child_process.execFile()`]: #child_process_child_process_execfile_file_args_options_callback
|
||||
[`child_process.execFileSync()`]: #child_process_child_process_execfilesync_file_args_options
|
||||
[`child_process.execSync()`]: #child_process_child_process_execsync_command_options
|
||||
[`child_process.fork()`]: #child_process_child_process_fork_modulepath_args_options
|
||||
[`child_process.spawn()`]: #child_process_child_process_spawn_command_args_options
|
||||
[`child_process.spawnSync()`]: #child_process_child_process_spawnsync_command_args_options
|
||||
[`ChildProcess#kill()`]: #child_process_child_kill_signal
|
||||
[`ChildProcess#send()`]: #child_process_child_send_message_sendhandle_options_callback
|
||||
[`ChildProcess`]: #child_process_child_process
|
||||
[`Error`]: errors.html#errors_class_error
|
||||
[`EventEmitter`]: events.html#events_class_eventemitter
|
||||
[`EventEmitters`]: events.html#events_class_eventemitter
|
||||
[`EventEmitter`]: events.html#events_class_events_eventemitter
|
||||
[`JSON.stringify()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
|
||||
[`maxBuffer`]: #child_process_maxbuffer_and_unicode
|
||||
[`net.Server`]: net.html#net_class_net_server
|
||||
[`net.Socket`]: net.html#net_class_net_socket
|
||||
[`options.detached`]: #child_process_options_detached
|
||||
[`options.stdio`]: #child_process_options_stdio
|
||||
[`process.disconnect()`]: process.html#process_process_disconnect
|
||||
[`process.env`]: process.html#process_process_env
|
||||
[`process.execPath`]: process.html#process_process_execpath
|
||||
[`process.on('disconnect')`]: process.html#process_event_disconnect
|
||||
[`process.on('message')`]: process.html#process_event_message
|
||||
[`process.send()`]: process.html#process_process_send_message_sendhandle_callback
|
||||
[`stdio`]: #child_process_options_stdio
|
||||
[synchronous counterparts]: #child_process_synchronous_process_creation
|
||||
[`JSON.stringify()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
|
||||
[`maxBuffer`]: #child_process_maxbuffer_and_unicode
|
||||
|
||||
@ -16,6 +16,11 @@ continue.
|
||||
as [`process.exit()`][] or uncaught exceptions, and should not be used as an
|
||||
alternative to the `'exit'` event unless the intention is to schedule more work.
|
||||
|
||||
## Event: 'disconnect'
|
||||
|
||||
If process is spawned with an IPC channel, `'disconnect'` will be emitted when
|
||||
IPC channel is closed. Read more in [child_process `'disconnect'` event][] doc.
|
||||
|
||||
## Event: 'exit'
|
||||
|
||||
Emitted when the process is about to exit. There is no way to prevent the
|
||||
@ -52,7 +57,7 @@ event on the child's process object.
|
||||
## Event: 'rejectionHandled'
|
||||
|
||||
Emitted whenever a Promise was rejected and an error handler was attached to it
|
||||
(for example with `.catch()`) later than after an event loop turn. This event
|
||||
(for example with [`promise.catch()`][]) later than after an event loop turn. This event
|
||||
is emitted with the following arguments:
|
||||
|
||||
- `p` the promise that was previously emitted in an `'unhandledRejection'`
|
||||
@ -140,7 +145,7 @@ down the process. It is not safe to resume normal operation after
|
||||
Emitted whenever a `Promise` is rejected and no error handler is attached to
|
||||
the promise within a turn of the event loop. When programming with promises
|
||||
exceptions are encapsulated as rejected promises. Such promises can be caught
|
||||
and handled using [`promise.catch(...)`][] and rejections are propagated through
|
||||
and handled using [`promise.catch()`][] and rejections are propagated through
|
||||
a promise chain. This event is useful for detecting and keeping track of
|
||||
promises that were rejected whose rejections were not handled yet. This event
|
||||
is emitted with the following arguments:
|
||||
@ -182,7 +187,7 @@ var resource = new SomeResource();
|
||||
|
||||
In cases like this, you may not want to track the rejection as a developer
|
||||
error like you would for other `'unhandledRejection'` events. To address
|
||||
this, you can either attach a dummy `.catch(() => { })` handler to
|
||||
this, you can either attach a dummy [`.catch(() => { })`][`promise.catch()`] handler to
|
||||
`resource.loaded`, preventing the `'unhandledRejection'` event from being
|
||||
emitted, or you can use the [`'rejectionHandled'`][] event.
|
||||
|
||||
@ -307,7 +312,7 @@ operations are pending. The following status codes are used in other
|
||||
cases:
|
||||
|
||||
* `1` **Uncaught Fatal Exception** - There was an uncaught exception,
|
||||
and it was not handled by a domain or an `'uncaughtException'` event
|
||||
and it was not handled by a domain or an [`'uncaughtException'`][] event
|
||||
handler.
|
||||
* `2` - Unused (reserved by Bash for builtin misuse)
|
||||
* `3` **Internal JavaScript Parse Error** - The JavaScript source code
|
||||
@ -327,7 +332,7 @@ cases:
|
||||
* `7` **Internal Exception Handler Run-Time Failure** - There was an
|
||||
uncaught exception, and the internal fatal exception handler
|
||||
function itself threw an error while attempting to handle it. This
|
||||
can happen, for example, if a `process.on('uncaughtException')` or
|
||||
can happen, for example, if a [`'uncaughtException'`][] or
|
||||
`domain.on('error')` handler throws an error.
|
||||
* `8` - Unused. In previous versions of Node.js, exit code 8 sometimes
|
||||
indicated an uncaught exception.
|
||||
@ -397,7 +402,7 @@ Note:
|
||||
- `SIGSTOP` cannot have a listener installed.
|
||||
|
||||
Note that Windows does not support sending Signals, but Node.js offers some
|
||||
emulation with `process.kill()`, and `child_process.kill()`. Sending signal `0`
|
||||
emulation with [`process.kill()`][], and [`ChildProcess.kill()`][]. Sending signal `0`
|
||||
can be used to test for the existence of a process. Sending `SIGINT`,
|
||||
`SIGTERM`, and `SIGKILL` cause the unconditional termination of the target
|
||||
process.
|
||||
@ -495,9 +500,9 @@ the value of `process.config`.*
|
||||
|
||||
## process.connected
|
||||
|
||||
* {Boolean} Set to false after `process.disconnect()` is called
|
||||
* {Boolean} Set to `false` after `process.disconnect()` is called
|
||||
|
||||
If `process.connected` is false, it is no longer possible to send messages.
|
||||
If `process.connected` is `false`, it is no longer possible to send messages.
|
||||
|
||||
## process.cwd()
|
||||
|
||||
@ -665,7 +670,7 @@ emitMyWarning();
|
||||
|
||||
This is the set of Node.js-specific command line options from the
|
||||
executable that started the process. These options do not show up in
|
||||
`process.argv`, and do not include the Node.js executable, the name of
|
||||
[`process.argv`][], and do not include the Node.js executable, the name of
|
||||
the script, or any options following the script name. These options
|
||||
are useful in order to spawn child processes with the same execution
|
||||
environment as the parent.
|
||||
@ -719,7 +724,7 @@ A number which will be the process exit code, when the process either
|
||||
exits gracefully, or is exited via [`process.exit()`][] without specifying
|
||||
a code.
|
||||
|
||||
Specifying a code to `process.exit(code)` will override any previous
|
||||
Specifying a code to [`process.exit(code)`][`process.exit()`] will override any previous
|
||||
setting of `process.exitCode`.
|
||||
|
||||
|
||||
@ -837,7 +842,7 @@ console.log(process.getgroups()); // [ 27, 30, 46, 1000 ]
|
||||
|
||||
Send a signal to a process. `pid` is the process id and `signal` is the
|
||||
string describing the signal to send. Signal names are strings like
|
||||
`SIGINT` or `SIGHUP`. If omitted, the signal will be `SIGTERM`.
|
||||
`'SIGINT'` or `'SIGHUP'`. If omitted, the signal will be `'SIGTERM'`.
|
||||
See [Signal Events][] and kill(2) for more information.
|
||||
|
||||
Will throw an error if target does not exist, and as a special case, a signal
|
||||
@ -869,11 +874,11 @@ Note: When SIGUSR1 is received by Node.js it starts the debugger, see
|
||||
## process.mainModule
|
||||
|
||||
Alternate way to retrieve [`require.main`][]. The difference is that if the main
|
||||
module changes at runtime, `require.main` might still refer to the original main
|
||||
module changes at runtime, [`require.main`][] might still refer to the original main
|
||||
module in modules that were required before the change occurred. Generally it's
|
||||
safe to assume that the two refer to the same module.
|
||||
|
||||
As with `require.main`, it will be `undefined` if there was no entry script.
|
||||
As with [`require.main`][], it will be `undefined` if there was no entry script.
|
||||
|
||||
## process.memoryUsage()
|
||||
|
||||
@ -1043,7 +1048,7 @@ relied upon to exist.
|
||||
|
||||
When Node.js is spawned with an IPC channel attached, it can send messages to its
|
||||
parent process using `process.send()`. Each will be received as a
|
||||
[`'message'`][] event on the parent's `ChildProcess` object.
|
||||
[`'message'`][] event on the parent's [`ChildProcess`][] object.
|
||||
|
||||
*Note: this function uses [`JSON.stringify()`][] internally to serialize the `message`.*
|
||||
|
||||
@ -1055,7 +1060,7 @@ Note: this function is only available on POSIX platforms (i.e. not Windows,
|
||||
Android)
|
||||
|
||||
Sets the effective group identity of the process. (See setegid(2).)
|
||||
This accepts either a numerical ID or a groupname string. If a groupname
|
||||
This accepts either a numerical ID or a group name string. If a group name
|
||||
is specified, this method blocks while resolving it to a numerical ID.
|
||||
|
||||
```js
|
||||
@ -1099,7 +1104,7 @@ Note: this function is only available on POSIX platforms (i.e. not Windows,
|
||||
Android)
|
||||
|
||||
Sets the group identity of the process. (See setgid(2).) This accepts either
|
||||
a numerical ID or a groupname string. If a groupname is specified, this method
|
||||
a numerical ID or a group name string. If a group name is specified, this method
|
||||
blocks while resolving it to a numerical ID.
|
||||
|
||||
```js
|
||||
@ -1152,7 +1157,7 @@ if (process.getuid && process.setuid) {
|
||||
A writable stream to stderr (on fd `2`).
|
||||
|
||||
`process.stderr` and `process.stdout` are unlike other streams in Node.js in
|
||||
that they cannot be closed (`end()` will throw), they never emit the `finish`
|
||||
that they cannot be closed ([`end()`][] will throw), they never emit the [`'finish'`][]
|
||||
event and that writes can block when output is redirected to a file (although
|
||||
disks are fast and operating systems normally employ write-back caching so it
|
||||
should be a very rare occurrence indeed.)
|
||||
@ -1202,7 +1207,7 @@ console.log = (msg) => {
|
||||
```
|
||||
|
||||
`process.stderr` and `process.stdout` are unlike other streams in Node.js in
|
||||
that they cannot be closed (`end()` will throw), they never emit the `'finish'`
|
||||
that they cannot be closed ([`end()`][] will throw), they never emit the [`'finish'`][]
|
||||
event and that writes can block when output is redirected to a file (although
|
||||
disks are fast and operating systems normally employ write-back caching so it
|
||||
should be a very rare occurrence indeed.)
|
||||
@ -1287,21 +1292,30 @@ Will print something like:
|
||||
openssl: '1.0.1k' }
|
||||
```
|
||||
|
||||
[`'finish'`]: stream.html#stream_event_finish
|
||||
[`'message'`]: child_process.html#child_process_event_message
|
||||
[`'rejectionHandled'`]: #process_event_rejectionhandled
|
||||
[`'uncaughtException'`]: #process_event_uncaughtexception
|
||||
[`ChildProcess.disconnect()`]: child_process.html#child_process_child_disconnect
|
||||
[`ChildProcess.kill()`]: child_process.html#child_process_child_kill_signal
|
||||
[`ChildProcess.send()`]: child_process.html#child_process_child_send_message_sendhandle_options_callback
|
||||
[`ChildProcess`]: child_process.html#child_process_class_childprocess
|
||||
[`end()`]: stream.html#stream_writable_end_chunk_encoding_callback
|
||||
[`Error`]: errors.html#errors_class_error
|
||||
[`EventEmitter`]: events.html#events_class_eventemitter
|
||||
[`EventEmitter`]: events.html#events_class_events_eventemitter
|
||||
[`JSON.stringify()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
|
||||
[`net.Server`]: net.html#net_class_net_server
|
||||
[`net.Socket`]: net.html#net_class_net_socket
|
||||
[`process.argv`]: #process_process_argv
|
||||
[`process.exit()`]: #process_process_exit_code
|
||||
[`promise.catch(...)`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch
|
||||
[`'rejectionHandled'`]: #process_event_rejectionhandled
|
||||
[`process.kill()`]: #process_process_kill_pid_signal
|
||||
[`promise.catch()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch
|
||||
[`require.main`]: modules.html#modules_accessing_the_main_module
|
||||
[`setTimeout(fn, 0)`]: timers.html#timers_settimeout_callback_delay_arg
|
||||
[child_process `'disconnect'` event]: child_process.html#child_process_event_disconnect
|
||||
[process_emit_warning]: #process_emitwarning_warning_name_ctor
|
||||
[process_warning]: #process_event_warning
|
||||
[Signal Events]: #process_signal_events
|
||||
[Stream compatibility]: stream.html#stream_compatibility_with_older_node_js_versions
|
||||
[the tty docs]: tty.html#tty_tty
|
||||
[`JSON.stringify()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
|
||||
[process_warning]: #process_event_warning
|
||||
[process_emit_warning]: #process_process_emitwarning_warning_name_ctor
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user