From 342f4cccb5f708fd27499a08dcb8ed43abf06ade Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Tue, 1 Aug 2017 14:43:34 -0700 Subject: [PATCH] doc: change `child` to `subprocess` Backport-PR-URL: https://github.com/nodejs/node/pull/14632 Backport-Reviewed-By: Refael Ackermann Backport-Reviewed-By: Anna Henningsen PR-URL: https://github.com/nodejs/node/pull/14578 Reviewed-By: Colin Ihrig Reviewed-By: Luigi Pinca Reviewed-By: Refael Ackermann --- doc/api/child_process.md | 194 +++++++++++++++++++++------------------ doc/api/errors.md | 8 +- 2 files changed, 108 insertions(+), 94 deletions(-) diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 1801bc54575112..beb4e37a6d8156 100755 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -333,7 +333,7 @@ The `child_process.fork()` method is a special case of 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 -[`child.send()`][] for details. +[`subprocess.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 @@ -472,10 +472,10 @@ Example of checking for failed `spawn`: ```js const { spawn } = require('child_process'); -const child = spawn('bad_command'); +const subprocess = spawn('bad_command'); -child.on('error', (err) => { - console.log('Failed to start child process.'); +subprocess.on('error', (err) => { + console.log('Failed to start subprocess.'); }); ``` @@ -503,10 +503,10 @@ child processes may continue running after the parent exits regardless of 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. -Doing so will cause the parent's event loop to not include the child in its -reference count, allowing the parent to exit independently of the child, unless -there is an established IPC channel between the child and parent. +the parent from waiting for a given `subprocess`, use the `subprocess.unref()` +method. Doing so will cause the parent's event loop to not include the child in +its reference count, allowing the parent to exit independently of the child, +unless there is an established IPC channel between the child and parent. When using the `detached` option to start a long-running process, the process will not stay running in the background after the parent exits unless it is @@ -520,12 +520,12 @@ Example of a long-running process, by detaching and also ignoring its parent ```js const { spawn } = require('child_process'); -const child = spawn(process.argv[0], ['child_program.js'], { +const subprocess = spawn(process.argv[0], ['child_program.js'], { detached: true, stdio: 'ignore' }); -child.unref(); +subprocess.unref(); ``` Alternatively one can redirect the child process' output into files: @@ -536,12 +536,12 @@ const { spawn } = require('child_process'); const out = fs.openSync('./out.log', 'a'); const err = fs.openSync('./out.log', 'a'); -const child = spawn('prg', [], { +const subprocess = spawn('prg', [], { detached: true, stdio: [ 'ignore', out, err ] }); -child.unref(); +subprocess.unref(); ``` #### options.stdio @@ -555,9 +555,10 @@ changes: The `options.stdio` option is used to configure the pipes that are established between the parent and child process. By default, the child's stdin, stdout, -and stderr are redirected to corresponding [`child.stdin`][], [`child.stdout`][], and -[`child.stderr`][] streams on the [`ChildProcess`][] object. This is equivalent to -setting the `options.stdio` equal to `['pipe', 'pipe', 'pipe']`. +and stderr are redirected to corresponding [`subprocess.stdin`][], +[`subprocess.stdout`][], and [`subprocess.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: @@ -573,17 +574,18 @@ 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 [`child.stdio[fd]`][`stdio`]. Pipes created for - fds 0 - 2 are also available as [`child.stdin`][], [`child.stdout`][] - and [`child.stderr`][], respectively. + `child_process` object as [`subprocess.stdio[fd]`][`stdio`]. Pipes created + for fds 0 - 2 are also available as [`subprocess.stdin`][], + [`subprocess.stdout`][] and [`subprocess.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 [`child.send()`][] method. - If the child writes JSON messages to this file descriptor, the - [`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. + file descriptor. Setting this option enables the [`subprocess.send()`][] + method. If the child writes JSON messages to this file descriptor, the + [`subprocess.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. 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 @@ -828,9 +830,10 @@ added: v0.7.2 --> The `'disconnect'` event is emitted after calling the -[`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 -[`child.connected`][] property is `false`. +[`subprocess.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 [`subprocess.connected`][] +property is `false`. ### Event: 'error' @@ -846,7 +849,7 @@ The `'error'` event is emitted whenever: When listening to both the `'exit'` and `'error'` events, it is important to guard against accidentally invoking handler functions multiple times. -See also [`child.kill()`][] and [`child.send()`][]. +See also [`subprocess.kill()`][] and [`subprocess.send()`][]. ### Event: 'exit' * {Object} A pipe representing the IPC channel to the child process. -The `child.channel` property is a reference to the child's IPC channel. If no -IPC channel currently exists, this property is `undefined`. +The `subprocess.channel` property is a reference to the child's IPC channel. If +no IPC channel currently exists, this property is `undefined`. -### child.connected + +### subprocess.connected -* {boolean} Set to `false` after `child.disconnect()` is called +* {boolean} Set to `false` after `subprocess.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 -is no longer possible to send or receive messages. +The `subprocess.connected` property indicates whether it is still possible to +send and receive messages from a child process. When `subprocess.connected` is +`false`, it is no longer possible to send or receive messages. -### child.disconnect() + +### subprocess.disconnect() Closes the IPC channel between parent and child, allowing the child to exit gracefully once there are no other connections keeping it alive. After calling -this method the `child.connected` and `process.connected` properties in both -the parent and child (respectively) will be set to `false`, and it will be no -longer possible to pass messages between the processes. +this method the `subprocess.connected` and `process.connected` properties in +both the parent and child (respectively) will be set to `false`, and it will be +no longer possible to pass messages between the processes. The `'disconnect'` event will be emitted when there are no messages in the process of being received. This will most often be triggered immediately after -calling `child.disconnect()`. +calling `subprocess.disconnect()`. Note that when the child process is a Node.js instance (e.g. spawned using [`child_process.fork()`]), the `process.disconnect()` method can be invoked within the child process to close the IPC channel as well. -### child.kill([signal]) + +### subprocess.kill([signal]) * `signal` {string} -The `child.kill()` methods sends a signal to the child process. If no argument -is given, the process will be sent the `'SIGTERM'` signal. See signal(7) for -a list of available signals. +The `subprocess.kill()` methods sends a signal to the child process. If no +argument is given, the process will be sent the `'SIGTERM'` signal. See +signal(7) for a list of available signals. ```js const { spawn } = require('child_process'); @@ -967,7 +974,7 @@ as in this example: 'use strict'; const { spawn } = require('child_process'); -const child = spawn( +const subprocess = spawn( 'sh', [ '-c', @@ -980,11 +987,12 @@ const child = spawn( ); setTimeout(() => { - child.kill(); // does not terminate the node process in the shell + subprocess.kill(); // does not terminate the node process in the shell }, 2000); ``` -### child.pid + +### subprocess.pid @@ -1003,7 +1011,8 @@ console.log(`Spawned child pid: ${grep.pid}`); grep.stdin.end(); ``` -### child.send(message[, sendHandle[, options]][, callback]) + +### subprocess.send(message[, sendHandle[, options]][, callback]) @@ -1196,10 +1207,11 @@ A `Readable Stream` that represents the child process's `stderr`. If the child was spawned with `stdio[2]` set to anything other than `'pipe'`, then this will be `null`. -`child.stderr` is an alias for `child.stdio[2]`. Both properties will refer to -the same value. +`subprocess.stderr` is an alias for `subprocess.stdio[2]`. Both properties will +refer to the same value. -### child.stdin + +### subprocess.stdin @@ -1214,10 +1226,11 @@ continue until this stream has been closed via `end()`.* If the child was spawned with `stdio[0]` set to anything other than `'pipe'`, then this will be `null`. -`child.stdin` is an alias for `child.stdio[0]`. Both properties will refer to -the same value. +`subprocess.stdin` is an alias for `subprocess.stdio[0]`. Both properties will +refer to the same value. -### child.stdio + +### subprocess.stdio @@ -1226,20 +1239,20 @@ added: v0.7.10 A sparse array of pipes to the child process, corresponding with positions in the [`stdio`][] option passed to [`child_process.spawn()`][] that have been set -to the value `'pipe'`. Note that `child.stdio[0]`, `child.stdio[1]`, and -`child.stdio[2]` are also available as `child.stdin`, `child.stdout`, and -`child.stderr`, respectively. +to the value `'pipe'`. Note that `subprocess.stdio[0]`, `subprocess.stdio[1]`, +and `subprocess.stdio[2]` are also available as `subprocess.stdin`, +`subprocess.stdout`, and `subprocess.stderr`, respectively. In the following example, only the child's fd `1` (stdout) is configured as a -pipe, so only the parent's `child.stdio[1]` is a stream, all other values in -the array are `null`. +pipe, so only the parent's `subprocess.stdio[1]` is a stream, all other values +in the array are `null`. ```js const assert = require('assert'); const fs = require('fs'); const child_process = require('child_process'); -const child = child_process.spawn('ls', { +const subprocess = child_process.spawn('ls', { stdio: [ 0, // Use parent's stdin for child 'pipe', // Pipe child's stdout to parent @@ -1247,17 +1260,18 @@ const child = child_process.spawn('ls', { ] }); -assert.strictEqual(child.stdio[0], null); -assert.strictEqual(child.stdio[0], child.stdin); +assert.strictEqual(subprocess.stdio[0], null); +assert.strictEqual(subprocess.stdio[0], subprocess.stdin); -assert(child.stdout); -assert.strictEqual(child.stdio[1], child.stdout); +assert(subprocess.stdout); +assert.strictEqual(subprocess.stdio[1], subprocess.stdout); -assert.strictEqual(child.stdio[2], null); -assert.strictEqual(child.stdio[2], child.stderr); +assert.strictEqual(subprocess.stdio[2], null); +assert.strictEqual(subprocess.stdio[2], subprocess.stderr); ``` -### child.stdout + +### subprocess.stdout @@ -1269,8 +1283,8 @@ A `Readable Stream` that represents the child process's `stdout`. If the child was spawned with `stdio[1]` set to anything other than `'pipe'`, then this will be `null`. -`child.stdout` is an alias for `child.stdio[1]`. Both properties will refer -to the same value. +`subprocess.stdout` is an alias for `subprocess.stdio[1]`. Both properties will +refer to the same value. ## `maxBuffer` and Unicode @@ -1300,13 +1314,13 @@ unavailable. [`Error`]: errors.html#errors_class_error [`EventEmitter`]: events.html#events_class_eventemitter [`JSON.stringify()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify -[`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 +[`subprocess.connected`]: #child_process_subprocess_connected +[`subprocess.disconnect()`]: #child_process_subprocess_disconnect +[`subprocess.kill()`]: #child_process_subprocess_kill_signal +[`subprocess.send()`]: #child_process_subprocess_send_message_sendhandle_options_callback +[`subprocess.stderr`]: #child_process_subprocess_stderr +[`subprocess.stdin`]: #child_process_subprocess_stdin +[`subprocess.stdout`]: #child_process_subprocess_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 diff --git a/doc/api/errors.md b/doc/api/errors.md index 8c12359538b3e3..570832237c485d 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -607,7 +607,7 @@ platform-dependent. ### ERR_INVALID_HANDLE_TYPE Used when an attempt is made to send an unsupported "handle" over an IPC -communication channel to a child process. See [`child.send()`] and +communication channel to a child process. See [`subprocess.send()`] and [`process.send()`] for more information. @@ -749,7 +749,7 @@ internal bug within the Node.js binary itself. ### ERR_UNKNOWN_SIGNAL Used when an invalid or unknown process signal is passed to an API expecting a -valid signal (such as [`child.kill()`][]). +valid signal (such as [`subprocess.kill()`][]). ### ERR_UNKNOWN_STDIN_TYPE @@ -769,8 +769,8 @@ are most likely an indication of a bug within Node.js itself. [`ERR_INVALID_ARG_TYPE`]: #ERR_INVALID_ARG_TYPE -[`child.kill()`]: child_process.html#child_process_child_kill_signal -[`child.send()`]: child_process.html#child_process_child_send_message_sendhandle_options_callback +[`subprocess.kill()`]: child_process.html#child_process_subprocess_kill_signal +[`subprocess.send()`]: child_process.html#child_process_subprocess_send_message_sendhandle_options_callback [`fs.readFileSync`]: fs.html#fs_fs_readfilesync_path_options [`fs.readdir`]: fs.html#fs_fs_readdir_path_options_callback [`fs.unlink`]: fs.html#fs_fs_unlink_path_callback