It is possible to stream data through a child's `stdin`, `stdout`, and
`stderr` in a fully non-blocking way. (Note that some programs use
line-buffered I/O internally. That doesn't affect node.js but it means
-data you send to the child process is not immediately consumed.)
+data you send to the child process may not be immediately consumed.)
To create a child process use `require('child_process').spawn()` or
`require('child_process').fork()`. The semantics of each are slightly
-different, and explained below.
+different, and explained [below](#child_process_asynchronous_process_creation).
+
+For scripting purposes you may find the
+[synchronous counterparts](#child_process_synchronous_process_creation) more
+convenient.
## Class: ChildProcess
which can be piped to and from.
The ChildProcess class is not intended to be used directly. Use the
-`spawn()` or `fork()` methods to create a Child Process instance.
+`spawn()`, `exec()`, `execFile()`, or `fork()` methods to create a Child
+Process instance.
### Event: 'error'
Note that you can also call `process.disconnect()` in the child process when the
child process has any open IPC channels with the parent (i.e `fork()`).
-## child_process.spawn(command, [args], [options])
+## Asynchronous Process Creation
+
+These methods follow the common async programming patterns (accepting a
+callback or returning an EventEmitter).
+
+### child_process.spawn(command, [args], [options])
* `command` {String} The command to run
* `args` {Array} List of string arguments
Launches a new process with the given `command`, with command line arguments in `args`.
If omitted, `args` defaults to an empty Array.
-The third argument is used to specify additional options, which defaults to:
+The third argument is used to specify additional options, with these defaults:
{ cwd: undefined,
env: process.env
console.log('Failed to start child process.');
});
-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.
-
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:
See also: `child_process.exec()` and `child_process.fork()`
-## child_process.exec(command, [options], callback)
+### child_process.exec(command, [options], callback)
* `command` {String} The command to run, with space-separated arguments
* `options` {Object}
the child process is killed.
-## child_process.execFile(file, [args], [options], [callback])
+### child_process.execFile(file, [args], [options], [callback])
* `file` {String} The filename of the program to run
* `args` {Array} List of string arguments
leaner than `child_process.exec`. It has the same options.
-## child_process.fork(modulePath, [args], [options])
+### child_process.fork(modulePath, [args], [options])
* `modulePath` {String} The module to run in the child
* `args` {Array} List of string arguments
environmental variable `NODE_CHANNEL_FD` on the child process. The input and
output on this fd is expected to be line delimited JSON objects.
-## child_process.spawnSync(command, [args], [options])
+## Synchronous Process Creation
+
+These methods are **synchronous**, meaning they **WILL** block the event loop,
+pausing execution of your code until the spawned process exits.
+
+Blocking calls like these are mostly useful for simplifying general purpose
+scripting tasks and for simplifying the loading/processing of application
+configuration at startup.
+
+### child_process.spawnSync(command, [args], [options])
* `command` {String} The command to run
* `args` {Array} List of string arguments
the `SIGTERM` signal and doesn't exit, your process will wait until the child
process has exited.
-## child_process.execFileSync(command, [args], [options])
+### child_process.execFileSync(command, [args], [options])
* `command` {String} The command to run
* `args` {Array} List of string arguments
[`child_process.spawnSync`](#child_process_child_process_spawnsync_command_args_options)
-## child_process.execSync(command, [options])
+### child_process.execSync(command, [options])
* `command` {String} The command to run
* `options` {Object}
--- /dev/null
+// Copyright Joyent, Inc. and other Node contributors.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a
+// copy of this software and associated documentation files (the
+// "Software"), to deal in the Software without restriction, including
+// without limitation the rights to use, copy, modify, merge, publish,
+// distribute, sublicense, and/or sell copies of the Software, and to permit
+// persons to whom the Software is furnished to do so, subject to the
+// following conditions:
+//
+// The above copyright notice and this permission notice shall be included
+// in all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+// NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+// USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+var common = require('../common');
+var assert = require('assert');
+
+var spawn = require('child_process').spawn;
+
+var isWindows = process.platform === 'win32';
+
+process.env.HELLO = 'WORLD';
+
+if (isWindows) {
+ var child = spawn('cmd.exe', ['/c', 'set'], {});
+} else {
+ var child = spawn('/usr/bin/env', [], {});
+}
+
+var response = '';
+
+child.stdout.setEncoding('utf8');
+
+child.stdout.on('data', function(chunk) {
+ console.log('stdout: ' + chunk);
+ response += chunk;
+});
+
+process.on('exit', function() {
+ assert.ok(response.indexOf('HELLO=WORLD') >= 0,
+ 'spawn did not use process.env as default');
+});