From 0fa09dfd77b7d621921a4d86671daedc35e93358 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/14635 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 | 141 +++++++++++++++++++++------------------ 1 file changed, 76 insertions(+), 65 deletions(-) diff --git a/doc/api/child_process.md b/doc/api/child_process.md index e60416ed2c22d0..2730f403771b83 100644 --- a/doc/api/child_process.md +++ b/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 + +### subprocess.connected * {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() + +### 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').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 + +### subprocess.pid @@ -869,7 +874,8 @@ console.log(`Spawned child pid: ${grep.pid}`); grep.stdin.end(); ``` -### child.send(message[, sendHandle][, callback]) + +### subprocess.send(message[, sendHandle[, options]][, callback]) @@ -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,7 +950,7 @@ 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(); @@ -951,7 +958,7 @@ 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 + +### subprocess.stderr @@ -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 + +### subprocess.stdin @@ -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 + +### subprocess.stdio @@ -1060,20 +1070,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 parents stdin for child 'pipe', // Pipe child's stdout to parent @@ -1081,17 +1091,18 @@ const child = child_process.spawn('ls', { ] }); -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 + +### subprocess.stdout @@ -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