+## Class: ChildProcess
+
+Instances of the `ChildProcess` class are [`EventEmitters`][] that represent
+spawned child processes.
+
+Instances of `ChildProcess` are not intended to be created directly. Rather,
+use the [`child_process.spawn()`][], [`child_process.exec()`][],
+[`child_process.execFile()`][], or [`child_process.fork()`][] methods to create
+instances of `ChildProcess`.
+
+### Event: 'close'
+
+* `code` {Number} the exit code if the child exited on its own.
+* `signal` {String} the signal by which the child process was terminated.
+
+The `'close'` event is emitted when the stdio streams of a child process have
+been closed. This is distinct from the `'exit'` event, since multiple
+processes might share the same stdio streams.
+
+### Event: 'disconnect'
+
+The `'disconnect'` event is emitted after calling the
+`ChildProcess.disconnect()` method in the parent or child process. After
+disconnecting it is no longer possible to send or receive messages, and the
+`ChildProcess.connected` property is false.
+
+### Event: 'error'
+
+* `err` {Error Object} the error.
+
+The `'error'` event is emitted whenever:
+
+1. The process could not be spawned, or
+2. The process could not be killed, or
+3. Sending a message to the child process failed.
+
+Note that the `'exit'` event may or may not fire after an error has occurred.
+If you are listening to both the `'exit'` and `'error'` events, it is important
+to guard against accidentally invoking handler functions multiple times.
+
+See also [`ChildProcess#kill()`][] and [`ChildProcess#send()`][].
+
+### Event: 'exit'
+
+* `code` {Number} the exit code if the child exited on its own.
+* `signal` {String} the signal by which the child process was terminated.
+
+The `'exit'` event is emitted after the child process ends. If the process
+exited, `code` is the final exit code of the process, otherwise `null`. If the
+process terminated due to receipt of a signal, `signal` is the string name of
+the signal, otherwise `null`. One of the two will always be non-null.
+
+Note that when the `'exit'` event is triggered, child process stdio streams
+might still be open.
+
+Also, note that Node.js establishes signal handlers for `SIGINT` and
+`SIGTERM` and Node.js processes will not terminate immediately due to receipt
+of those signals. Rather, Node.js will perform a sequence of cleanup actions
+and then will re-raise the handled signal.
+
+See `waitpid(2)`.
+
+### Event: 'message'
+
+* `message` {Object} a parsed JSON object or primitive value.
+* `sendHandle` {Handle object} a [`net.Socket`][] or [`net.Server`][] object, or
+ undefined.
+
+The `'message'` event is triggered when a child process uses `process.send()`
+to send messages.
+
+### child.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.
+
+### child.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.
+
+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()`.
+
+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])
+
+* `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.
+
+ const spawn = require('child_process').spawn;
+ const grep = spawn('grep', ['ssh']);
+
+ grep.on('close', (code, signal) => {
+ console.log(
+ `child process terminated due to receipt of signal ${signal}`);
+ });
+
+ // Send SIGHUP to process
+ grep.kill('SIGHUP');
+
+The `ChildProcess` object may emit an `'error'` event if the signal cannot be
+delivered. Sending a signal to a child process that has already exited is not
+an error but may have unforeseen consequences. Specifically, if the process
+identifier (PID) has been reassigned to another process, the signal will be
+delivered to that process instead which can have unexpected results.
+
+Note that while the function is called `kill`, the signal delivered to the
+child process may not actually terminate the process.
+
+See `kill(2)`
+
+### child.pid
+
+* {Integer}
+
+Returns the process identifier (PID) of the child process.
+
+Example:
+
+ const spawn = require('child_process').spawn;
+ const grep = spawn('grep', ['ssh']);
+
+ console.log(`Spawned child pid: ${grep.pid}`);
+ grep.stdin.end();
+
+### child.send(message[, sendHandle][, callback])
+
+* `message` {Object}
+* `sendHandle` {Handle object}
+* `callback` {Function}
+* Return: 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.
+
+For example, in the parent script:
+
+ const cp = require('child_process');
+ const n = cp.fork(`${__dirname}/sub.js`);
+
+ n.on('message', (m) => {
+ console.log('PARENT got message:', m);
+ });
+
+ n.send({ hello: 'world' });
+
+And then the child script, `'sub.js'` might look like this:
+
+ process.on('message', (m) => {
+ console.log('CHILD got message:', m);
+ });
+
+ process.send({ foo: 'bar' });
+
+Child Node.js processes will have a `process.send()` method of their own that
+allows the child to send messages back to the parent.
+
+There is a special case when sending a `{cmd: 'NODE_foo'}` message. All messages
+containing a `NODE_` prefix in its `cmd` property are considered to be reserved
+for use within Node.js core and will not be emitted in the child's
+`process.on('message')` event. Rather, such messages are emitted using the
+`process.on('internalMessage')` event and are consumed internally by Node.js.
+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
+receive the object as the second argument passed to the callback function
+registered on the `process.on('message')` event.
+
+The optional `callback` is a function that is invoked after the message is
+sent but before the child may have received it. The function is called with a
+single argument: `null` on success, or an [`Error`][] object on failure.
+
+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
+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.
+
+#### Example: sending a server object
+
+The `sendHandle` argument can be used, for instance, to pass the handle of
+a TSCP server object to the child process as illustrated in the example below:
+
+ const child = require('child_process').fork('child.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);
+ });
+
+The child would then receive the server object as:
+
+ process.on('message', (m, server) => {
+ if (m === 'server') {
+ server.on('connection', (socket) => {
+ socket.end('handled by child');
+ });
+ }
+ });
+
+Once the server is now shared between the parent and child, some connections
+can be handled by the parent and some by the child.
+
+While the example above uses a server created using the `net` module, `dgram`
+module servers use exactly the same workflow with the exceptions of listening on
+a `'message'` event instead of `'connection'` and using `server.bind` instead of
+`server.listen`. This is, however, currently only supported on UNIX platforms.
+
+#### Example: sending a socket object
+
+Similarly, the `sendHandler` argument can be used to pass the handle of a
+socket to the child process. The example below spawns two children that each
+handle connections with "normal" or "special" priority:
+
+ const normal = require('child_process').fork('child.js', ['normal']);
+ const special = require('child_process').fork('child.js', ['special']);
+
+ // Open up the server and send sockets to child
+ const server = require('net').createServer();
+ server.on('connection', (socket) => {
+
+ // If this is special priority
+ if (socket.remoteAddress === '74.125.127.100') {
+ special.send('socket', socket);
+ return;
+ }
+ // This is normal priority
+ normal.send('socket', socket);
+ });
+ server.listen(1337);
+
+The `child.js` would receive the socket handle as the second argument passed
+to the event callback function:
+
+ process.on('message', (m, socket) => {
+ if (m === 'socket') {
+ socket.end(`Request handled with ${process.argv[2]} priority`);
+ }
+ });
+
+Once a socket has been passed to a child, the parent is no longer capable of
+tracking when the socket is destroyed. To indicate this, the `.connections`
+property becomes `null`. It is recommended not to use `.maxConnections` when
+this occurs.
+
+### child.stderr
+
+* {Stream object}
+
+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.
+
+### child.stdin
+
+* {Stream object}
+
+A `Writable Stream` that represents the child process's `stdin`.
+
+*Note that if a child process waits to read all of its input, the child will not
+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.
+
+### child.stdio
+
+* {Array}
+
+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.
+
+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`.
+
+ const assert = require('assert');
+ const fs = require('fs');
+ const child_process = require('child_process');
+
+ const 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.stdout
+
+* {Stream object}
+
+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.
+
+[`popen(3)`]: http://linux.die.net/man/3/popen