diff --git a/doc/api/child_process.markdown b/doc/api/child_process.markdown index bfcfbe0bfe07..7f1bb8004371 100644 --- a/doc/api/child_process.markdown +++ b/doc/api/child_process.markdown @@ -90,29 +90,71 @@ Messages send by `.send(message, [sendHandle])` are obtained using the * {Stream object} A `Writable Stream` that represents the child process's `stdin`. -Closing this stream via `end()` often causes the child process to terminate. +If the child is waiting to read all its input, it will not continue until this +stream has been closed via `end()`. -If the child stdio streams are shared with the parent, then this will +If the child was not spawned with `stdio[0]` set to `'pipe'`, then this will not be set. +`child.stdin` is shorthand for `child.stdio[0]`. Both properties will refer +to the same object, or null. + ### child.stdout * {Stream object} A `Readable Stream` that represents the child process's `stdout`. -If the child stdio streams are shared with the parent, then this will +If the child was not spawned with `stdio[1]` set to `'pipe'`, then this will not be set. +`child.stdout` is shorthand for `child.stdio[1]`. Both properties will refer +to the same object, or null. + ### child.stderr * {Stream object} A `Readable Stream` that represents the child process's `stderr`. -If the child stdio streams are shared with the parent, then this will +If the child was not spawned with `stdio[2]` set to `'pipe'`, then this will not be set. +`child.stderr` is shorthand for `child.stdio[2]`. Both properties will refer +to the same object, or null. + +### child.stdio + +* {Array} + +A sparse array of pipes to the child process, corresponding with positions in +the [stdio](#child_process_options_stdio) option to +[spawn](#child_process_child_process_spawn_command_args_options) that have been +set to `'pipe'`. +Note that streams 0-2 are also available as ChildProcess.stdin, +ChildProcess.stdout, and ChildProcess.stderr, respectively. + +In the following example, only the child's fd `1` is setup as a pipe, so only +the parent's `child.stdio[1]` is a stream, all other values in the array are +`null`. + + child = 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(child.stdout); + assert.equal(child.stdio[1], child.stdout); + + assert.equal(child.stdio[2], null); + assert.equal(child.stdio[2], child.stderr); + ### child.pid * {Integer} @@ -299,11 +341,13 @@ child process has any open IPC channels with the parent (i.e `fork()`). * `args` {Array} List of string arguments * `options` {Object} * `cwd` {String} Current working directory of the child process - * `stdio` {Array|String} Child's stdio configuration. (See below) - * `customFds` {Array} **Deprecated** File descriptors for the child to use - for stdio. (See below) * `env` {Object} Environment key-value pairs - * `detached` {Boolean} The child will be a process group leader. (See below) + * `stdio` {Array|String} Child's stdio configuration. (See + [below](#child_process_options_stdio)) + * `customFds` {Array} **Deprecated** File descriptors for the child to use + for stdio. (See [below](#child_process_options_customFds)) + * `detached` {Boolean} The child will be a process group leader. (See + [below](#child_process_options_detached)) * `uid` {Number} Sets the user identity of the process. (See setuid(2).) * `gid` {Number} Sets the group identity of the process. (See setgid(2).) * return: {ChildProcess object} @@ -317,8 +361,11 @@ The third argument is used to specify additional options, which defaults to: env: process.env } -`cwd` allows you to specify the working directory from which the process is spawned. -Use `env` to specify environment variables that will be visible to the new process. +Use `cwd` to specify the working directory from which the process is spawned. +If not given, the default is to inherit the current working directory. + +Use `env` to specify environment variables that will be visible to the new +process, the default is `process.env`. Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the exit code: @@ -374,24 +421,16 @@ Example: A very elaborate way to run 'ps ax | grep ssh' }); -Example of checking for failed exec: - - var spawn = require('child_process').spawn, - child = spawn('bad_command'); +### options.stdio - child.stderr.setEncoding('utf8'); - child.stderr.on('data', function (data) { - if (/^execvp\(\)/.test(data)) { - console.log('Failed to start child process.'); - } - }); +As a shorthand, the `stdio` argument may also be one of the following +strings: -Note that if spawn receives an empty options object, it will result in -spawning the process with an empty environment rather than using -`process.env`. This due to backwards compatibility issues with a deprecated -API. +* `'pipe'` - `['pipe', 'pipe', 'pipe']`, this is the default value +* `'ignore'` - `['ignore', 'ignore', 'ignore']` +* `'inherit'` - `[process.stdin, process.stdout, process.stderr]` or `[0,1,2]` -The 'stdio' option to `child_process.spawn()` is an array where each +Otherwise, the 'stdio' option to `child_process.spawn()` is an array where each index corresponds to a fd in the child. The value is one of the following: 1. `'pipe'` - Create a pipe between the child process and the parent process. @@ -422,13 +461,6 @@ index corresponds to a fd in the child. The value is one of the following: words, stdin, stdout, and stderr) a pipe is created. For fd 3 and up, the default is `'ignore'`. -As a shorthand, the `stdio` argument may also be one of the following -strings, rather than an array: - -* `ignore` - `['ignore', 'ignore', 'ignore']` -* `pipe` - `['pipe', 'pipe', 'pipe']` -* `inherit` - `[process.stdin, process.stdout, process.stderr]` or `[0,1,2]` - Example: var spawn = require('child_process').spawn; @@ -443,6 +475,8 @@ Example: // startd-style interface. spawn('prg', [], { stdio: ['pipe', null, null, null, 'pipe'] }); +### options.detached + If the `detached` option is set, the child process will be made the leader of a new process group. This makes it possible for the child to continue running after the parent exits. @@ -471,6 +505,8 @@ will not stay running in the background unless it is provided with a `stdio` configuration that is not connected to the parent. If the parent's `stdio` is inherited, the child will remain attached to the controlling terminal. +### options.customFds + There is a deprecated option called `customFds` which allows one to specify specific file descriptors for the stdio of the child process. This API was not portable to all platforms and therefore removed. @@ -561,7 +597,6 @@ leaner than `child_process.exec`. It has the same options. * `options` {Object} * `cwd` {String} Current working directory of the child process * `env` {Object} Environment key-value pairs - * `encoding` {String} (Default: 'utf8') * `execPath` {String} Executable used to create the child process * `execArgv` {Array} List of string arguments passed to the executable (Default: `process.execArgv`)