doc: change child to subprocess

Backport-PR-URL: #14635
PR-URL: #14578
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Refael Ackermann <[email protected]>

Author: Trott

doc/api/child_process.md

@@ -400,10 +400,10 @@ Example of checking for failed exec:
 
 ```js
 const spawn = require('child_process').spawn;
-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.');
 });
 ```
 
@@ -423,10 +423,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
@@ -440,12 +440,12 @@ Example of a long-running process, by detaching and also ignoring its parent
 ```js
 const spawn = require('child_process').spawn;
 
-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:
@@ -456,12 +456,12 @@ const spawn = require('child_process').spawn;
 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
@@ -471,9 +471,10 @@ added: v0.7.10
 
 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:
 
@@ -763,46 +764,49 @@ added: v0.5.9
 The `'message'` event is triggered when a child process uses `process.send()`
 to send messages.
 
-### child.connected
+<a name="child_process_child_connected"></a>
+### subprocess.connected
 <!-- YAML
 added: v0.7.2
 -->
 
 * {Boolean} Set to false after `.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()
+<a name="child_process_child_disconnect"></a>
+### subprocess.disconnect()
 <!-- YAML
 added: v0.7.2
 -->
 
 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])
+<a name="child_process_child_kill_signal"></a>
+### subprocess.kill([signal])
 <!-- YAML
 added: v0.1.90
 -->
 
 * `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').spawn;
@@ -837,7 +841,7 @@ as in this example:
 'use strict';
 const spawn = require('child_process').spawn;
 
-let child = spawn('sh', ['-c',
+let subprocess = spawn('sh', ['-c',
   `node -e "setInterval(() => {
       console.log(process.pid, 'is alive')
     }, 500);"`
@@ -846,11 +850,12 @@ let child = spawn('sh', ['-c',
   });
 
 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
+<a name="child_process_child_pid"></a>
+### subprocess.pid
 <!-- YAML
 added: v0.1.90
 -->
@@ -869,7 +874,8 @@ console.log(`Spawned child pid: ${grep.pid}`);
 grep.stdin.end();
 ```
 
-### child.send(message[, sendHandle][, callback])
+<a name="child_process_child_send_message_sendhandle_options_callback"></a>
+### subprocess.send(message[, sendHandle[, options]][, callback])
 <!-- YAML
 added: v0.5.9
 -->
@@ -880,9 +886,10 @@ added: v0.5.9
 * Returns: {Boolean}
 
 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.
+i.e. when using [`child_process.fork()`][]), the `subprocess.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.
 
 For example, in the parent script:
 
@@ -918,8 +925,8 @@ for use within Node.js core and will not be emitted in the child's
 Applications should avoid using such messages or listening for
 `'internalMessage'` events as it is subject to change without notice.
 
-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
+The optional `sendHandle` argument that may be passed to `subprocess.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. Any data that is received and
 buffered in the socket will not be sent to the child.
@@ -932,7 +939,7 @@ 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,
 for instance, when the child process has already exited.
 
-`child.send()` will return `false` if the channel has closed or when the
+`subprocess.send()` will return `false` if the channel has closed or when the
 backlog of unsent messages exceeds a threshold that makes it unwise to send
 more. Otherwise, the method returns `true`. The `callback` function can be
 used to implement flow control.
@@ -943,15 +950,15 @@ The `sendHandle` argument can be used, for instance, to pass the handle of
 a TCP server object to the child process as illustrated in the example below:
 
 ```js
-const child = require('child_process').fork('child.js');
+const subprocess = require('child_process').fork('subprocess.js');
 
 // Open up the server object and send the handle.
 const server = require('net').createServer();
 server.on('connection', (socket) => {
   socket.end('handled by parent');
 });
 server.listen(1337, () => {
-  child.send('server', server);
+  subprocess.send('server', server);
 });
 ```
 
@@ -982,8 +989,8 @@ socket to the child process. The example below spawns two children that each
 handle connections with "normal" or "special" priority:
 
 ```js
-const normal = require('child_process').fork('child.js', ['normal']);
-const special = require('child_process').fork('child.js', ['special']);
+const normal = require('child_process').fork('subprocess.js', ['normal']);
+const special = require('child_process').fork('subprocess.js', ['special']);
 
 // Open up the server and send sockets to child
 const server = require('net').createServer();
@@ -1000,8 +1007,8 @@ server.on('connection', (socket) => {
 server.listen(1337);
 ```
 
-The `child.js` would receive the socket handle as the second argument passed
-to the event callback function:
+The `subprocess.js` would receive the socket handle as the second argument
+passed to the event callback function:
 
 ```js
 process.on('message', (m, socket) => {
@@ -1018,7 +1025,8 @@ this occurs.
 
 *Note: this function uses [`JSON.stringify()`][] internally to serialize the `message`.*
 
-### child.stderr
+<a name="child_process_child_stderr"></a>
+### subprocess.stderr
 <!-- YAML
 added: v0.1.90
 -->
@@ -1030,10 +1038,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 `undefined`.
 
-`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
+<a name="child_process_child_stdin"></a>
+### subprocess.stdin
 <!-- YAML
 added: v0.1.90
 -->
@@ -1048,10 +1057,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 `undefined`.
 
-`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
+<a name="child_process_child_stdio"></a>
+### subprocess.stdio
 <!-- YAML
 added: v0.7.10
 -->
@@ -1060,38 +1070,39 @@ 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 parents stdin for child
       'pipe', // Pipe child's stdout to parent
       fs.openSync('err.out', 'w') // Direct child's stderr to a file
     ]
 });
 
-assert.equal(child.stdio[0], null);
-assert.equal(child.stdio[0], child.stdin);
+assert.equal(subprocess.stdio[0], null);
+assert.equal(subprocess.stdio[0], subprocess.stdin);
 
-assert(child.stdout);
-assert.equal(child.stdio[1], child.stdout);
+assert(subprocess.stdout);
+assert.equal(subprocess.stdio[1], subprocess.stdout);
 
-assert.equal(child.stdio[2], null);
-assert.equal(child.stdio[2], child.stderr);
+assert.equal(subprocess.stdio[2], null);
+assert.equal(subprocess.stdio[2], subprocess.stderr);
 ```
 
-### child.stdout
+<a name="child_process_child_stdout"></a>
+### subprocess.stdout
 <!-- YAML
 added: v0.1.90
 -->
@@ -1103,8 +1114,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 `undefined`.
 
-`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.
 
 [`popen(3)`]: http://linux.die.net/man/3/popen
 [`ChildProcess`]: #child_process_child_process