@caido/quickjs-types / llrt/child_process

llrt/child_process

Classes

ChildProcess

Instances of the ChildProcess represent spawned child processes.

Instances of ChildProcess are not intended to be created directly. Rather, use the spawn method to create instances of ChildProcess.

Extends

• EventEmitter

Extended by

• ChildProcessWithoutNullStreams
• ChildProcessByStdio

Constructors

new ChildProcess()

new ChildProcess(): ChildProcess

Returns

ChildProcess

Inherited from

EventEmitter.constructor

Properties

pid?

readonly optional pid: number

Returns the process identifier (PID) of the child process. If the child process fails to spawn due to errors, then the value is undefined and error is emitted.

const { spawn } = require('child_process');
const grep = spawn('grep', ['ssh']);

console.log(`Spawned child pid: ${grep.pid}`);
grep.stdin.end();

stderr

stderr: null | DefaultReadableStream

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 null.

subprocess.stderr is an alias for subprocess.stdio[2]. Both properties will refer to the same value.

The subprocess.stderr property can be null or undefined if the child process could not be successfully spawned.

stdin

stdin: null | DefaultWritableStream

A Writable Stream that represents the child process's stdin.

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 null.

subprocess.stdin is an alias for subprocess.stdio[0]. Both properties will refer to the same value.

The subprocess.stdin property can be null or undefined if the child process could not be successfully spawned.

stdout

stdout: null | DefaultReadableStream

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 null.

subprocess.stdout is an alias for subprocess.stdio[1]. Both properties will refer to the same value.

const { spawn } = require('child_process');

const subprocess = spawn('ls');

subprocess.stdout.on('data', (data) => {
  console.log(`Received chunk ${data}`);
});

The subprocess.stdout property can be null or undefined if the child process could not be successfully spawned.

Methods

[dispose]()

[dispose](): void

Calls ChildProcess.kill with 'SIGTERM'.

Returns

void

addListener()

Call Signature

addListener(event: string, listener: (...args: any[]) => void): this

events.EventEmitter

1. close
2. error
3. exit

Parameters

Parameter	Type
event	string
listener	(...args: any[]) => void

Returns

this

Overrides

EventEmitter.addListener

Call Signature

addListener(event: "close", listener: (code: null | number, signal: null | Signals) => void): this

events.EventEmitter

1. close
2. error
3. exit

Parameters

Parameter	Type
event	"close"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Overrides

EventEmitter.addListener

Call Signature

addListener(event: "error", listener: (err: Error) => void): this

events.EventEmitter

1. close
2. error
3. exit

Parameters

Parameter	Type
event	"error"
listener	(err: Error) => void

Returns

this

Overrides

EventEmitter.addListener

Call Signature

addListener(event: "exit", listener: (code: null | number, signal: null | Signals) => void): this

events.EventEmitter

1. close
2. error
3. exit

Parameters

Parameter	Type
event	"exit"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Overrides

EventEmitter.addListener

emit()

Call Signature

emit(event: string | symbol, ...args: any[]): boolean

Synchronously calls each of the listeners registered for the event named eventName, in the order they were registered, passing the supplied arguments to each.

import { EventEmitter } from 'events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener

Parameters

Parameter	Type
event	string | symbol
...args	any[]

Returns

boolean

Overrides

EventEmitter.emit

Call Signature

emit(event: "close", code: null | number, signal: null | Signals): boolean

Parameters

Parameter	Type
event	"close"
code	null | number
signal	null | Signals

Returns

boolean

Overrides

EventEmitter.emit

Call Signature

emit(event: "error", err: Error): boolean

Parameters

Parameter	Type
event	"error"
err	Error

Returns

boolean

Overrides

EventEmitter.emit

Call Signature

emit(event: "exit", code: null | number, signal: null | Signals): boolean

Parameters

Parameter	Type
event	"exit"
code	null | number
signal	null | Signals

Returns

boolean

Overrides

EventEmitter.emit

eventNames()

eventNames(): EventKey[]

Returns an array listing the events for which the emitter has registered listeners. The values in the array are strings or Symbols.

import { EventEmitter } from 'events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]

Returns

EventKey[]

Inherited from

EventEmitter.eventNames

kill()

kill(signal?: number | Signals): boolean

The subprocess.kill() method 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. This function returns true if kill(2) succeeds, and false otherwise.

const { spawn } = require('child_process');
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.

While the function is called kill, the signal delivered to the child process may not actually terminate the process.

See kill(2) for reference.

On Windows, where POSIX signals do not exist, the signal argument will be ignored, and the process will be killed forcefully and abruptly (similar to 'SIGKILL'). See Signal Events for more details.

On Linux, child processes of child processes will not be terminated when attempting to kill their parent. This is likely to happen when running a new process in a shell or with the use of the shell option of ChildProcess:

'use strict';
const { spawn } = require('child_process');

const subprocess = spawn(
  'sh',
  [
    '-c',
    `node -e "setInterval(() => {
      console.log(process.pid, 'is alive')
    }, 500);"`,
  ], {
    stdio: ['inherit', 'inherit', 'inherit'],
  },
);

setTimeout(() => {
  subprocess.kill(); // Does not terminate the Node.js process in the shell.
}, 2000);

Parameters

Parameter	Type
signal?	number | Signals

Returns

boolean

off()

off<K>(eventName: EventKey, listener: (...args: any[]) => void): this

Alias for emitter.removeListener().

Type Parameters

Type Parameter
K

Parameters

Parameter	Type
eventName	EventKey
listener	(...args: any[]) => void

Returns

this

Inherited from

EventEmitter.off

on()

Call Signature

on(event: string, listener: (...args: any[]) => void): this

Adds the listener function to the end of the listeners array for the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventName and listener will result in the listener being added, and called, multiple times.

server.on('connection', (stream) => {
  console.log('someone connected!');
});

Returns a reference to the EventEmitter, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The emitter.prependListener() method can be used as an alternative to add the event listener to the beginning of the listeners array.

import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a

Parameters

Parameter	Type	Description
event	string	-
listener	(...args: any[]) => void	The callback function

Returns

this

Overrides

EventEmitter.on

Call Signature

on(event: "close", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"close"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Overrides

EventEmitter.on

Call Signature

on(event: "error", listener: (err: Error) => void): this

Parameters

Parameter	Type
event	"error"
listener	(err: Error) => void

Returns

this

Overrides

EventEmitter.on

Call Signature

on(event: "exit", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"exit"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Overrides

EventEmitter.on

once()

Call Signature

once(event: string, listener: (...args: any[]) => void): this

Adds a one-time listener function for the event named eventName. The next time eventName is triggered, this listener is removed and then invoked.

Returns a reference to the EventEmitter, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The emitter.prependOnceListener() method can be used as an alternative to add the event listener to the beginning of the listeners array.

import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a

Parameters

Parameter	Type	Description
event	string	-
listener	(...args: any[]) => void	The callback function

Returns

this

Since

v0.3.0

Overrides

EventEmitter.once

Call Signature

once(event: "close", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"close"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Overrides

EventEmitter.once

Call Signature

once(event: "error", listener: (err: Error) => void): this

Parameters

Parameter	Type
event	"error"
listener	(err: Error) => void

Returns

this

Overrides

EventEmitter.once

Call Signature

once(event: "exit", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"exit"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Overrides

EventEmitter.once

prependListener()

Call Signature

prependListener(event: string, listener: (...args: any[]) => void): this

Adds the listener function to the beginning of the listeners array for the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventName and listener will result in the listener being added, and called, multiple times.

Returns a reference to the EventEmitter, so that calls can be chained.

Parameters

Parameter	Type	Description
event	string	-
listener	(...args: any[]) => void	The callback function

Returns

this

Overrides

EventEmitter.prependListener

Call Signature

prependListener(event: "close", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"close"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Overrides

EventEmitter.prependListener

Call Signature

prependListener(event: "error", listener: (err: Error) => void): this

Parameters

Parameter	Type
event	"error"
listener	(err: Error) => void

Returns

this

Overrides

EventEmitter.prependListener

Call Signature

prependListener(event: "exit", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"exit"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Overrides

EventEmitter.prependListener

prependOnceListener()

Call Signature

prependOnceListener(event: string, listener: (...args: any[]) => void): this

Adds a one-timelistener function for the event named eventName to the beginning of the listeners array. The next time eventName is triggered, this listener is removed, and then invoked.

Returns a reference to the EventEmitter, so that calls can be chained.

Parameters

Parameter	Type	Description
event	string	-
listener	(...args: any[]) => void	The callback function

Returns

this

Overrides

EventEmitter.prependOnceListener

Call Signature

prependOnceListener(event: "close", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"close"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Overrides

EventEmitter.prependOnceListener

Call Signature

prependOnceListener(event: "error", listener: (err: Error) => void): this

Parameters

Parameter	Type
event	"error"
listener	(err: Error) => void

Returns

this

Overrides

EventEmitter.prependOnceListener

Call Signature

prependOnceListener(event: "exit", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"exit"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Overrides

EventEmitter.prependOnceListener

removeListener()

removeListener<K>(eventName: EventKey, listener: (...args: any[]) => void): this

Removes the specified listener from the listener array for the event named eventName.

removeListener() will remove, at most, one instance of a listener from the listener array. If any single listener has been added multiple times to the listener array for the specified eventName, then removeListener() must be called multiple times to remove each instance.

Once an event is emitted, all listeners attached to it at the time of emitting are called in order. This implies that any removeListener() calls after emitting and before the last listener finishes execution will not remove them from emit() in progress. Subsequent events behave as expected.

import { EventEmitter } from 'events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A

Because listeners are managed using an internal array, calling this will change the position indices of any listener registered after the listener being removed. This will not impact the order in which listeners are called, but it means that any copies of the listener array as returned by the emitter.listeners() method will need to be recreated.

When a single function has been added as a handler multiple times for a single event (as in the example below), removeListener() will remove the most recently added instance. In the example the once('ping') listener is removed:

import { EventEmitter } from 'events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');

Returns a reference to the EventEmitter, so that calls can be chained.

Type Parameters

Type Parameter
K

Parameters

Parameter	Type
eventName	EventKey
listener	(...args: any[]) => void

Returns

this

Inherited from

EventEmitter.removeListener

Interfaces

ChildProcessByStdio<I, O, E>

Instances of the ChildProcess represent spawned child processes.

Instances of ChildProcess are not intended to be created directly. Rather, use the spawn method to create instances of ChildProcess.

Extends

• ChildProcess

Type Parameters

Type Parameter
I extends null | DefaultWritableStream
O extends null | DefaultReadableStream
E extends null | DefaultReadableStream

Properties

pid?

readonly optional pid: number

Returns the process identifier (PID) of the child process. If the child process fails to spawn due to errors, then the value is undefined and error is emitted.

const { spawn } = require('child_process');
const grep = spawn('grep', ['ssh']);

console.log(`Spawned child pid: ${grep.pid}`);
grep.stdin.end();

Inherited from

ChildProcess.pid

stderr

stderr: E

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 null.

subprocess.stderr is an alias for subprocess.stdio[2]. Both properties will refer to the same value.

The subprocess.stderr property can be null or undefined if the child process could not be successfully spawned.

Overrides

ChildProcess.stderr

stdin

stdin: I

A Writable Stream that represents the child process's stdin.

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 null.

subprocess.stdin is an alias for subprocess.stdio[0]. Both properties will refer to the same value.

The subprocess.stdin property can be null or undefined if the child process could not be successfully spawned.

Overrides

ChildProcess.stdin

stdout

stdout: O

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 null.

subprocess.stdout is an alias for subprocess.stdio[1]. Both properties will refer to the same value.

const { spawn } = require('child_process');

const subprocess = spawn('ls');

subprocess.stdout.on('data', (data) => {
  console.log(`Received chunk ${data}`);
});

The subprocess.stdout property can be null or undefined if the child process could not be successfully spawned.

Overrides

ChildProcess.stdout

Methods

[dispose]()

[dispose](): void

Calls ChildProcess.kill with 'SIGTERM'.

Returns

void

Inherited from

ChildProcess.[dispose]

addListener()

Call Signature

addListener(event: string, listener: (...args: any[]) => void): this

events.EventEmitter

1. close
2. error
3. exit

Parameters

Parameter	Type
event	string
listener	(...args: any[]) => void

Returns

this

Inherited from

ChildProcess.addListener

Call Signature

addListener(event: "close", listener: (code: null | number, signal: null | Signals) => void): this

events.EventEmitter

1. close
2. error
3. exit

Parameters

Parameter	Type
event	"close"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Inherited from

ChildProcess.addListener

Call Signature

addListener(event: "error", listener: (err: Error) => void): this

events.EventEmitter

1. close
2. error
3. exit

Parameters

Parameter	Type
event	"error"
listener	(err: Error) => void

Returns

this

Inherited from

ChildProcess.addListener

Call Signature

addListener(event: "exit", listener: (code: null | number, signal: null | Signals) => void): this

events.EventEmitter

1. close
2. error
3. exit

Parameters

Parameter	Type
event	"exit"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Inherited from

ChildProcess.addListener

emit()

Call Signature

emit(event: string | symbol, ...args: any[]): boolean

Synchronously calls each of the listeners registered for the event named eventName, in the order they were registered, passing the supplied arguments to each.

import { EventEmitter } from 'events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener

Parameters

Parameter	Type
event	string | symbol
...args	any[]

Returns

boolean

Inherited from

ChildProcess.emit

Call Signature

emit(event: "close", code: null | number, signal: null | Signals): boolean

Parameters

Parameter	Type
event	"close"
code	null | number
signal	null | Signals

Returns

boolean

Inherited from

ChildProcess.emit

Call Signature

emit(event: "error", err: Error): boolean

Parameters

Parameter	Type
event	"error"
err	Error

Returns

boolean

Inherited from

ChildProcess.emit

Call Signature

emit(event: "exit", code: null | number, signal: null | Signals): boolean

Parameters

Parameter	Type
event	"exit"
code	null | number
signal	null | Signals

Returns

boolean

Inherited from

ChildProcess.emit

eventNames()

eventNames(): EventKey[]

Returns an array listing the events for which the emitter has registered listeners. The values in the array are strings or Symbols.

import { EventEmitter } from 'events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]

Returns

EventKey[]

Inherited from

ChildProcess.eventNames

kill()

kill(signal?: number | Signals): boolean

The subprocess.kill() method 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. This function returns true if kill(2) succeeds, and false otherwise.

const { spawn } = require('child_process');
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.

While the function is called kill, the signal delivered to the child process may not actually terminate the process.

See kill(2) for reference.

On Windows, where POSIX signals do not exist, the signal argument will be ignored, and the process will be killed forcefully and abruptly (similar to 'SIGKILL'). See Signal Events for more details.

On Linux, child processes of child processes will not be terminated when attempting to kill their parent. This is likely to happen when running a new process in a shell or with the use of the shell option of ChildProcess:

'use strict';
const { spawn } = require('child_process');

const subprocess = spawn(
  'sh',
  [
    '-c',
    `node -e "setInterval(() => {
      console.log(process.pid, 'is alive')
    }, 500);"`,
  ], {
    stdio: ['inherit', 'inherit', 'inherit'],
  },
);

setTimeout(() => {
  subprocess.kill(); // Does not terminate the Node.js process in the shell.
}, 2000);

Parameters

Parameter	Type
signal?	number | Signals

Returns

boolean

Inherited from

ChildProcess.kill

off()

off<K>(eventName: EventKey, listener: (...args: any[]) => void): this

Alias for emitter.removeListener().

Type Parameters

Type Parameter
K

Parameters

Parameter	Type
eventName	EventKey
listener	(...args: any[]) => void

Returns

this

Inherited from

ChildProcess.off

on()

Call Signature

on(event: string, listener: (...args: any[]) => void): this

Adds the listener function to the end of the listeners array for the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventName and listener will result in the listener being added, and called, multiple times.

server.on('connection', (stream) => {
  console.log('someone connected!');
});

Returns a reference to the EventEmitter, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The emitter.prependListener() method can be used as an alternative to add the event listener to the beginning of the listeners array.

import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a

Parameters

Parameter	Type	Description
event	string	-
listener	(...args: any[]) => void	The callback function

Returns

this

Inherited from

ChildProcess.on

Call Signature

on(event: "close", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"close"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Inherited from

ChildProcess.on

Call Signature

on(event: "error", listener: (err: Error) => void): this

Parameters

Parameter	Type
event	"error"
listener	(err: Error) => void

Returns

this

Inherited from

ChildProcess.on

Call Signature

on(event: "exit", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"exit"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Inherited from

ChildProcess.on

once()

Call Signature

once(event: string, listener: (...args: any[]) => void): this

Adds a one-time listener function for the event named eventName. The next time eventName is triggered, this listener is removed and then invoked.

Returns a reference to the EventEmitter, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The emitter.prependOnceListener() method can be used as an alternative to add the event listener to the beginning of the listeners array.

import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a

Parameters

Parameter	Type	Description
event	string	-
listener	(...args: any[]) => void	The callback function

Returns

this

Since

v0.3.0

Inherited from

ChildProcess.once

Call Signature

once(event: "close", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"close"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Inherited from

ChildProcess.once

Call Signature

once(event: "error", listener: (err: Error) => void): this

Parameters

Parameter	Type
event	"error"
listener	(err: Error) => void

Returns

this

Inherited from

ChildProcess.once

Call Signature

once(event: "exit", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"exit"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Inherited from

ChildProcess.once

prependListener()

Call Signature

prependListener(event: string, listener: (...args: any[]) => void): this

Adds the listener function to the beginning of the listeners array for the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventName and listener will result in the listener being added, and called, multiple times.

Returns a reference to the EventEmitter, so that calls can be chained.

Parameters

Parameter	Type	Description
event	string	-
listener	(...args: any[]) => void	The callback function

Returns

this

Inherited from

ChildProcess.prependListener

Call Signature

prependListener(event: "close", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"close"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Inherited from

ChildProcess.prependListener

Call Signature

prependListener(event: "error", listener: (err: Error) => void): this

Parameters

Parameter	Type
event	"error"
listener	(err: Error) => void

Returns

this

Inherited from

ChildProcess.prependListener

Call Signature

prependListener(event: "exit", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"exit"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Inherited from

ChildProcess.prependListener

prependOnceListener()

Call Signature

prependOnceListener(event: string, listener: (...args: any[]) => void): this

Adds a one-timelistener function for the event named eventName to the beginning of the listeners array. The next time eventName is triggered, this listener is removed, and then invoked.

Returns a reference to the EventEmitter, so that calls can be chained.

Parameters

Parameter	Type	Description
event	string	-
listener	(...args: any[]) => void	The callback function

Returns

this

Inherited from

ChildProcess.prependOnceListener

Call Signature

prependOnceListener(event: "close", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"close"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Inherited from

ChildProcess.prependOnceListener

Call Signature

prependOnceListener(event: "error", listener: (err: Error) => void): this

Parameters

Parameter	Type
event	"error"
listener	(err: Error) => void

Returns

this

Inherited from

ChildProcess.prependOnceListener

Call Signature

prependOnceListener(event: "exit", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"exit"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Inherited from

ChildProcess.prependOnceListener

removeListener()

removeListener<K>(eventName: EventKey, listener: (...args: any[]) => void): this

Removes the specified listener from the listener array for the event named eventName.

removeListener() will remove, at most, one instance of a listener from the listener array. If any single listener has been added multiple times to the listener array for the specified eventName, then removeListener() must be called multiple times to remove each instance.

Once an event is emitted, all listeners attached to it at the time of emitting are called in order. This implies that any removeListener() calls after emitting and before the last listener finishes execution will not remove them from emit() in progress. Subsequent events behave as expected.

import { EventEmitter } from 'events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A

Because listeners are managed using an internal array, calling this will change the position indices of any listener registered after the listener being removed. This will not impact the order in which listeners are called, but it means that any copies of the listener array as returned by the emitter.listeners() method will need to be recreated.

When a single function has been added as a handler multiple times for a single event (as in the example below), removeListener() will remove the most recently added instance. In the example the once('ping') listener is removed:

import { EventEmitter } from 'events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');

Returns a reference to the EventEmitter, so that calls can be chained.

Type Parameters

Type Parameter
K

Parameters

Parameter	Type
eventName	EventKey
listener	(...args: any[]) => void

Returns

this

Inherited from

ChildProcess.removeListener

---

ChildProcessWithoutNullStreams

Instances of the ChildProcess represent spawned child processes.

Instances of ChildProcess are not intended to be created directly. Rather, use the spawn method to create instances of ChildProcess.

Extends

• ChildProcess

Properties

pid?

readonly optional pid: number

Returns the process identifier (PID) of the child process. If the child process fails to spawn due to errors, then the value is undefined and error is emitted.

const { spawn } = require('child_process');
const grep = spawn('grep', ['ssh']);

console.log(`Spawned child pid: ${grep.pid}`);
grep.stdin.end();

Inherited from

ChildProcess.pid

stderr

stderr: DefaultReadableStream

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 null.

subprocess.stderr is an alias for subprocess.stdio[2]. Both properties will refer to the same value.

The subprocess.stderr property can be null or undefined if the child process could not be successfully spawned.

Overrides

ChildProcess.stderr

stdin

stdin: DefaultWritableStream

A Writable Stream that represents the child process's stdin.

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 null.

subprocess.stdin is an alias for subprocess.stdio[0]. Both properties will refer to the same value.

The subprocess.stdin property can be null or undefined if the child process could not be successfully spawned.

Overrides

ChildProcess.stdin

stdout

stdout: DefaultReadableStream

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 null.

subprocess.stdout is an alias for subprocess.stdio[1]. Both properties will refer to the same value.

const { spawn } = require('child_process');

const subprocess = spawn('ls');

subprocess.stdout.on('data', (data) => {
  console.log(`Received chunk ${data}`);
});

The subprocess.stdout property can be null or undefined if the child process could not be successfully spawned.

Overrides

ChildProcess.stdout

Methods

[dispose]()

[dispose](): void

Calls ChildProcess.kill with 'SIGTERM'.

Returns

void

Inherited from

ChildProcess.[dispose]

addListener()

Call Signature

addListener(event: string, listener: (...args: any[]) => void): this

events.EventEmitter

1. close
2. error
3. exit

Parameters

Parameter	Type
event	string
listener	(...args: any[]) => void

Returns

this

Inherited from

ChildProcess.addListener

Call Signature

addListener(event: "close", listener: (code: null | number, signal: null | Signals) => void): this

events.EventEmitter

1. close
2. error
3. exit

Parameters

Parameter	Type
event	"close"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Inherited from

ChildProcess.addListener

Call Signature

addListener(event: "error", listener: (err: Error) => void): this

events.EventEmitter

1. close
2. error
3. exit

Parameters

Parameter	Type
event	"error"
listener	(err: Error) => void

Returns

this

Inherited from

ChildProcess.addListener

Call Signature

addListener(event: "exit", listener: (code: null | number, signal: null | Signals) => void): this

events.EventEmitter

1. close
2. error
3. exit

Parameters

Parameter	Type
event	"exit"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Inherited from

ChildProcess.addListener

emit()

Call Signature

emit(event: string | symbol, ...args: any[]): boolean

Synchronously calls each of the listeners registered for the event named eventName, in the order they were registered, passing the supplied arguments to each.

import { EventEmitter } from 'events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener

Parameters

Parameter	Type
event	string | symbol
...args	any[]

Returns

boolean

Inherited from

ChildProcess.emit

Call Signature

emit(event: "close", code: null | number, signal: null | Signals): boolean

Parameters

Parameter	Type
event	"close"
code	null | number
signal	null | Signals

Returns

boolean

Inherited from

ChildProcess.emit

Call Signature

emit(event: "error", err: Error): boolean

Parameters

Parameter	Type
event	"error"
err	Error

Returns

boolean

Inherited from

ChildProcess.emit

Call Signature

emit(event: "exit", code: null | number, signal: null | Signals): boolean

Parameters

Parameter	Type
event	"exit"
code	null | number
signal	null | Signals

Returns

boolean

Inherited from

ChildProcess.emit

eventNames()

eventNames(): EventKey[]

Returns an array listing the events for which the emitter has registered listeners. The values in the array are strings or Symbols.

import { EventEmitter } from 'events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]

Returns

EventKey[]

Inherited from

ChildProcess.eventNames

kill()

kill(signal?: number | Signals): boolean

The subprocess.kill() method 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. This function returns true if kill(2) succeeds, and false otherwise.

const { spawn } = require('child_process');
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.

While the function is called kill, the signal delivered to the child process may not actually terminate the process.

See kill(2) for reference.

On Windows, where POSIX signals do not exist, the signal argument will be ignored, and the process will be killed forcefully and abruptly (similar to 'SIGKILL'). See Signal Events for more details.

On Linux, child processes of child processes will not be terminated when attempting to kill their parent. This is likely to happen when running a new process in a shell or with the use of the shell option of ChildProcess:

'use strict';
const { spawn } = require('child_process');

const subprocess = spawn(
  'sh',
  [
    '-c',
    `node -e "setInterval(() => {
      console.log(process.pid, 'is alive')
    }, 500);"`,
  ], {
    stdio: ['inherit', 'inherit', 'inherit'],
  },
);

setTimeout(() => {
  subprocess.kill(); // Does not terminate the Node.js process in the shell.
}, 2000);

Parameters

Parameter	Type
signal?	number | Signals

Returns

boolean

Inherited from

ChildProcess.kill

off()

off<K>(eventName: EventKey, listener: (...args: any[]) => void): this

Alias for emitter.removeListener().

Type Parameters

Type Parameter
K

Parameters

Parameter	Type
eventName	EventKey
listener	(...args: any[]) => void

Returns

this

Inherited from

ChildProcess.off

on()

Call Signature

on(event: string, listener: (...args: any[]) => void): this

Adds the listener function to the end of the listeners array for the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventName and listener will result in the listener being added, and called, multiple times.

server.on('connection', (stream) => {
  console.log('someone connected!');
});

Returns a reference to the EventEmitter, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The emitter.prependListener() method can be used as an alternative to add the event listener to the beginning of the listeners array.

import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a

Parameters

Parameter	Type	Description
event	string	-
listener	(...args: any[]) => void	The callback function

Returns

this

Inherited from

ChildProcess.on

Call Signature

on(event: "close", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"close"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Inherited from

ChildProcess.on

Call Signature

on(event: "error", listener: (err: Error) => void): this

Parameters

Parameter	Type
event	"error"
listener	(err: Error) => void

Returns

this

Inherited from

ChildProcess.on

Call Signature

on(event: "exit", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"exit"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Inherited from

ChildProcess.on

once()

Call Signature

once(event: string, listener: (...args: any[]) => void): this

Adds a one-time listener function for the event named eventName. The next time eventName is triggered, this listener is removed and then invoked.

Returns a reference to the EventEmitter, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The emitter.prependOnceListener() method can be used as an alternative to add the event listener to the beginning of the listeners array.

import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a

Parameters

Parameter	Type	Description
event	string	-
listener	(...args: any[]) => void	The callback function

Returns

this

Since

v0.3.0

Inherited from

ChildProcess.once

Call Signature

once(event: "close", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"close"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Inherited from

ChildProcess.once

Call Signature

once(event: "error", listener: (err: Error) => void): this

Parameters

Parameter	Type
event	"error"
listener	(err: Error) => void

Returns

this

Inherited from

ChildProcess.once

Call Signature

once(event: "exit", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"exit"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Inherited from

ChildProcess.once

prependListener()

Call Signature

prependListener(event: string, listener: (...args: any[]) => void): this

Adds the listener function to the beginning of the listeners array for the event named eventName. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of eventName and listener will result in the listener being added, and called, multiple times.

Returns a reference to the EventEmitter, so that calls can be chained.

Parameters

Parameter	Type	Description
event	string	-
listener	(...args: any[]) => void	The callback function

Returns

this

Inherited from

ChildProcess.prependListener

Call Signature

prependListener(event: "close", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"close"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Inherited from

ChildProcess.prependListener

Call Signature

prependListener(event: "error", listener: (err: Error) => void): this

Parameters

Parameter	Type
event	"error"
listener	(err: Error) => void

Returns

this

Inherited from

ChildProcess.prependListener

Call Signature

prependListener(event: "exit", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"exit"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Inherited from

ChildProcess.prependListener

prependOnceListener()

Call Signature

prependOnceListener(event: string, listener: (...args: any[]) => void): this

Adds a one-timelistener function for the event named eventName to the beginning of the listeners array. The next time eventName is triggered, this listener is removed, and then invoked.

Returns a reference to the EventEmitter, so that calls can be chained.

Parameters

Parameter	Type	Description
event	string	-
listener	(...args: any[]) => void	The callback function

Returns

this

Inherited from

ChildProcess.prependOnceListener

Call Signature

prependOnceListener(event: "close", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"close"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Inherited from

ChildProcess.prependOnceListener

Call Signature

prependOnceListener(event: "error", listener: (err: Error) => void): this

Parameters

Parameter	Type
event	"error"
listener	(err: Error) => void

Returns

this

Inherited from

ChildProcess.prependOnceListener

Call Signature

prependOnceListener(event: "exit", listener: (code: null | number, signal: null | Signals) => void): this

Parameters

Parameter	Type
event	"exit"
listener	(code: null | number, signal: null | Signals) => void

Returns

this

Inherited from

ChildProcess.prependOnceListener

removeListener()

removeListener<K>(eventName: EventKey, listener: (...args: any[]) => void): this

Removes the specified listener from the listener array for the event named eventName.

removeListener() will remove, at most, one instance of a listener from the listener array. If any single listener has been added multiple times to the listener array for the specified eventName, then removeListener() must be called multiple times to remove each instance.

Once an event is emitted, all listeners attached to it at the time of emitting are called in order. This implies that any removeListener() calls after emitting and before the last listener finishes execution will not remove them from emit() in progress. Subsequent events behave as expected.

import { EventEmitter } from 'events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A

Because listeners are managed using an internal array, calling this will change the position indices of any listener registered after the listener being removed. This will not impact the order in which listeners are called, but it means that any copies of the listener array as returned by the emitter.listeners() method will need to be recreated.

When a single function has been added as a handler multiple times for a single event (as in the example below), removeListener() will remove the most recently added instance. In the example the once('ping') listener is removed:

import { EventEmitter } from 'events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');

Returns a reference to the EventEmitter, so that calls can be chained.

Type Parameters

Type Parameter
K

Parameters

Parameter	Type
eventName	EventKey
listener	(...args: any[]) => void

Returns

this

Inherited from

ChildProcess.removeListener

---

ProcessEnvOptions

Extended by

• SpawnOptions

Properties

cwd?

optional cwd: string

gid?

optional gid: number

uid?

optional uid: number

---

SpawnOptions

Extends

• ProcessEnvOptions

Extended by

• SpawnOptionsWithoutStdio
• SpawnOptionsWithStdioTuple

Properties

cwd?

optional cwd: string

Inherited from

ProcessEnvOptions.cwd

gid?

optional gid: number

Inherited from

ProcessEnvOptions.gid

shell?

optional shell: string | boolean

stdio?

optional stdio: StdioOptions

Can be set to 'pipe', 'inherit', or 'ignore', or an array of these strings. If passed as an array, the first element is used for stdin, the second for stdout, and the third for stderr.

Default

'pipe'

uid?

optional uid: number

Inherited from

ProcessEnvOptions.uid

windowsVerbatimArguments?

optional windowsVerbatimArguments: boolean

---

SpawnOptionsWithoutStdio

Extends

• SpawnOptions

Properties

cwd?

optional cwd: string

Inherited from

SpawnOptions.cwd

gid?

optional gid: number

Inherited from

SpawnOptions.gid

shell?

optional shell: string | boolean

Inherited from

SpawnOptions.shell

stdio?

optional stdio: "pipe" | StdioPipe[]

Can be set to 'pipe', 'inherit', or 'ignore', or an array of these strings. If passed as an array, the first element is used for stdin, the second for stdout, and the third for stderr.

Default

'pipe'

Overrides

SpawnOptions.stdio

uid?

optional uid: number

Inherited from

SpawnOptions.uid

windowsVerbatimArguments?

optional windowsVerbatimArguments: boolean

Inherited from

SpawnOptions.windowsVerbatimArguments

---

SpawnOptionsWithStdioTuple<Stdin, Stdout, Stderr>

Extends

• SpawnOptions

Type Parameters

Type Parameter
Stdin extends StdioNull | StdioPipe
Stdout extends StdioNull | StdioPipe
Stderr extends StdioNull | StdioPipe

Properties

cwd?

optional cwd: string

Inherited from

SpawnOptions.cwd

gid?

optional gid: number

Inherited from

SpawnOptions.gid

shell?

optional shell: string | boolean

Inherited from

SpawnOptions.shell

stdio

stdio: [Stdin, Stdout, Stderr]

Can be set to 'pipe', 'inherit', or 'ignore', or an array of these strings. If passed as an array, the first element is used for stdin, the second for stdout, and the third for stderr.

Default

'pipe'

Overrides

SpawnOptions.stdio

uid?

optional uid: number

Inherited from

SpawnOptions.uid

windowsVerbatimArguments?

optional windowsVerbatimArguments: boolean

Inherited from

SpawnOptions.windowsVerbatimArguments

Type Aliases

IOType

IOType: "pipe" | "ignore" | "inherit"

---

StdioNull

StdioNull: "inherit" | "ignore"

---

StdioOptions

StdioOptions: IOType | (IOType | number | null | undefined)[]

---

StdioPipe

StdioPipe: undefined | null | StdioPipeNamed

---

StdioPipeNamed

StdioPipeNamed: "pipe"

Functions

spawn()

Call Signature

spawn(command: string, options?: SpawnOptionsWithoutStdio): ChildProcessWithoutNullStreams

The child_process.spawn() method spawns a new process using the given command, with command-line arguments in args. If omitted, args defaults to an empty array.

If the shell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

A third argument may be used to specify additional options.

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. If given, but the path does not exist, the child process emits an ENOENT error and exits immediately. ENOENT is also emitted when the command does not exist.

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:

const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

Example: A very elaborate way to run ps ax | grep ssh

const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

Example of checking for failed spawn:

const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});

Certain platforms (macOS, Linux) will use the value of argv[0] for the process title while others (Windows, SunOS) will use command.

Parameters

Parameter	Type	Description
command	string	The command to run.
options?	SpawnOptionsWithoutStdio	-

Returns

ChildProcessWithoutNullStreams

Call Signature

spawn(command: string, options: SpawnOptionsWithStdioTuple<StdioPipe, StdioPipe, StdioPipe>): ChildProcessByStdio<DefaultWritableStream, DefaultReadableStream, DefaultReadableStream>

The child_process.spawn() method spawns a new process using the given command, with command-line arguments in args. If omitted, args defaults to an empty array.

If the shell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

A third argument may be used to specify additional options.

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. If given, but the path does not exist, the child process emits an ENOENT error and exits immediately. ENOENT is also emitted when the command does not exist.

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:

const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

Example: A very elaborate way to run ps ax | grep ssh

const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

Example of checking for failed spawn:

const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});

Certain platforms (macOS, Linux) will use the value of argv[0] for the process title while others (Windows, SunOS) will use command.

Parameters

Parameter	Type	Description
command	string	The command to run.
options	SpawnOptionsWithStdioTuple<StdioPipe, StdioPipe, StdioPipe>	-

Returns

ChildProcessByStdio<DefaultWritableStream, DefaultReadableStream, DefaultReadableStream>

Call Signature

spawn(command: string, options: SpawnOptionsWithStdioTuple<StdioPipe, StdioPipe, StdioNull>): ChildProcessByStdio<DefaultWritableStream, DefaultReadableStream, null>

The child_process.spawn() method spawns a new process using the given command, with command-line arguments in args. If omitted, args defaults to an empty array.

If the shell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

A third argument may be used to specify additional options.

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. If given, but the path does not exist, the child process emits an ENOENT error and exits immediately. ENOENT is also emitted when the command does not exist.

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:

const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

Example: A very elaborate way to run ps ax | grep ssh

const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

Example of checking for failed spawn:

const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});

Certain platforms (macOS, Linux) will use the value of argv[0] for the process title while others (Windows, SunOS) will use command.

Parameters

Parameter	Type	Description
command	string	The command to run.
options	SpawnOptionsWithStdioTuple<StdioPipe, StdioPipe, StdioNull>	-

Returns

ChildProcessByStdio<DefaultWritableStream, DefaultReadableStream, null>

Call Signature

spawn(command: string, options: SpawnOptionsWithStdioTuple<StdioPipe, StdioNull, StdioPipe>): ChildProcessByStdio<DefaultWritableStream, null, DefaultReadableStream>

The child_process.spawn() method spawns a new process using the given command, with command-line arguments in args. If omitted, args defaults to an empty array.

If the shell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

A third argument may be used to specify additional options.

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. If given, but the path does not exist, the child process emits an ENOENT error and exits immediately. ENOENT is also emitted when the command does not exist.

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:

const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

Example: A very elaborate way to run ps ax | grep ssh

const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

Example of checking for failed spawn:

const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});

Certain platforms (macOS, Linux) will use the value of argv[0] for the process title while others (Windows, SunOS) will use command.

Parameters

Parameter	Type	Description
command	string	The command to run.
options	SpawnOptionsWithStdioTuple<StdioPipe, StdioNull, StdioPipe>	-

Returns

ChildProcessByStdio<DefaultWritableStream, null, DefaultReadableStream>

Call Signature

spawn(command: string, options: SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioPipe>): ChildProcessByStdio<null, DefaultReadableStream, DefaultReadableStream>

The child_process.spawn() method spawns a new process using the given command, with command-line arguments in args. If omitted, args defaults to an empty array.

If the shell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

A third argument may be used to specify additional options.

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. If given, but the path does not exist, the child process emits an ENOENT error and exits immediately. ENOENT is also emitted when the command does not exist.

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:

const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

Example: A very elaborate way to run ps ax | grep ssh

const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

Example of checking for failed spawn:

const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});

Certain platforms (macOS, Linux) will use the value of argv[0] for the process title while others (Windows, SunOS) will use command.

Parameters

Parameter	Type	Description
command	string	The command to run.
options	SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioPipe>	-

Returns

ChildProcessByStdio<null, DefaultReadableStream, DefaultReadableStream>

Call Signature

spawn(command: string, options: SpawnOptionsWithStdioTuple<StdioPipe, StdioNull, StdioNull>): ChildProcessByStdio<DefaultWritableStream, null, null>

The child_process.spawn() method spawns a new process using the given command, with command-line arguments in args. If omitted, args defaults to an empty array.

If the shell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

A third argument may be used to specify additional options.

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. If given, but the path does not exist, the child process emits an ENOENT error and exits immediately. ENOENT is also emitted when the command does not exist.

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:

const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

Example: A very elaborate way to run ps ax | grep ssh

const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

Example of checking for failed spawn:

const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});

Certain platforms (macOS, Linux) will use the value of argv[0] for the process title while others (Windows, SunOS) will use command.

Parameters

Parameter	Type	Description
command	string	The command to run.
options	SpawnOptionsWithStdioTuple<StdioPipe, StdioNull, StdioNull>	-

Returns

ChildProcessByStdio<DefaultWritableStream, null, null>

Call Signature

spawn(command: string, options: SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioNull>): ChildProcessByStdio<null, DefaultReadableStream, null>

The child_process.spawn() method spawns a new process using the given command, with command-line arguments in args. If omitted, args defaults to an empty array.

If the shell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

A third argument may be used to specify additional options.

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. If given, but the path does not exist, the child process emits an ENOENT error and exits immediately. ENOENT is also emitted when the command does not exist.

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:

const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

Example: A very elaborate way to run ps ax | grep ssh

const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

Example of checking for failed spawn:

const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});

Certain platforms (macOS, Linux) will use the value of argv[0] for the process title while others (Windows, SunOS) will use command.

Parameters

Parameter	Type	Description
command	string	The command to run.
options	SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioNull>	-

Returns

ChildProcessByStdio<null, DefaultReadableStream, null>

Call Signature

spawn(command: string, options: SpawnOptionsWithStdioTuple<StdioNull, StdioNull, StdioPipe>): ChildProcessByStdio<null, null, DefaultReadableStream>

The child_process.spawn() method spawns a new process using the given command, with command-line arguments in args. If omitted, args defaults to an empty array.

If the shell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

A third argument may be used to specify additional options.

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. If given, but the path does not exist, the child process emits an ENOENT error and exits immediately. ENOENT is also emitted when the command does not exist.

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:

const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

Example: A very elaborate way to run ps ax | grep ssh

const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

Example of checking for failed spawn:

const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});

Certain platforms (macOS, Linux) will use the value of argv[0] for the process title while others (Windows, SunOS) will use command.

Parameters

Parameter	Type	Description
command	string	The command to run.
options	SpawnOptionsWithStdioTuple<StdioNull, StdioNull, StdioPipe>	-

Returns

ChildProcessByStdio<null, null, DefaultReadableStream>

Call Signature

spawn(command: string, options: SpawnOptionsWithStdioTuple<StdioNull, StdioNull, StdioNull>): ChildProcessByStdio<null, null, null>

The child_process.spawn() method spawns a new process using the given command, with command-line arguments in args. If omitted, args defaults to an empty array.

If the shell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

A third argument may be used to specify additional options.

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. If given, but the path does not exist, the child process emits an ENOENT error and exits immediately. ENOENT is also emitted when the command does not exist.

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:

const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

Example: A very elaborate way to run ps ax | grep ssh

const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

Example of checking for failed spawn:

const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});

Certain platforms (macOS, Linux) will use the value of argv[0] for the process title while others (Windows, SunOS) will use command.

Parameters

Parameter	Type	Description
command	string	The command to run.
options	SpawnOptionsWithStdioTuple<StdioNull, StdioNull, StdioNull>	-

Returns

ChildProcessByStdio<null, null, null>

Call Signature

spawn(command: string, options: SpawnOptions): ChildProcess

The child_process.spawn() method spawns a new process using the given command, with command-line arguments in args. If omitted, args defaults to an empty array.

If the shell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

A third argument may be used to specify additional options.

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. If given, but the path does not exist, the child process emits an ENOENT error and exits immediately. ENOENT is also emitted when the command does not exist.

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:

const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

Example: A very elaborate way to run ps ax | grep ssh

const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

Example of checking for failed spawn:

const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});

Certain platforms (macOS, Linux) will use the value of argv[0] for the process title while others (Windows, SunOS) will use command.

Parameters

Parameter	Type	Description
command	string	The command to run.
options	SpawnOptions	-

Returns

ChildProcess

Call Signature

spawn(command: string, args?: readonly string[], options?: SpawnOptionsWithoutStdio): ChildProcessWithoutNullStreams

The child_process.spawn() method spawns a new process using the given command, with command-line arguments in args. If omitted, args defaults to an empty array.

If the shell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

A third argument may be used to specify additional options.

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. If given, but the path does not exist, the child process emits an ENOENT error and exits immediately. ENOENT is also emitted when the command does not exist.

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:

const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

Example: A very elaborate way to run ps ax | grep ssh

const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

Example of checking for failed spawn:

const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});

Certain platforms (macOS, Linux) will use the value of argv[0] for the process title while others (Windows, SunOS) will use command.

Parameters

Parameter	Type	Description
command	string	The command to run.
args?	readonly string[]	List of string arguments.
options?	SpawnOptionsWithoutStdio	-

Returns

ChildProcessWithoutNullStreams

Call Signature

spawn(command: string, args: readonly string[], options: SpawnOptionsWithStdioTuple<StdioPipe, StdioPipe, StdioPipe>): ChildProcessByStdio<DefaultWritableStream, DefaultReadableStream, DefaultReadableStream>

The child_process.spawn() method spawns a new process using the given command, with command-line arguments in args. If omitted, args defaults to an empty array.

If the shell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

A third argument may be used to specify additional options.

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. If given, but the path does not exist, the child process emits an ENOENT error and exits immediately. ENOENT is also emitted when the command does not exist.

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:

const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

Example: A very elaborate way to run ps ax | grep ssh

const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

Example of checking for failed spawn:

const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});

Certain platforms (macOS, Linux) will use the value of argv[0] for the process title while others (Windows, SunOS) will use command.

Parameters

Parameter	Type	Description
command	string	The command to run.
args	readonly string[]	List of string arguments.
options	SpawnOptionsWithStdioTuple<StdioPipe, StdioPipe, StdioPipe>	-

Returns

ChildProcessByStdio<DefaultWritableStream, DefaultReadableStream, DefaultReadableStream>

Call Signature

spawn(command: string, args: readonly string[], options: SpawnOptionsWithStdioTuple<StdioPipe, StdioPipe, StdioNull>): ChildProcessByStdio<DefaultWritableStream, DefaultReadableStream, null>

The child_process.spawn() method spawns a new process using the given command, with command-line arguments in args. If omitted, args defaults to an empty array.

If the shell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

A third argument may be used to specify additional options.

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. If given, but the path does not exist, the child process emits an ENOENT error and exits immediately. ENOENT is also emitted when the command does not exist.

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:

const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

Example: A very elaborate way to run ps ax | grep ssh

const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

Example of checking for failed spawn:

const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});

Certain platforms (macOS, Linux) will use the value of argv[0] for the process title while others (Windows, SunOS) will use command.

Parameters

Parameter	Type	Description
command	string	The command to run.
args	readonly string[]	List of string arguments.
options	SpawnOptionsWithStdioTuple<StdioPipe, StdioPipe, StdioNull>	-

Returns

ChildProcessByStdio<DefaultWritableStream, DefaultReadableStream, null>

Call Signature

spawn(command: string, args: readonly string[], options: SpawnOptionsWithStdioTuple<StdioPipe, StdioNull, StdioPipe>): ChildProcessByStdio<DefaultWritableStream, null, DefaultReadableStream>

The child_process.spawn() method spawns a new process using the given command, with command-line arguments in args. If omitted, args defaults to an empty array.

If the shell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

A third argument may be used to specify additional options.

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. If given, but the path does not exist, the child process emits an ENOENT error and exits immediately. ENOENT is also emitted when the command does not exist.

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:

const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

Example: A very elaborate way to run ps ax | grep ssh

const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

Example of checking for failed spawn:

const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});

Certain platforms (macOS, Linux) will use the value of argv[0] for the process title while others (Windows, SunOS) will use command.

Parameters

Parameter	Type	Description
command	string	The command to run.
args	readonly string[]	List of string arguments.
options	SpawnOptionsWithStdioTuple<StdioPipe, StdioNull, StdioPipe>	-

Returns

ChildProcessByStdio<DefaultWritableStream, null, DefaultReadableStream>

Call Signature

spawn(command: string, args: readonly string[], options: SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioPipe>): ChildProcessByStdio<null, DefaultReadableStream, DefaultReadableStream>

The child_process.spawn() method spawns a new process using the given command, with command-line arguments in args. If omitted, args defaults to an empty array.

If the shell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

A third argument may be used to specify additional options.

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. If given, but the path does not exist, the child process emits an ENOENT error and exits immediately. ENOENT is also emitted when the command does not exist.

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:

const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

Example: A very elaborate way to run ps ax | grep ssh

const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

Example of checking for failed spawn:

const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});

Certain platforms (macOS, Linux) will use the value of argv[0] for the process title while others (Windows, SunOS) will use command.

Parameters

Parameter	Type	Description
command	string	The command to run.
args	readonly string[]	List of string arguments.
options	SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioPipe>	-

Returns

ChildProcessByStdio<null, DefaultReadableStream, DefaultReadableStream>

Call Signature

spawn(command: string, args: readonly string[], options: SpawnOptionsWithStdioTuple<StdioPipe, StdioNull, StdioNull>): ChildProcessByStdio<DefaultWritableStream, null, null>

The child_process.spawn() method spawns a new process using the given command, with command-line arguments in args. If omitted, args defaults to an empty array.

If the shell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

A third argument may be used to specify additional options.

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. If given, but the path does not exist, the child process emits an ENOENT error and exits immediately. ENOENT is also emitted when the command does not exist.

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:

const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

Example: A very elaborate way to run ps ax | grep ssh

const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

Example of checking for failed spawn:

const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});

Certain platforms (macOS, Linux) will use the value of argv[0] for the process title while others (Windows, SunOS) will use command.

Parameters

Parameter	Type	Description
command	string	The command to run.
args	readonly string[]	List of string arguments.
options	SpawnOptionsWithStdioTuple<StdioPipe, StdioNull, StdioNull>	-

Returns

ChildProcessByStdio<DefaultWritableStream, null, null>

Call Signature

spawn(command: string, args: readonly string[], options: SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioNull>): ChildProcessByStdio<null, DefaultReadableStream, null>

The child_process.spawn() method spawns a new process using the given command, with command-line arguments in args. If omitted, args defaults to an empty array.

If the shell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

A third argument may be used to specify additional options.

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. If given, but the path does not exist, the child process emits an ENOENT error and exits immediately. ENOENT is also emitted when the command does not exist.

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:

const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

Example: A very elaborate way to run ps ax | grep ssh

const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

Example of checking for failed spawn:

const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});

Certain platforms (macOS, Linux) will use the value of argv[0] for the process title while others (Windows, SunOS) will use command.

Parameters

Parameter	Type	Description
command	string	The command to run.
args	readonly string[]	List of string arguments.
options	SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioNull>	-

Returns

ChildProcessByStdio<null, DefaultReadableStream, null>

Call Signature

spawn(command: string, args: readonly string[], options: SpawnOptionsWithStdioTuple<StdioNull, StdioNull, StdioPipe>): ChildProcessByStdio<null, null, DefaultReadableStream>

The child_process.spawn() method spawns a new process using the given command, with command-line arguments in args. If omitted, args defaults to an empty array.

If the shell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

A third argument may be used to specify additional options.

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. If given, but the path does not exist, the child process emits an ENOENT error and exits immediately. ENOENT is also emitted when the command does not exist.

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:

const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

Example: A very elaborate way to run ps ax | grep ssh

const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

Example of checking for failed spawn:

const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});

Certain platforms (macOS, Linux) will use the value of argv[0] for the process title while others (Windows, SunOS) will use command.

Parameters

Parameter	Type	Description
command	string	The command to run.
args	readonly string[]	List of string arguments.
options	SpawnOptionsWithStdioTuple<StdioNull, StdioNull, StdioPipe>	-

Returns

ChildProcessByStdio<null, null, DefaultReadableStream>

Call Signature

spawn(command: string, args: readonly string[], options: SpawnOptionsWithStdioTuple<StdioNull, StdioNull, StdioNull>): ChildProcessByStdio<null, null, null>

The child_process.spawn() method spawns a new process using the given command, with command-line arguments in args. If omitted, args defaults to an empty array.

If the shell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

A third argument may be used to specify additional options.

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. If given, but the path does not exist, the child process emits an ENOENT error and exits immediately. ENOENT is also emitted when the command does not exist.

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:

const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

Example: A very elaborate way to run ps ax | grep ssh

const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

Example of checking for failed spawn:

const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});

Certain platforms (macOS, Linux) will use the value of argv[0] for the process title while others (Windows, SunOS) will use command.

Parameters

Parameter	Type	Description
command	string	The command to run.
args	readonly string[]	List of string arguments.
options	SpawnOptionsWithStdioTuple<StdioNull, StdioNull, StdioNull>	-

Returns

ChildProcessByStdio<null, null, null>

Call Signature

spawn(command: string, args: readonly string[], options: SpawnOptions): ChildProcess

The child_process.spawn() method spawns a new process using the given command, with command-line arguments in args. If omitted, args defaults to an empty array.

If the shell option is enabled, do not pass unsanitized user input to thisfunction. Any input containing shell metacharacters may be used to triggerarbitrary command execution.

A third argument may be used to specify additional options.

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. If given, but the path does not exist, the child process emits an ENOENT error and exits immediately. ENOENT is also emitted when the command does not exist.

Example of running ls -lh /usr, capturing stdout, stderr, and the exit code:

const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

Example: A very elaborate way to run ps ax | grep ssh

const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

Example of checking for failed spawn:

const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});

Certain platforms (macOS, Linux) will use the value of argv[0] for the process title while others (Windows, SunOS) will use command.

Parameters

Parameter	Type	Description
command	string	The command to run.
args	readonly string[]	List of string arguments.
options	SpawnOptions	-

Returns

ChildProcess