doc/api/child_process.markdown

   1 # Child Process
   2
   3     Stability: 3 - Stable
   4
   5 Node provides a tri-directional `popen(3)` facility through the
   6 `child_process` module.
   7
   8 It is possible to stream data through a child's `stdin`, `stdout`, and
   9 `stderr` in a fully non-blocking way.
  10
  11 To create a child process use `require('child_process').spawn()` or
  12 `require('child_process').fork()`.  The semantics of each are slightly
  13 different, and explained below.
  14
  15 ## Class: ChildProcess
  16
  17 `ChildProcess` is an `EventEmitter`.
  18
  19 Child processes always have three streams associated with them. `child.stdin`,
  20 `child.stdout`, and `child.stderr`.  These may be shared with the stdio
  21 streams of the parent process, or they may be separate stream objects
  22 which can be piped to and from.
  23
  24 The ChildProcess class is not intended to be used directly.  Use the
  25 `spawn()` or `fork()` methods to create a Child Process instance.
  26
  27 ### Event:  'exit'
  28
  29 * `code` {Number} the exit code, if it exited normally.
  30 * `signal` {String} the signal passed to kill the child process, if it
  31   was killed by the parent.
  32
  33 This event is emitted after the child process ends. If the process terminated
  34 normally, `code` is the final exit code of the process, otherwise `null`. If
  35 the process terminated due to receipt of a signal, `signal` is the string name
  36 of the signal, otherwise `null`.
  37
  38 Note that the child process stdio streams might still be open.
  39
  40 See `waitpid(2)`.
  41
  42 ### Event: 'close'
  43
  44 This event is emitted when the stdio streams of a child process have all
  45 terminated.  This is distinct from 'exit', since multiple processes
  46 might share the same stdio streams.
  47
  48 ### Event: 'disconnect'
  49
  50 This event is emitted after using the `.disconnect()` method in the parent or
  51 in the child. After disconnecting it is no longer possible to send messages.
  52 An alternative way to check if you can send messages is to see if the
  53 `child.connected` property is `true`.
  54
  55 ### Event: 'message'
  56
  57 * `message` {Object} a parsed JSON object or primitive value
  58 * `sendHandle` {Handle object} a handle object
  59
  60 Messages send by `.send(message, [sendHandle])` are obtained using the
  61 `message` event.
  62
  63 ### child.stdin
  64
  65 * {Stream object}
  66
  67 A `Writable Stream` that represents the child process's `stdin`.
  68 Closing this stream via `end()` often causes the child process to terminate.
  69
  70 If the child stdio streams are shared with the parent, then this will
  71 not be set.
  72
  73 ### child.stdout
  74
  75 * {Stream object}
  76
  77 A `Readable Stream` that represents the child process's `stdout`.
  78
  79 If the child stdio streams are shared with the parent, then this will
  80 not be set.
  81
  82 ### child.stderr
  83
  84 * {Stream object}
  85
  86 A `Readable Stream` that represents the child process's `stderr`.
  87
  88 If the child stdio streams are shared with the parent, then this will
  89 not be set.
  90
  91 ### child.pid
  92
  93 * {Integer}
  94
  95 The PID of the child process.
  96
  97 Example:
  98
  99     var spawn = require('child_process').spawn,
 100         grep  = spawn('grep', ['ssh']);
 101
 102     console.log('Spawned child pid: ' + grep.pid);
 103     grep.stdin.end();
 104
 105 ### child.kill([signal])
 106
 107 * `signal` {String}
 108
 109 Send a signal to the child process. If no argument is given, the process will
 110 be sent `'SIGTERM'`. See `signal(7)` for a list of available signals.
 111
 112     var spawn = require('child_process').spawn,
 113         grep  = spawn('grep', ['ssh']);
 114
 115     grep.on('exit', function (code, signal) {
 116       console.log('child process terminated due to receipt of signal '+signal);
 117     });
 118
 119     // send SIGHUP to process
 120     grep.kill('SIGHUP');
 121
 122 Note that while the function is called `kill`, the signal delivered to the child
 123 process may not actually kill it.  `kill` really just sends a signal to a process.
 124
 125 See `kill(2)`
 126
 127 ### child.send(message, [sendHandle])
 128
 129 * `message` {Object}
 130 * `sendHandle` {Handle object}
 131
 132 When useing `child_process.fork()` an you can write to the child using
 133 `child.send(message, [sendHandle])` and messages are received by
 134 a `'message'` event on the child.
 135
 136 For example:
 137
 138     var cp = require('child_process');
 139
 140     var n = cp.fork(__dirname + '/sub.js');
 141
 142     n.on('message', function(m) {
 143       console.log('PARENT got message:', m);
 144     });
 145
 146     n.send({ hello: 'world' });
 147
 148 And then the child script, `'sub.js'` might look like this:
 149
 150     process.on('message', function(m) {
 151       console.log('CHILD got message:', m);
 152     });
 153
 154     process.send({ foo: 'bar' });
 155
 156 In the child the `process` object will have a `send()` method, and `process`
 157 will emit objects each time it receives a message on its channel.
 158
 159 There is a special case when sending a `{cmd: 'NODE_foo'}` message. All messages
 160 containing a `NODE_` prefix in its `cmd` property will not be emitted in
 161 the `message` event, since they are internal messages used by node core.
 162 Messages containing the prefix are emitted in the `internalMessage` event, you
 163 should by all means avoid using this feature, it is subject to change without notice.
 164
 165 The `sendHandle` option to `child.send()` is for sending a handle object to
 166 another process. The child will receive the object as its second argument to
 167 the `message` event.
 168
 169 ### child.disconnect()
 170
 171 To close the IPC connection between parent and child use the
 172 `child.disconnect()` method. This allows the child to exit gracefully since
 173 there is no IPC channel keeping it alive. When calling this method the
 174 `disconnect` event will be emitted in both parent and child, and the
 175 `connected` flag will be set to `false`. Please note that you can also call
 176 `process.disconnect()` in the child process.
 177
 178 ## child_process.spawn(command, [args], [options])
 179
 180 * `command` {String} The command to run
 181 * `args` {Array} List of string arguments
 182 * `options` {Object}
 183   * `cwd` {String} Current working directory of the child process
 184   * `customFds` {Array} **Deprecated** File descriptors for the child to use
 185     for stdio.  (See below)
 186   * `env` {Object} Environment key-value pairs
 187   * `setsid` {Boolean}
 188 * return: {ChildProcess object}
 189
 190 Launches a new process with the given `command`, with  command line arguments in `args`.
 191 If omitted, `args` defaults to an empty Array.
 192
 193 The third argument is used to specify additional options, which defaults to:
 194
 195     { cwd: undefined,
 196       env: process.env
 197     }
 198
 199 `cwd` allows you to specify the working directory from which the process is spawned.
 200 Use `env` to specify environment variables that will be visible to the new process.
 201
 202 Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the exit code:
 203
 204     var util  = require('util'),
 205         spawn = require('child_process').spawn,
 206         ls    = spawn('ls', ['-lh', '/usr']);
 207
 208     ls.stdout.on('data', function (data) {
 209       console.log('stdout: ' + data);
 210     });
 211
 212     ls.stderr.on('data', function (data) {
 213       console.log('stderr: ' + data);
 214     });
 215
 216     ls.on('exit', function (code) {
 217       console.log('child process exited with code ' + code);
 218     });
 219
 220
 221 Example: A very elaborate way to run 'ps ax | grep ssh'
 222
 223     var util  = require('util'),
 224         spawn = require('child_process').spawn,
 225         ps    = spawn('ps', ['ax']),
 226         grep  = spawn('grep', ['ssh']);
 227
 228     ps.stdout.on('data', function (data) {
 229       grep.stdin.write(data);
 230     });
 231
 232     ps.stderr.on('data', function (data) {
 233       console.log('ps stderr: ' + data);
 234     });
 235
 236     ps.on('exit', function (code) {
 237       if (code !== 0) {
 238         console.log('ps process exited with code ' + code);
 239       }
 240       grep.stdin.end();
 241     });
 242
 243     grep.stdout.on('data', function (data) {
 244       console.log(data);
 245     });
 246
 247     grep.stderr.on('data', function (data) {
 248       console.log('grep stderr: ' + data);
 249     });
 250
 251     grep.on('exit', function (code) {
 252       if (code !== 0) {
 253         console.log('grep process exited with code ' + code);
 254       }
 255     });
 256
 257
 258 Example of checking for failed exec:
 259
 260     var spawn = require('child_process').spawn,
 261         child = spawn('bad_command');
 262
 263     child.stderr.setEncoding('utf8');
 264     child.stderr.on('data', function (data) {
 265       if (/^execvp\(\)/.test(data)) {
 266         console.log('Failed to start child process.');
 267       }
 268     });
 269
 270 Note that if spawn receives an empty options object, it will result in
 271 spawning the process with an empty environment rather than using
 272 `process.env`. This due to backwards compatibility issues with a deprecated
 273 API.
 274
 275 There is a deprecated option called `customFds` which allows one to specify
 276 specific file descriptors for the stdio of the child process. This API was
 277 not portable to all platforms and therefore removed.
 278 With `customFds` it was possible to hook up the new process' `[stdin, stdout,
 279 stderr]` to existing streams; `-1` meant that a new stream should be created.
 280 Use at your own risk.
 281
 282 There are several internal options. In particular `stdinStream`,
 283 `stdoutStream`, `stderrStream`. They are for INTERNAL USE ONLY. As with all
 284 undocumented APIs in Node, they should not be used.
 285
 286 See also: `child_process.exec()` and `child_process.fork()`
 287
 288 ## child_process.exec(command, [options], callback)
 289
 290 * `command` {String} The command to run, with space-separated arguments
 291 * `options` {Object}
 292   * `cwd` {String} Current working directory of the child process
 293   * `customFds` {Array} **Deprecated** File descriptors for the child to use
 294     for stdio.  (See below)
 295   * `env` {Object} Environment key-value pairs
 296   * `setsid` {Boolean}
 297   * `encoding` {String} (Default: 'utf8')
 298   * `timeout` {Number} (Default: 0)
 299   * `maxBuffer` {Number} (Default: 200*1024)
 300   * `killSignal` {String} (Default: 'SIGTERM')
 301 * `callback` {Function} called with the output when process terminates
 302   * `error` {Error}
 303   * `stdout` {Buffer}
 304   * `stderr` {Buffer}
 305 * Return: ChildProcess object
 306
 307 Runs a command in a shell and buffers the output.
 308
 309     var util = require('util'),
 310         exec = require('child_process').exec,
 311         child;
 312
 313     child = exec('cat *.js bad_file | wc -l',
 314       function (error, stdout, stderr) {
 315         console.log('stdout: ' + stdout);
 316         console.log('stderr: ' + stderr);
 317         if (error !== null) {
 318           console.log('exec error: ' + error);
 319         }
 320     });
 321
 322 The callback gets the arguments `(error, stdout, stderr)`. On success, `error`
 323 will be `null`.  On error, `error` will be an instance of `Error` and `err.code`
 324 will be the exit code of the child process, and `err.signal` will be set to the
 325 signal that terminated the process.
 326
 327 There is a second optional argument to specify several options. The
 328 default options are
 329
 330     { encoding: 'utf8',
 331       timeout: 0,
 332       maxBuffer: 200*1024,
 333       killSignal: 'SIGTERM',
 334       cwd: null,
 335       env: null }
 336
 337 If `timeout` is greater than 0, then it will kill the child process
 338 if it runs longer than `timeout` milliseconds. The child process is killed with
 339 `killSignal` (default: `'SIGTERM'`). `maxBuffer` specifies the largest
 340 amount of data allowed on stdout or stderr - if this value is exceeded then
 341 the child process is killed.
 342
 343
 344 ## child_process.execFile(file, args, options, callback)
 345
 346 * `file` {String} The filename of the program to run
 347 * `args` {Array} List of string arguments
 348 * `options` {Object}
 349   * `cwd` {String} Current working directory of the child process
 350   * `customFds` {Array} **Deprecated** File descriptors for the child to use
 351     for stdio.  (See below)
 352   * `env` {Object} Environment key-value pairs
 353   * `setsid` {Boolean}
 354   * `encoding` {String} (Default: 'utf8')
 355   * `timeout` {Number} (Default: 0)
 356   * `maxBuffer` {Number} (Default: 200*1024)
 357   * `killSignal` {String} (Default: 'SIGTERM')
 358 * `callback` {Function} called with the output when process terminates
 359   * `error` {Error}
 360   * `stdout` {Buffer}
 361   * `stderr` {Buffer}
 362 * Return: ChildProcess object
 363
 364 This is similar to `child_process.exec()` except it does not execute a
 365 subshell but rather the specified file directly. This makes it slightly
 366 leaner than `child_process.exec`. It has the same options.
 367
 368
 369 ## child_process.fork(modulePath, [args], [options])
 370
 371 * `modulePath` {String} The module to run in the child
 372 * `args` {Array} List of string arguments
 373 * `options` {Object}
 374   * `cwd` {String} Current working directory of the child process
 375   * `customFds` {Array} **Deprecated** File descriptors for the child to use
 376     for stdio.  (See below)
 377   * `env` {Object} Environment key-value pairs
 378   * `setsid` {Boolean}
 379   * `encoding` {String} (Default: 'utf8')
 380   * `timeout` {Number} (Default: 0)
 381 * Return: ChildProcess object
 382
 383 This is a special case of the `spawn()` functionality for spawning Node
 384 processes. In addition to having all the methods in a normal ChildProcess
 385 instance, the returned object has a communication channel built-in. Se
 386 `child.send(message, [sendHandle])` for details.
 387
 388 By default the spawned Node process will have the stdout, stderr associated
 389 with the parent's. To change this behavior set the `silent` property in the
 390 `options` object to `true`.
 391
 392 These child Nodes are still whole new instances of V8. Assume at least 30ms
 393 startup and 10mb memory for each new Node. That is, you cannot create many
 394 thousands of them.