lukechilds
/
node
mirror of https://github.com/lukechilds/node.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

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>
v6.x
Alexander Makarenko 9 years ago
committed by James M Snell
parent
7c03595b2a
commit
e6d4f3befb
2 changed files with 154 additions and 127 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 221
      doc/api/child_process.md
  2. 60
      doc/api/process.md

221
doc/api/child_process.md
View File

@ -3,8 +3,8 @@
Stability: 2 - Stable Stability: 2 - Stable
The `child_process` module provides the ability to spawn child processes in 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 a manner that is similar, but not identical, to popen(3). This capability
is primarily provided by the `child_process.spawn()` function: is primarily provided by the [`child_process.spawn()`][] function:
```js ```js
const spawn = require('child_process').spawn; 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 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.* mean that data sent to the child process may not be immediately consumed.*
The `child_process.spawn()` method spawns the child process asynchronously, The [`child_process.spawn()`][] method spawns the child process asynchronously,
without blocking the Node.js event loop. The `child_process.spawnSync()` without blocking the Node.js event loop. The [`child_process.spawnSync()`][]
function provides equivalent functionality in a synchronous manner that blocks function provides equivalent functionality in a synchronous manner that blocks
the event loop until the spawned process either exits or is terminated. the event loop until the spawned process either exits or is terminated.
For convenience, the `child_process` module provides a handful of synchronous For convenience, the `child_process` module provides a handful of synchronous
and asynchronous alternatives to [`child_process.spawn()`][] and and asynchronous alternatives to [`child_process.spawn()`][] and
[`child_process.spawnSync()`][]. *Note that each of these alternatives are [`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. 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. 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 specified module with an IPC communication channel established that allows
sending messages between parent and child. sending messages between parent and child.
* `child_process.execSync()`: a synchronous version of * [`child_process.execSync()`][]: a synchronous version of
`child_process.exec()` that *will* block the Node.js event loop. [`child_process.exec()`][] that *will* block the Node.js event loop.
* `child_process.execFileSync()`: a synchronous version of * [`child_process.execFileSync()`][]: a synchronous version of
`child_process.execFile()` that *will* block the Node.js event loop. [`child_process.execFile()`][] that *will* block the Node.js event loop.
For certain use cases, such as automating shell scripts, the For certain use cases, such as automating shell scripts, the
[synchronous counterparts][] may be more convenient. In many cases, however, [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 ## Asynchronous Process Creation
The `child_process.spawn()`, `child_process.fork()`, `child_process.exec()`, The [`child_process.spawn()`][], [`child_process.fork()`][], [`child_process.exec()`][],
and `child_process.execFile()` methods all follow the idiomatic asynchronous and [`child_process.execFile()`][] methods all follow the idiomatic asynchronous
programming pattern typical of other Node.js APIs. programming pattern typical of other Node.js APIs.
Each of the methods returns a [`ChildProcess`][] instance. These objects 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 register listener functions that are called when certain events occur during
the life cycle of the child process. 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 allow for an optional `callback` function to be specified that is invoked
when the child process terminates. when the child process terminates.
### Spawning `.bat` and `.cmd` files on Windows ### Spawning `.bat` and `.cmd` files on Windows
The importance of the distinction between `child_process.exec()` and The importance of the distinction between [`child_process.exec()`][] and
`child_process.execFile()` can vary based on platform. On Unix-type operating [`child_process.execFile()`][] can vary based on platform. On Unix-type operating
systems (Unix, Linux, OSX) `child_process.execFile()` can be more efficient systems (Unix, Linux, OSX) [`child_process.execFile()`][] can be more efficient
because it does not spawn a shell. On Windows, however, `.bat` and `.cmd` 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 files are not executable on their own without a terminal, and therefore cannot
be launched using `child_process.execFile()`. When running on Windows, `.bat` be launched using [`child_process.execFile()`][]. When running on Windows, `.bat`
and `.cmd` files can be invoked using `child_process.spawn()` with the `shell` 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 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 the `.bat` or `.cmd` file as an argument (which is what the `shell` option and
`child_process.exec()` do). [`child_process.exec()`][] do).
```js ```js
// On Windows Only ... // On Windows Only ...
@ -118,15 +118,15 @@ exec('my.bat', (err, stdout, stderr) => {
* `options` {Object} * `options` {Object}
* `cwd` {String} Current working directory of the child process * `cwd` {String} Current working directory of the child process
* `env` {Object} Environment key-value pairs * `env` {Object} Environment key-value pairs
* `encoding` {String} (Default: 'utf8') * `encoding` {String} (Default: `'utf8'`)
* `shell` {String} Shell to execute the command with * `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, understand the `-c` switch on UNIX or `/s /c` on Windows. On Windows,
command line parsing should be compatible with `cmd.exe`.) 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 * [`maxBuffer`][] {Number} largest amount of data (in bytes) allowed on
stdout or stderr - if exceeded child process is killed (Default: `200*1024`) stdout or stderr - if exceeded child process is killed (Default: `200\*1024`)
* `killSignal` {String} (Default: 'SIGTERM') * `killSignal` {String} (Default: `'SIGTERM'`)
* `uid` {Number} Sets the user identity of the process. (See setuid(2).) * `uid` {Number} Sets the user identity of the process. (See setuid(2).)
* `gid` {Number} Sets the group identity of the process. (See setgid(2).) * `gid` {Number} Sets the group identity of the process. (See setgid(2).)
* `callback` {Function} called with the output when process terminates * `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 identified by the `killSignal` property (the default is `'SIGTERM'`) if the
child runs longer than `timeout` milliseconds. 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.* replace the existing process and uses a shell to execute the command.*
### child_process.execFile(file[, args][, options][, callback]) ### 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} * `options` {Object}
* `cwd` {String} Current working directory of the child process * `cwd` {String} Current working directory of the child process
* `env` {Object} Environment key-value pairs * `env` {Object} Environment key-value pairs
* `encoding` {String} (Default: 'utf8') * `encoding` {String} (Default: `'utf8'`)
* `timeout` {Number} (Default: 0) * `timeout` {Number} (Default: `0`)
* [`maxBuffer`][] {Number} largest amount of data (in bytes) allowed on * [`maxBuffer`][] {Number} largest amount of data (in bytes) allowed on
stdout or stderr - if exceeded child process is killed (Default: 200\*1024) stdout or stderr - if exceeded child process is killed (Default: `200\*1024`)
* `killSignal` {String} (Default: 'SIGTERM') * `killSignal` {String} (Default: `'SIGTERM'`)
* `uid` {Number} Sets the user identity of the process. (See setuid(2).) * `uid` {Number} Sets the user identity of the process. (See setuid(2).)
* `gid` {Number} Sets the group identity of the process. (See setgid(2).) * `gid` {Number} Sets the group identity of the process. (See setgid(2).)
* `callback` {Function} called with the output when process terminates * `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 is spawned directly as a new process making it slightly more efficient than
[`child_process.exec()`][]. [`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. spawned, behaviors such as I/O redirection and file globbing are not supported.
```js ```js
@ -240,20 +240,20 @@ the callback instead.
* `execPath` {String} Executable used to create the child process * `execPath` {String} Executable used to create the child process
* `execArgv` {Array} List of string arguments passed to the executable * `execArgv` {Array} List of string arguments passed to the executable
(Default: `process.execArgv`) (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 piped to the parent, otherwise they will be inherited from the parent, see
the `'pipe'` and `'inherit'` options for [`child_process.spawn()`][]'s 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).) * `uid` {Number} Sets the user identity of the process. (See setuid(2).)
* `gid` {Number} Sets the group identity of the process. (See setgid(2).) * `gid` {Number} Sets the group identity of the process. (See setgid(2).)
* Return: {ChildProcess} * Return: {ChildProcess}
The `child_process.fork()` method is a special case of The `child_process.fork()` method is a special case of
[`child_process.spawn()`][] used specifically to spawn new Node.js processes. [`child_process.spawn()`][] used specifically to spawn new Node.js processes.
Like `child_process.spawn()`, a `ChildProcess` object is returned. The returned Like [`child_process.spawn()`][], a [`ChildProcess`][] object is returned. The returned
`ChildProcess` will have an additional communication channel built-in that [`ChildProcess`][] will have an additional communication channel built-in that
allows messages to be passed back and forth between the parent and child. See 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 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 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. recommended.
By default, `child_process.fork()` will spawn new Node.js instances using the 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. `options` object allows for an alternative execution path to be used.
Node.js processes launched with a custom `execPath` will communicate with the 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 environment variable `NODE_CHANNEL_FD` on the child process. The input and
output on this fd is expected to be line delimited JSON objects. 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.* not clone the current process.*
### child_process.spawn(command[, args][, options]) ### child_process.spawn(command[, args][, options])
@ -282,14 +282,14 @@ not clone the current process.*
* `cwd` {String} Current working directory of the child process * `cwd` {String} Current working directory of the child process
* `env` {Object} Environment key-value pairs * `env` {Object} Environment key-value pairs
* `stdio` {Array|String} Child's stdio configuration. (See * `stdio` {Array|String} Child's stdio configuration. (See
[`options.stdio`][]) [`options.stdio`][`stdio`])
* `detached` {Boolean} Prepare child to run independently of its parent * `detached` {Boolean} Prepare child to run independently of its parent
process. Specific behavior depends on the platform, see process. Specific behavior depends on the platform, see
[`options.detached`][]) [`options.detached`][])
* `uid` {Number} Sets the user identity of the process. (See setuid(2).) * `uid` {Number} Sets the user identity of the process. (See setuid(2).)
* `gid` {Number} Sets the group identity of the process. (See setgid(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 * `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, specified as a string. The shell should understand the `-c` switch on UNIX,
or `/s /c` on Windows. Defaults to `false` (no shell). or `/s /c` on Windows. Defaults to `false` (no shell).
* return: {ChildProcess} * 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. 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 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 Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
exit code: 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 ```js
const spawn = require('child_process').spawn; const spawn = require('child_process').spawn;
@ -393,7 +393,7 @@ disabled*.
On non-Windows platforms, if `options.detached` is set to `true`, the child 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 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 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 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. 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 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, between the parent and child process. By default, the child's stdin, stdout,
and stderr are redirected to corresponding `child.stdin`, `child.stdout`, and and stderr are redirected to corresponding [`child.stdin`][], [`child.stdout`][], and
`child.stderr` streams on the `ChildProcess` object. This is equivalent to [`child.stderr`][] streams on the [`ChildProcess`][] object. This is equivalent to
setting the `options.stdio` equal to `['pipe', 'pipe', 'pipe']`. setting the `options.stdio` equal to `['pipe', 'pipe', 'pipe']`.
For convenience, `options.stdio` may be one of the following strings: 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]` * `'inherit'` - equivalent to `[process.stdin, process.stdout, process.stderr]`
or `[0,1,2]` 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, 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 and stderr, respectively. Additional fds can be specified to create additional
pipes between the parent and child. The value is one of the following: 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. 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 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 `child_process` object as [`child.stdio[fd]`][`stdio`]. Pipes created for
fds 0 - 2 are also available as ChildProcess.stdin, ChildProcess.stdout fds 0 - 2 are also available as [`child.stdin`][], [`child.stdout`][]
and ChildProcess.stderr, respectively. and [`child.stderr`][], respectively.
2. `'ipc'` - Create an IPC channel for passing messages/file descriptors 2. `'ipc'` - Create an IPC channel for passing messages/file descriptors
between parent and child. A ChildProcess may have at most *one* IPC stdio between parent and child. A [`ChildProcess`][] may have at most *one* IPC stdio
file descriptor. Setting this option enables the ChildProcess.send() method. file descriptor. Setting this option enables the [`child.send()`][] method.
If the child writes JSON messages to this file descriptor, the 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 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.send()`][], [`process.disconnect()`][], [`process.on('disconnect')`][], and
`process.on('message')` within the child. [`process.on('message')`] within the child.
3. `'ignore'` - Instructs Node.js to ignore the fd in the child. While Node.js 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 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 `'ignore'` will cause Node.js to open `/dev/null` and attach it to the
child's fd. 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, socket, or a pipe with the child process. The stream's underlying
file descriptor is duplicated in the child process to the fd that 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 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). event has occurred).
5. Positive integer - The integer value is interpreted as a file descriptor 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 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 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 words, stdin, stdout, and stderr) a pipe is created. For fd 3 and up, the
default is `'ignore'`. 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 *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 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 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 This allows the child to exit normally without the process being held open
by the open IPC channel.* by the open IPC channel.*
@ -514,8 +514,8 @@ See also: [`child_process.exec()`][] and [`child_process.fork()`][]
## Synchronous Process Creation ## Synchronous Process Creation
The `child_process.spawnSync()`, `child_process.execSync()`, and The [`child_process.spawnSync()`][], [`child_process.execSync()`][], and
`child_process.execFileSync()` methods are **synchronous** and **WILL** block [`child_process.execFileSync()`][] methods are **synchronous** and **WILL** block
the Node.js event loop, pausing execution of any additional code until the the Node.js event loop, pausing execution of any additional code until the
spawned process exits. spawned process exits.
@ -532,23 +532,23 @@ configuration at startup.
* `input` {String|Buffer} The value which will be passed as stdin to the * `input` {String|Buffer} The value which will be passed as stdin to the
spawned process spawned process
- supplying this value will override `stdio[0]` - 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 - `stderr` by default will be output to the parent process' stderr unless
`stdio` is specified `stdio` is specified
* `env` {Object} Environment key-value pairs * `env` {Object} Environment key-value pairs
* `uid` {Number} Sets the user identity of the process. (See setuid(2).) * `uid` {Number} Sets the user identity of the process. (See setuid(2).)
* `gid` {Number} Sets the group identity of the process. (See setgid(2).) * `gid` {Number} Sets the group identity of the process. (See setgid(2).)
* `timeout` {Number} In milliseconds the maximum amount of time the process * `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 * `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 * [`maxBuffer`][] {Number} largest amount of data (in bytes) allowed on
stdout or stderr - if exceeded child process is killed 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 * return: {Buffer|String} The stdout from the command
The `child_process.execFileSync()` method is generally identical to 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 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 and `killSignal` is sent, the method won't return until the process has
completely exited. *Note that if the child process intercepts and handles 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 * `input` {String|Buffer} The value which will be passed as stdin to the
spawned process spawned process
- supplying this value will override `stdio[0]` - 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 - `stderr` by default will be output to the parent process' stderr unless
`stdio` is specified `stdio` is specified
* `env` {Object} Environment key-value pairs * `env` {Object} Environment key-value pairs
* `shell` {String} Shell to execute the command with * `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, understand the `-c` switch on UNIX or `/s /c` on Windows. On Windows,
command line parsing should be compatible with `cmd.exe`.) command line parsing should be compatible with `cmd.exe`.)
* `uid` {Number} Sets the user identity of the process. (See setuid(2).) * `uid` {Number} Sets the user identity of the process. (See setuid(2).)
* `gid` {Number} Sets the group identity of the process. (See setgid(2).) * `gid` {Number} Sets the group identity of the process. (See setgid(2).)
* `timeout` {Number} In milliseconds the maximum amount of time the process * `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 * `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 * [`maxBuffer`][] {Number} largest amount of data (in bytes) allowed on
stdout or stderr - if exceeded child process is killed stdout or stderr - if exceeded child process is killed
* `encoding` {String} The encoding used for all stdio inputs and outputs. * `encoding` {String} The encoding used for all stdio inputs and outputs.
(Default: 'buffer') (Default: `'buffer'`)
* return: {Buffer|String} The stdout from the command * return: {Buffer|String} The stdout from the command
The `child_process.execSync()` method is generally identical to 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 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 `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` 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).) * `uid` {Number} Sets the user identity of the process. (See setuid(2).)
* `gid` {Number} Sets the group identity of the process. (See setgid(2).) * `gid` {Number} Sets the group identity of the process. (See setgid(2).)
* `timeout` {Number} In milliseconds the maximum amount of time the process * `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 * `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 * [`maxBuffer`][] {Number} largest amount of data (in bytes) allowed on
stdout or stderr - if exceeded child process is killed stdout or stderr - if exceeded child process is killed
* `encoding` {String} The encoding used for all stdio inputs and outputs. * `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 * `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, specified as a string. The shell should understand the `-c` switch on UNIX,
or `/s /c` on Windows. Defaults to `false` (no shell). or `/s /c` on Windows. Defaults to `false` (no shell).
* return: {Object} * 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 * `error` {Error} The error object if the child process failed or timed out
The `child_process.spawnSync()` method is generally identical to 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 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 and `killSignal` is sent, the method won't return until the process has
completely exited. Note that if the process intercepts and handles the completely exited. Note that if the process intercepts and handles the
@ -643,7 +643,7 @@ process has exited.
## Class: ChildProcess ## Class: ChildProcess
Instances of the `ChildProcess` class are [`EventEmitters`][] that represent Instances of the `ChildProcess` class are [`EventEmitters`][`EventEmitter`] that represent
spawned child processes. spawned child processes.
Instances of `ChildProcess` are not intended to be created directly. Rather, 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. * `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 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. processes might share the same stdio streams.
### Event: 'disconnect' ### Event: 'disconnect'
The `'disconnect'` event is emitted after calling the 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 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' ### 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 If you are listening to both the `'exit'` and `'error'` events, it is important
to guard against accidentally invoking handler functions multiple times. 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' ### 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 of those signals. Rather, Node.js will perform a sequence of cleanup actions
and then will re-raise the handled signal. and then will re-raise the handled signal.
See `waitpid(2)`. See waitpid(2).
### Event: 'message' ### Event: 'message'
@ -709,15 +709,15 @@ See `waitpid(2)`.
* `sendHandle` {Handle} a [`net.Socket`][] or [`net.Server`][] object, or * `sendHandle` {Handle} a [`net.Socket`][] or [`net.Server`][] object, or
undefined. 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. to send messages.
### child.connected ### 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 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. is no longer possible to send or receive messages.
### child.disconnect() ### child.disconnect()
@ -757,7 +757,7 @@ grep.on('close', (code, signal) => {
grep.kill('SIGHUP'); 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 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 an error but may have unforeseen consequences. Specifically, if the process
identifier (PID) has been reassigned to another process, the signal will be 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 Note that while the function is called `kill`, the signal delivered to the
child process may not actually terminate the process. 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 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 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 ( 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 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 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: For example, in the parent script:
@ -842,13 +842,13 @@ process.on('message', (m) => {
process.send({ foo: 'bar' }); 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. allows the child to send messages back to the parent.
There is a special case when sending a `{cmd: 'NODE_foo'}` message. All messages 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 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 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. `process.on('internalMessage')` event and are consumed internally by Node.js.
Applications should avoid using such messages or listening for Applications should avoid using such messages or listening for
`'internalMessage'` events as it is subject to change without notice. `'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 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 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 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 The `options` argument, if present, is an object used to parameterize the
sending of certain types of handles. `options` supports the following 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. single argument: `null` on success, or an [`Error`][] object on failure.
If no `callback` function is provided and the message cannot be sent, an 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. for instance, when the child process has already exited.
`child.send()` will return `false` if the channel has closed or when the `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` 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 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 a `'message'` event instead of `'connection'` and using `server.bind()` instead of
`server.listen`. This is, however, currently only supported on UNIX platforms. `server.listen()`. This is, however, currently only supported on UNIX platforms.
#### Example: sending a socket object #### Example: sending a socket object
@ -1050,23 +1050,36 @@ although there are only 4 characters:
console.log('中文测试'); console.log('中文测试');
``` ```
[`popen(3)`]: http://linux.die.net/man/3/popen [`'error'`]: #child_process_event_error
[`ChildProcess`]: #child_process_child_process [`'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.exec()`]: #child_process_child_process_exec_command_options_callback
[`child_process.execFile()`]: #child_process_child_process_execfile_file_args_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.fork()`]: #child_process_child_process_fork_modulepath_args_options
[`child_process.spawn()`]: #child_process_child_process_spawn_command_args_options [`child_process.spawn()`]: #child_process_child_process_spawn_command_args_options
[`child_process.spawnSync()`]: #child_process_child_process_spawnsync_command_args_options [`child_process.spawnSync()`]: #child_process_child_process_spawnsync_command_args_options
[`ChildProcess#kill()`]: #child_process_child_kill_signal [`ChildProcess`]: #child_process_child_process
[`ChildProcess#send()`]: #child_process_child_send_message_sendhandle_options_callback
[`Error`]: errors.html#errors_class_error [`Error`]: errors.html#errors_class_error
[`EventEmitter`]: events.html#events_class_eventemitter [`EventEmitter`]: events.html#events_class_events_eventemitter
[`EventEmitters`]: events.html#events_class_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.Server`]: net.html#net_class_net_server
[`net.Socket`]: net.html#net_class_net_socket [`net.Socket`]: net.html#net_class_net_socket
[`options.detached`]: #child_process_options_detached [`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 [`stdio`]: #child_process_options_stdio
[synchronous counterparts]: #child_process_synchronous_process_creation [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

60
doc/api/process.md
View File

@ -16,6 +16,11 @@ continue.
as [`process.exit()`][] or uncaught exceptions, and should not be used as an 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. 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' ## Event: 'exit'
Emitted when the process is about to exit. There is no way to prevent the 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' ## Event: 'rejectionHandled'
Emitted whenever a Promise was rejected and an error handler was attached to it 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: is emitted with the following arguments:
- `p` the promise that was previously emitted in an `'unhandledRejection'` - `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 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 the promise within a turn of the event loop. When programming with promises
exceptions are encapsulated as rejected promises. Such promises can be caught 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 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 promises that were rejected whose rejections were not handled yet. This event
is emitted with the following arguments: 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 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 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 `resource.loaded`, preventing the `'unhandledRejection'` event from being
emitted, or you can use the [`'rejectionHandled'`][] event. emitted, or you can use the [`'rejectionHandled'`][] event.
@ -307,7 +312,7 @@ operations are pending. The following status codes are used in other
cases: cases:
* `1` **Uncaught Fatal Exception** - There was an uncaught exception, * `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. handler.
* `2` - Unused (reserved by Bash for builtin misuse) * `2` - Unused (reserved by Bash for builtin misuse)
* `3` **Internal JavaScript Parse Error** - The JavaScript source code * `3` **Internal JavaScript Parse Error** - The JavaScript source code
@ -327,7 +332,7 @@ cases:
* `7` **Internal Exception Handler Run-Time Failure** - There was an * `7` **Internal Exception Handler Run-Time Failure** - There was an
uncaught exception, and the internal fatal exception handler uncaught exception, and the internal fatal exception handler
function itself threw an error while attempting to handle it. This 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. `domain.on('error')` handler throws an error.
* `8` - Unused. In previous versions of Node.js, exit code 8 sometimes * `8` - Unused. In previous versions of Node.js, exit code 8 sometimes
indicated an uncaught exception. indicated an uncaught exception.
@ -397,7 +402,7 @@ Note:
- `SIGSTOP` cannot have a listener installed. - `SIGSTOP` cannot have a listener installed.
Note that Windows does not support sending Signals, but Node.js offers some 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`, can be used to test for the existence of a process. Sending `SIGINT`,
`SIGTERM`, and `SIGKILL` cause the unconditional termination of the target `SIGTERM`, and `SIGKILL` cause the unconditional termination of the target
process. process.
@ -495,9 +500,9 @@ the value of `process.config`.*
## process.connected ## 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() ## process.cwd()
@ -665,7 +670,7 @@ emitMyWarning();
This is the set of Node.js-specific command line options from the 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 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 the script, or any options following the script name. These options
are useful in order to spawn child processes with the same execution are useful in order to spawn child processes with the same execution
environment as the parent. 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 exits gracefully, or is exited via [`process.exit()`][] without specifying
a code. 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`. 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 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 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. 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 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 ## process.mainModule
Alternate way to retrieve [`require.main`][]. The difference is that if the main 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 module in modules that were required before the change occurred. Generally it's
safe to assume that the two refer to the same module. 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() ## 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 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 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`.* *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) Android)
Sets the effective group identity of the process. (See setegid(2).) 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. is specified, this method blocks while resolving it to a numerical ID.
```js ```js
@ -1099,7 +1104,7 @@ Note: this function is only available on POSIX platforms (i.e. not Windows,
Android) Android)
Sets the group identity of the process. (See setgid(2).) This accepts either 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. blocks while resolving it to a numerical ID.
```js ```js
@ -1152,7 +1157,7 @@ if (process.getuid && process.setuid) {
A writable stream to stderr (on fd `2`). A writable stream to stderr (on fd `2`).
`process.stderr` and `process.stdout` are unlike other streams in Node.js in `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 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 disks are fast and operating systems normally employ write-back caching so it
should be a very rare occurrence indeed.) 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 `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 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 disks are fast and operating systems normally employ write-back caching so it
should be a very rare occurrence indeed.) should be a very rare occurrence indeed.)
@ -1287,21 +1292,30 @@ Will print something like:
openssl: '1.0.1k' } openssl: '1.0.1k' }
``` ```
[`'finish'`]: stream.html#stream_event_finish
[`'message'`]: child_process.html#child_process_event_message [`'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.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.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 [`Error`]: errors.html#errors_class_error
[`EventEmitter`]: events.html#events_class_eventemitter [`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.Server`]: net.html#net_class_net_server
[`net.Socket`]: net.html#net_class_net_socket [`net.Socket`]: net.html#net_class_net_socket
[`process.argv`]: #process_process_argv
[`process.exit()`]: #process_process_exit_code [`process.exit()`]: #process_process_exit_code
[`promise.catch(...)`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch [`process.kill()`]: #process_process_kill_pid_signal
[`'rejectionHandled'`]: #process_event_rejectionhandled [`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 [`require.main`]: modules.html#modules_accessing_the_main_module
[`setTimeout(fn, 0)`]: timers.html#timers_settimeout_callback_delay_arg [`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 [Signal Events]: #process_signal_events
[Stream compatibility]: stream.html#stream_compatibility_with_older_node_js_versions [Stream compatibility]: stream.html#stream_compatibility_with_older_node_js_versions
[the tty docs]: tty.html#tty_tty [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

Write Preview
Loading…
Cancel
Save