2021-09-29 18:17:34 +02:00
2022-04-10 02:18:16 +02:00
/* NOTE: Do not edit directly! This file is generated using `npm run update-types` in https://github.com/Steve-Mcl/monaco-editor-esm-i18n */
2021-09-29 18:17:34 +02:00
2023-03-03 11:55:06 +01:00
/ * *
* The ` child_process ` module provides the ability to spawn subprocesses in
* a manner that is similar , but not identical , to [ ` popen(3) ` ] ( http : //man7.org/linux/man-pages/man3/popen.3.html). This capability
* is primarily provided by the { @link spawn } function :
*
* ` ` ` js
* 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 } ` ) ;
* } ) ;
* ` ` `
*
* By default , pipes for ` stdin ` , ` stdout ` , and ` stderr ` are established between
* the parent Node . js process and the spawned subprocess . These pipes have
* limited ( and platform - specific ) capacity . If the subprocess writes to
* stdout in excess of that limit without the output being captured , the
* subprocess blocks waiting for the pipe buffer to accept more data . This is
* identical to the behavior of pipes in the shell . Use the ` { stdio: 'ignore' } ` option if the output will not be consumed .
*
* The command lookup is performed using the ` options.env.PATH ` environment
* variable if it is in the ` options ` object . Otherwise , ` process.env.PATH ` is
* used .
*
* On Windows , environment variables are case - insensitive . Node . js
* lexicographically sorts the ` env ` keys and uses the first one that
* case - insensitively matches . Only first ( in lexicographic order ) entry will be
* passed to the subprocess . This might lead to issues on Windows when passing
* objects to the ` env ` option that have multiple variants of the same key , such as ` PATH ` and ` Path ` .
*
* The { @link spawn } method spawns the child process asynchronously ,
* without blocking the Node . js event loop . The { @link spawnSync } function provides equivalent functionality in a synchronous manner that blocks
* the event loop until the spawned process either exits or is terminated .
*
* For convenience , the ` child_process ` module provides a handful of synchronous
* and asynchronous alternatives to { @link spawn } and { @link spawnSync } . Each of these alternatives are implemented on
* top of { @link spawn } or { @link spawnSync } .
*
* * { @link exec } : spawns a shell and runs a command within that
* shell , passing the ` stdout ` and ` stderr ` to a callback function when
* complete .
* * { @link execFile } : similar to { @link exec } except
* that it spawns the command directly without first spawning a shell by
* default .
* * { @link fork } : spawns a new Node . js process and invokes a
* specified module with an IPC communication channel established that allows
* sending messages between parent and child .
* * { @link execSync } : a synchronous version of { @link exec } that will block the Node . js event loop .
* * { @link execFileSync } : a synchronous version of { @link execFile } that will block the Node . js event loop .
*
* For certain use cases , such as automating shell scripts , the ` synchronous counterparts ` may be more convenient . In many cases , however ,
* the synchronous methods can have significant impact on performance due to
* stalling the event loop while spawned processes complete .
* @see [ source ] ( https : //github.com/nodejs/node/blob/v16.9.0/lib/child_process.js)
* /
2021-09-29 18:17:34 +02:00
declare module 'child_process' {
2023-03-03 11:55:06 +01:00
import { ObjectEncodingOptions } from 'node:fs' ;
import { EventEmitter , Abortable } from 'node:events' ;
import * as net from 'node:net' ;
import { Writable , Readable , Stream , Pipe } from 'node:stream' ;
import { URL } from 'node:url' ;
type Serializable = string | object | number | boolean | bigint ;
2021-09-29 18:17:34 +02:00
type SendHandle = net . Socket | net . Server ;
2023-03-03 11:55:06 +01:00
/ * *
* Instances of the ` ChildProcess ` represent spawned child processes .
*
* Instances of ` ChildProcess ` are not intended to be created directly . Rather ,
* use the { @link spawn } , { @link exec } , { @link execFile } , or { @link fork } methods to create
* instances of ` ChildProcess ` .
* @since v2 . 2.0
* /
class ChildProcess extends EventEmitter {
/ * *
* 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 ` undefined ` if the child process could
* not be successfully spawned .
* @since v0 . 1.90
* /
2021-09-29 18:17:34 +02:00
stdin : Writable | null ;
2023-03-03 11:55:06 +01:00
/ * *
* 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 .
*
* ` ` ` js
* 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 ` if the child process could
* not be successfully spawned .
* @since v0 . 1.90
* /
2021-09-29 18:17:34 +02:00
stdout : Readable | null ;
2023-03-03 11:55:06 +01:00
/ * *
* 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 ` if the child process could
* not be successfully spawned .
* @since v0 . 1.90
* /
2021-09-29 18:17:34 +02:00
stderr : Readable | null ;
2023-03-03 11:55:06 +01:00
/ * *
* The ` subprocess.channel ` property is a reference to the child ' s IPC channel . If
* no IPC channel currently exists , this property is ` undefined ` .
* @since v7 . 1.0
* /
2021-09-29 18:17:34 +02:00
readonly channel? : Pipe | null | undefined ;
2023-03-03 11:55:06 +01:00
/ * *
* A sparse array of pipes to the child process , corresponding with positions in
* the ` stdio ` option passed to { @link spawn } that have been set
* to the value ` 'pipe' ` . ` subprocess.stdio[0] ` , ` subprocess.stdio[1] ` , and ` subprocess.stdio[2] ` are also available as ` subprocess.stdin ` , ` subprocess.stdout ` , and ` subprocess.stderr ` ,
* respectively .
*
* In the following example , only the child ' s fd ` 1 ` ( stdout ) is configured as a
* pipe , so only the parent ' s ` subprocess.stdio[1] ` is a stream , all other values
* in the array are ` null ` .
*
* ` ` ` js
* const assert = require ( 'assert' ) ;
* const fs = require ( 'fs' ) ;
* const child_process = require ( 'child_process' ) ;
*
* const subprocess = child_process . spawn ( 'ls' , {
* stdio : [
* 0 , // Use parent's stdin for child.
* 'pipe' , // Pipe child's stdout to parent.
* fs . openSync ( 'err.out' , 'w' ) , // Direct child's stderr to a file.
* ]
* } ) ;
*
* assert . strictEqual ( subprocess . stdio [ 0 ] , null ) ;
* assert . strictEqual ( subprocess . stdio [ 0 ] , subprocess . stdin ) ;
*
* assert ( subprocess . stdout ) ;
* assert . strictEqual ( subprocess . stdio [ 1 ] , subprocess . stdout ) ;
*
* assert . strictEqual ( subprocess . stdio [ 2 ] , null ) ;
* assert . strictEqual ( subprocess . stdio [ 2 ] , subprocess . stderr ) ;
* ` ` `
*
* The ` subprocess.stdio ` property can be ` undefined ` if the child process could
* not be successfully spawned .
* @since v0 . 7.10
* /
2021-09-29 18:17:34 +02:00
readonly stdio : [
2023-03-03 11:55:06 +01:00
Writable | null ,
// stdin
Readable | null ,
// stdout
Readable | null ,
// stderr
Readable | Writable | null | undefined ,
// extra
2021-09-29 18:17:34 +02:00
Readable | Writable | null | undefined // extra
] ;
2023-03-03 11:55:06 +01:00
/ * *
* The ` subprocess.killed ` property indicates whether the child process
* successfully received a signal from ` subprocess.kill() ` . The ` killed ` property
* does not indicate that the child process has been terminated .
* @since v0 . 5.10
* /
2021-09-29 18:17:34 +02:00
readonly killed : boolean ;
2023-03-03 11:55:06 +01:00
/ * *
* 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 .
*
* ` ` ` js
* const { spawn } = require ( 'child_process' ) ;
* const grep = spawn ( 'grep' , [ 'ssh' ] ) ;
*
* console . log ( ` Spawned child pid: ${ grep . pid } ` ) ;
* grep . stdin . end ( ) ;
* ` ` `
* @since v0 . 1.90
* /
readonly pid? : number | undefined ;
/ * *
* The ` subprocess.connected ` property indicates whether it is still possible to
* send and receive messages from a child process . When ` subprocess.connected ` is ` false ` , it is no longer possible to send or receive messages .
* @since v0 . 7.2
* /
2021-09-29 18:17:34 +02:00
readonly connected : boolean ;
2023-03-03 11:55:06 +01:00
/ * *
* The ` subprocess.exitCode ` property indicates the exit code of the child process .
* If the child process is still running , the field will be ` null ` .
* /
2021-09-29 18:17:34 +02:00
readonly exitCode : number | null ;
2023-03-03 11:55:06 +01:00
/ * *
* The ` subprocess.signalCode ` property indicates the signal received by
* the child process if any , else ` null ` .
* /
2021-09-29 18:17:34 +02:00
readonly signalCode : NodeJS.Signals | null ;
2023-03-03 11:55:06 +01:00
/ * *
* The ` subprocess.spawnargs ` property represents the full list of command - line
* arguments the child process was launched with .
* /
2021-09-29 18:17:34 +02:00
readonly spawnargs : string [ ] ;
2023-03-03 11:55:06 +01:00
/ * *
* The ` subprocess.spawnfile ` property indicates the executable file name of
* the child process that is launched .
*
* For { @link fork } , its value will be equal to ` process.execPath ` .
* For { @link spawn } , its value will be the name of
* the executable file .
* For { @link exec } , its value will be the name of the shell
* in which the child process is launched .
* /
2021-09-29 18:17:34 +02:00
readonly spawnfile : string ;
2023-03-03 11:55:06 +01:00
/ * *
* 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) ` ] ( http : //man7.org/linux/man-pages/man7/signal.7.html) for a list of available signals. This function
* returns ` true ` if [ ` kill(2) ` ] ( http : //man7.org/linux/man-pages/man2/kill.2.html) succeeds, and `false` otherwise.
*
* ` ` ` js
* 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) ` ] ( http : //man7.org/linux/man-pages/man2/kill.2.html) 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 ` :
*
* ` ` ` js
* '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 ) ;
* ` ` `
* @since v0 . 1.90
* /
2021-09-29 18:17:34 +02:00
kill ( signal? : NodeJS.Signals | number ) : boolean ;
2023-03-03 11:55:06 +01:00
/ * *
* When an IPC channel has been established between the parent and child (
* i . e . when using { @link fork } ) , the ` subprocess.send() ` method can
* be used to send messages to the child process . When the child process is a
* Node . js instance , these messages can be received via the ` 'message' ` event .
*
* The message goes through serialization and parsing . The resulting
* message might not be the same as what is originally sent .
*
* For example , in the parent script :
*
* ` ` ` js
* const cp = require ( 'child_process' ) ;
* const n = cp . fork ( ` ${ __dirname } /sub.js ` ) ;
*
* n . on ( 'message' , ( m ) = > {
* console . log ( 'PARENT got message:' , m ) ;
* } ) ;
*
* // Causes the child to print: CHILD got message: { hello: 'world' }
* n . send ( { hello : 'world' } ) ;
* ` ` `
*
* And then the child script , ` 'sub.js' ` might look like this :
*
* ` ` ` js
* process . on ( 'message' , ( m ) = > {
* console . log ( 'CHILD got message:' , m ) ;
* } ) ;
*
* // Causes the parent to print: PARENT got message: { foo: 'bar', baz: null }
* process . send ( { foo : 'bar' , baz : NaN } ) ;
* ` ` `
*
* Child Node . js processes will have a ` process.send() ` method of their own
* that allows the child to send messages back to the parent .
*
* There is a special case when sending a ` {cmd: 'NODE_foo'} ` message . Messages
* containing a ` NODE_ ` prefix in the ` cmd ` property are reserved for use within
* Node . js core and will not be emitted in the child 's `' message '` event. Rather, such messages are emitted using the`' internalMessage ' ` event and are consumed internally by Node.js.
* Applications should avoid using such messages or listening for ` 'internalMessage' ` events as it is subject to change without notice .
*
* The optional ` sendHandle ` argument that may be passed to ` subprocess.send() ` is
* for passing a TCP server or socket object to the child process . The child will
* receive the object as the second argument passed to the callback function
* registered on the ` 'message' ` event . Any data that is received
* and buffered in the socket will not be sent to the child .
*
* The optional ` callback ` is a function that is invoked after the message is
* sent but before the child may have received it . The function is called with a
* single argument : ` null ` on success , or an ` Error ` object on failure .
*
* If no ` callback ` function is provided and the message cannot be sent , an ` 'error' ` event will be emitted by the ` ChildProcess ` object . This can
* happen , for instance , when the child process has already exited .
*
* ` subprocess.send() ` will return ` false ` if the channel has closed or when the
* backlog of unsent messages exceeds a threshold that makes it unwise to send
* more . Otherwise , the method returns ` true ` . The ` callback ` function can be
* used to implement flow control .
*
* # # # # Example : sending a server object
*
* The ` sendHandle ` argument can be used , for instance , to pass the handle of
* a TCP server object to the child process as illustrated in the example below :
*
* ` ` ` js
* const subprocess = require ( 'child_process' ) . fork ( 'subprocess.js' ) ;
*
* // Open up the server object and send the handle.
* const server = require ( 'net' ) . createServer ( ) ;
* server . on ( 'connection' , ( socket ) = > {
* socket . end ( 'handled by parent' ) ;
* } ) ;
* server . listen ( 1337 , ( ) = > {
* subprocess . send ( 'server' , server ) ;
* } ) ;
* ` ` `
*
* The child would then receive the server object as :
*
* ` ` ` js
* process . on ( 'message' , ( m , server ) = > {
* if ( m === 'server' ) {
* server . on ( 'connection' , ( socket ) = > {
* socket . end ( 'handled by child' ) ;
* } ) ;
* }
* } ) ;
* ` ` `
*
* Once the server is now shared between the parent and child , some connections
* can be handled by the parent and some by the child .
*
* While the example above uses a server created using the ` net ` module , ` dgram ` module servers use exactly the same workflow with the exceptions of listening on
* a ` 'message' ` event instead of ` 'connection' ` and using ` server.bind() ` instead
* of ` server.listen() ` . This is , however , currently only supported on Unix
* platforms .
*
* # # # # Example : sending a socket object
*
* Similarly , the ` sendHandler ` argument can be used to pass the handle of a
* socket to the child process . The example below spawns two children that each
* handle connections with "normal" or "special" priority :
*
* ` ` ` js
* const { fork } = require ( 'child_process' ) ;
* const normal = fork ( 'subprocess.js' , [ 'normal' ] ) ;
* const special = fork ( 'subprocess.js' , [ 'special' ] ) ;
*
* // Open up the server and send sockets to child. Use pauseOnConnect to prevent
* // the sockets from being read before they are sent to the child process.
* const server = require ( 'net' ) . createServer ( { pauseOnConnect : true } ) ;
* server . on ( 'connection' , ( socket ) = > {
*
* // If this is special priority...
* if ( socket . remoteAddress === '74.125.127.100' ) {
* special . send ( 'socket' , socket ) ;
* return ;
* }
* // This is normal priority.
* normal . send ( 'socket' , socket ) ;
* } ) ;
* server . listen ( 1337 ) ;
* ` ` `
*
* The ` subprocess.js ` would receive the socket handle as the second argument
* passed to the event callback function :
*
* ` ` ` js
* process . on ( 'message' , ( m , socket ) = > {
* if ( m === 'socket' ) {
* if ( socket ) {
* // Check that the client socket exists.
* // It is possible for the socket to be closed between the time it is
* // sent and the time it is received in the child process.
* socket . end ( ` Request handled with ${ process . argv [ 2 ] } priority ` ) ;
* }
* }
* } ) ;
* ` ` `
*
* Do not use ` .maxConnections ` on a socket that has been passed to a subprocess .
* The parent cannot track when the socket is destroyed .
*
* Any ` 'message' ` handlers in the subprocess should verify that ` socket ` exists ,
* as the connection may have been closed during the time it takes to send the
* connection to the child .
* @since v0 . 5.9
* @param options The ` options ` argument , if present , is an object used to parameterize the sending of certain types of handles . ` options ` supports the following properties :
* /
2021-09-29 18:17:34 +02:00
send ( message : Serializable , callback ? : ( error : Error | null ) = > void ) : boolean ;
send ( message : Serializable , sendHandle? : SendHandle , callback ? : ( error : Error | null ) = > void ) : boolean ;
send ( message : Serializable , sendHandle? : SendHandle , options? : MessageOptions , callback ? : ( error : Error | null ) = > void ) : boolean ;
2023-03-03 11:55:06 +01:00
/ * *
* Closes the IPC channel between parent and child , allowing the child to exit
* gracefully once there are no other connections keeping it alive . After calling
* this method the ` subprocess.connected ` and ` process.connected ` properties in
* both the parent and child ( respectively ) will be set to ` false ` , and it will be
* no longer possible to pass messages between the processes .
*
* The ` 'disconnect' ` event will be emitted when there are no messages in the
* process of being received . This will most often be triggered immediately after
* calling ` subprocess.disconnect() ` .
*
* When the child process is a Node . js instance ( e . g . spawned using { @link fork } ) , the ` process.disconnect() ` method can be invoked
* within the child process to close the IPC channel as well .
* @since v0 . 7.2
* /
2021-09-29 18:17:34 +02:00
disconnect ( ) : void ;
2023-03-03 11:55:06 +01:00
/ * *
* By default , the parent will wait for the detached child to exit . To prevent the
* parent from waiting for a given ` subprocess ` to exit , use the ` subprocess.unref() ` method . Doing so will cause the parent ' s event loop to not
* include the child in its reference count , allowing the parent to exit
* independently of the child , unless there is an established IPC channel between
* the child and the parent .
*
* ` ` ` js
* const { spawn } = require ( 'child_process' ) ;
*
* const subprocess = spawn ( process . argv [ 0 ] , [ 'child_program.js' ] , {
* detached : true ,
* stdio : 'ignore'
* } ) ;
*
* subprocess . unref ( ) ;
* ` ` `
* @since v0 . 7.10
* /
2021-09-29 18:17:34 +02:00
unref ( ) : void ;
2023-03-03 11:55:06 +01:00
/ * *
* Calling ` subprocess.ref() ` after making a call to ` subprocess.unref() ` will
* restore the removed reference count for the child process , forcing the parent
* to wait for the child to exit before exiting itself .
*
* ` ` ` js
* const { spawn } = require ( 'child_process' ) ;
*
* const subprocess = spawn ( process . argv [ 0 ] , [ 'child_program.js' ] , {
* detached : true ,
* stdio : 'ignore'
* } ) ;
*
* subprocess . unref ( ) ;
* subprocess . ref ( ) ;
* ` ` `
* @since v0 . 7.10
* /
2021-09-29 18:17:34 +02:00
ref ( ) : void ;
/ * *
* events . EventEmitter
* 1 . close
* 2 . disconnect
* 3 . error
* 4 . exit
* 5 . message
2023-03-03 11:55:06 +01:00
* 6 . spawn
2021-09-29 18:17:34 +02:00
* /
addListener ( event : string , listener : ( . . . args : any [ ] ) = > void ) : this ;
2023-03-03 11:55:06 +01:00
addListener ( event : 'close' , listener : ( code : number | null , signal : NodeJS.Signals | null ) = > void ) : this ;
addListener ( event : 'disconnect' , listener : ( ) = > void ) : this ;
addListener ( event : 'error' , listener : ( err : Error ) = > void ) : this ;
addListener ( event : 'exit' , listener : ( code : number | null , signal : NodeJS.Signals | null ) = > void ) : this ;
addListener ( event : 'message' , listener : ( message : Serializable , sendHandle : SendHandle ) = > void ) : this ;
addListener ( event : 'spawn' , listener : ( ) = > void ) : this ;
2021-09-29 18:17:34 +02:00
emit ( event : string | symbol , . . . args : any [ ] ) : boolean ;
2023-03-03 11:55:06 +01:00
emit ( event : 'close' , code : number | null , signal : NodeJS.Signals | null ) : boolean ;
emit ( event : 'disconnect' ) : boolean ;
emit ( event : 'error' , err : Error ) : boolean ;
emit ( event : 'exit' , code : number | null , signal : NodeJS.Signals | null ) : boolean ;
emit ( event : 'message' , message : Serializable , sendHandle : SendHandle ) : boolean ;
emit ( event : 'spawn' , listener : ( ) = > void ) : boolean ;
2021-09-29 18:17:34 +02:00
on ( event : string , listener : ( . . . args : any [ ] ) = > void ) : this ;
2023-03-03 11:55:06 +01:00
on ( event : 'close' , listener : ( code : number | null , signal : NodeJS.Signals | null ) = > void ) : this ;
on ( event : 'disconnect' , listener : ( ) = > void ) : this ;
on ( event : 'error' , listener : ( err : Error ) = > void ) : this ;
on ( event : 'exit' , listener : ( code : number | null , signal : NodeJS.Signals | null ) = > void ) : this ;
on ( event : 'message' , listener : ( message : Serializable , sendHandle : SendHandle ) = > void ) : this ;
on ( event : 'spawn' , listener : ( ) = > void ) : this ;
2021-09-29 18:17:34 +02:00
once ( event : string , listener : ( . . . args : any [ ] ) = > void ) : this ;
2023-03-03 11:55:06 +01:00
once ( event : 'close' , listener : ( code : number | null , signal : NodeJS.Signals | null ) = > void ) : this ;
once ( event : 'disconnect' , listener : ( ) = > void ) : this ;
once ( event : 'error' , listener : ( err : Error ) = > void ) : this ;
once ( event : 'exit' , listener : ( code : number | null , signal : NodeJS.Signals | null ) = > void ) : this ;
once ( event : 'message' , listener : ( message : Serializable , sendHandle : SendHandle ) = > void ) : this ;
once ( event : 'spawn' , listener : ( ) = > void ) : this ;
2021-09-29 18:17:34 +02:00
prependListener ( event : string , listener : ( . . . args : any [ ] ) = > void ) : this ;
2023-03-03 11:55:06 +01:00
prependListener ( event : 'close' , listener : ( code : number | null , signal : NodeJS.Signals | null ) = > void ) : this ;
prependListener ( event : 'disconnect' , listener : ( ) = > void ) : this ;
prependListener ( event : 'error' , listener : ( err : Error ) = > void ) : this ;
prependListener ( event : 'exit' , listener : ( code : number | null , signal : NodeJS.Signals | null ) = > void ) : this ;
prependListener ( event : 'message' , listener : ( message : Serializable , sendHandle : SendHandle ) = > void ) : this ;
prependListener ( event : 'spawn' , listener : ( ) = > void ) : this ;
2021-09-29 18:17:34 +02:00
prependOnceListener ( event : string , listener : ( . . . args : any [ ] ) = > void ) : this ;
2023-03-03 11:55:06 +01:00
prependOnceListener ( event : 'close' , listener : ( code : number | null , signal : NodeJS.Signals | null ) = > void ) : this ;
prependOnceListener ( event : 'disconnect' , listener : ( ) = > void ) : this ;
prependOnceListener ( event : 'error' , listener : ( err : Error ) = > void ) : this ;
prependOnceListener ( event : 'exit' , listener : ( code : number | null , signal : NodeJS.Signals | null ) = > void ) : this ;
prependOnceListener ( event : 'message' , listener : ( message : Serializable , sendHandle : SendHandle ) = > void ) : this ;
prependOnceListener ( event : 'spawn' , listener : ( ) = > void ) : this ;
2021-09-29 18:17:34 +02:00
}
// return this object when stdio option is undefined or not specified
interface ChildProcessWithoutNullStreams extends ChildProcess {
stdin : Writable ;
stdout : Readable ;
stderr : Readable ;
readonly stdio : [
2023-03-03 11:55:06 +01:00
Writable ,
Readable ,
Readable ,
// stderr
Readable | Writable | null | undefined ,
// extra, no modification
2021-09-29 18:17:34 +02:00
Readable | Writable | null | undefined // extra, no modification
] ;
}
// return this object when stdio option is a tuple of 3
2023-03-03 11:55:06 +01:00
interface ChildProcessByStdio < I extends null | Writable , O extends null | Readable , E extends null | Readable > extends ChildProcess {
2021-09-29 18:17:34 +02:00
stdin : I ;
stdout : O ;
stderr : E ;
readonly stdio : [
I ,
O ,
E ,
2023-03-03 11:55:06 +01:00
Readable | Writable | null | undefined ,
// extra, no modification
2021-09-29 18:17:34 +02:00
Readable | Writable | null | undefined // extra, no modification
] ;
}
interface MessageOptions {
keepOpen? : boolean | undefined ;
}
2023-03-03 11:55:06 +01:00
type IOType = 'overlapped' | 'pipe' | 'ignore' | 'inherit' ;
type StdioOptions = IOType | Array < IOType | ' ipc ' | Stream | number | null | undefined > ;
2021-09-29 18:17:34 +02:00
type SerializationType = 'json' | 'advanced' ;
2023-03-03 11:55:06 +01:00
interface MessagingOptions extends Abortable {
2021-09-29 18:17:34 +02:00
/ * *
* Specify the kind of serialization used for sending messages between processes .
* @default 'json'
* /
serialization? : SerializationType | undefined ;
2023-03-03 11:55:06 +01:00
/ * *
* The signal value to be used when the spawned process will be killed by the abort signal .
* @default 'SIGTERM'
* /
killSignal? : NodeJS.Signals | number | undefined ;
/ * *
* In milliseconds the maximum amount of time the process is allowed to run .
* /
timeout? : number | undefined ;
2021-09-29 18:17:34 +02:00
}
interface ProcessEnvOptions {
uid? : number | undefined ;
gid? : number | undefined ;
2023-03-03 11:55:06 +01:00
cwd? : string | URL | undefined ;
2021-09-29 18:17:34 +02:00
env? : NodeJS.ProcessEnv | undefined ;
}
interface CommonOptions extends ProcessEnvOptions {
/ * *
2023-03-03 11:55:06 +01:00
* @default false
2021-09-29 18:17:34 +02:00
* /
windowsHide? : boolean | undefined ;
/ * *
* @default 0
* /
timeout? : number | undefined ;
}
2023-03-03 11:55:06 +01:00
interface CommonSpawnOptions extends CommonOptions , MessagingOptions , Abortable {
2021-09-29 18:17:34 +02:00
argv0? : string | undefined ;
stdio? : StdioOptions | undefined ;
shell? : boolean | string | undefined ;
windowsVerbatimArguments? : boolean | undefined ;
}
interface SpawnOptions extends CommonSpawnOptions {
detached? : boolean | undefined ;
}
interface SpawnOptionsWithoutStdio extends SpawnOptions {
2023-03-03 11:55:06 +01:00
stdio? : StdioPipeNamed | StdioPipe [ ] | undefined ;
2021-09-29 18:17:34 +02:00
}
type StdioNull = 'inherit' | 'ignore' | Stream ;
2023-03-03 11:55:06 +01:00
type StdioPipeNamed = 'pipe' | 'overlapped' ;
type StdioPipe = undefined | null | StdioPipeNamed ;
interface SpawnOptionsWithStdioTuple < Stdin extends StdioNull | StdioPipe , Stdout extends StdioNull | StdioPipe , Stderr extends StdioNull | StdioPipe > extends SpawnOptions {
2021-09-29 18:17:34 +02:00
stdio : [ Stdin , Stdout , Stderr ] ;
}
2023-03-03 11:55:06 +01:00
/ * *
* 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 this * *
* * * function . Any input containing shell metacharacters may be used to trigger * *
* * * arbitrary command execution . * *
*
* A third argument may be used to specify additional options , with these defaults :
*
* ` ` ` js
* const defaults = {
* cwd : undefined ,
* env : process.env
* } ;
* ` ` `
*
* 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 .
*
* Use ` env ` to specify environment variables that will be visible to the new
* process , the default is ` process.env ` .
*
* ` undefined ` values in ` env ` will be ignored .
*
* Example of running ` ls -lh /usr ` , capturing ` stdout ` , ` stderr ` , and the
* exit code :
*
* ` ` ` js
* 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 `
*
* ` ` ` js
* 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 ` :
*
* ` ` ` js
* 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 ` .
*
* Node . js currently overwrites ` argv[0] ` with ` process.execPath ` on startup , so ` process.argv[0] ` in a Node . js child process will not match the ` argv0 ` parameter passed to ` spawn ` from the parent ,
* retrieve it with the ` process.argv0 ` property instead .
*
* If the ` signal ` option is enabled , calling ` .abort() ` on the corresponding ` AbortController ` is similar to calling ` .kill() ` on the child process except
* the error passed to the callback will be an ` AbortError ` :
*
* ` ` ` js
* const { spawn } = require ( 'child_process' ) ;
* const controller = new AbortController ( ) ;
* const { signal } = controller ;
* const grep = spawn ( 'grep' , [ 'ssh' ] , { signal } ) ;
* grep . on ( 'error' , ( err ) = > {
* // This will be called with err being an AbortError if the controller aborts
* } ) ;
* controller . abort ( ) ; // Stops the child process
* ` ` `
* @since v0 . 1.90
* @param command The command to run .
* @param args List of string arguments .
* /
2021-09-29 18:17:34 +02:00
function spawn ( command : string , options? : SpawnOptionsWithoutStdio ) : ChildProcessWithoutNullStreams ;
2023-03-03 11:55:06 +01:00
function spawn ( command : string , options : SpawnOptionsWithStdioTuple < StdioPipe , StdioPipe , StdioPipe > ) : ChildProcessByStdio < Writable , Readable , Readable > ;
function spawn ( command : string , options : SpawnOptionsWithStdioTuple < StdioPipe , StdioPipe , StdioNull > ) : ChildProcessByStdio < Writable , Readable , null > ;
function spawn ( command : string , options : SpawnOptionsWithStdioTuple < StdioPipe , StdioNull , StdioPipe > ) : ChildProcessByStdio < Writable , null , Readable > ;
function spawn ( command : string , options : SpawnOptionsWithStdioTuple < StdioNull , StdioPipe , StdioPipe > ) : ChildProcessByStdio < null , Readable , Readable > ;
function spawn ( command : string , options : SpawnOptionsWithStdioTuple < StdioPipe , StdioNull , StdioNull > ) : ChildProcessByStdio < Writable , null , null > ;
function spawn ( command : string , options : SpawnOptionsWithStdioTuple < StdioNull , StdioPipe , StdioNull > ) : ChildProcessByStdio < null , Readable , null > ;
function spawn ( command : string , options : SpawnOptionsWithStdioTuple < StdioNull , StdioNull , StdioPipe > ) : ChildProcessByStdio < null , null , Readable > ;
function spawn ( command : string , options : SpawnOptionsWithStdioTuple < StdioNull , StdioNull , StdioNull > ) : ChildProcessByStdio < null , null , null > ;
2021-09-29 18:17:34 +02:00
function spawn ( command : string , options : SpawnOptions ) : ChildProcess ;
// overloads of spawn with 'args'
function spawn ( command : string , args? : ReadonlyArray < string > , options? : SpawnOptionsWithoutStdio ) : ChildProcessWithoutNullStreams ;
2023-03-03 11:55:06 +01:00
function spawn ( command : string , args : ReadonlyArray < string > , options : SpawnOptionsWithStdioTuple < StdioPipe , StdioPipe , StdioPipe > ) : ChildProcessByStdio < Writable , Readable , Readable > ;
function spawn ( command : string , args : ReadonlyArray < string > , options : SpawnOptionsWithStdioTuple < StdioPipe , StdioPipe , StdioNull > ) : ChildProcessByStdio < Writable , Readable , null > ;
function spawn ( command : string , args : ReadonlyArray < string > , options : SpawnOptionsWithStdioTuple < StdioPipe , StdioNull , StdioPipe > ) : ChildProcessByStdio < Writable , null , Readable > ;
function spawn ( command : string , args : ReadonlyArray < string > , options : SpawnOptionsWithStdioTuple < StdioNull , StdioPipe , StdioPipe > ) : ChildProcessByStdio < null , Readable , Readable > ;
function spawn ( command : string , args : ReadonlyArray < string > , options : SpawnOptionsWithStdioTuple < StdioPipe , StdioNull , StdioNull > ) : ChildProcessByStdio < Writable , null , null > ;
function spawn ( command : string , args : ReadonlyArray < string > , options : SpawnOptionsWithStdioTuple < StdioNull , StdioPipe , StdioNull > ) : ChildProcessByStdio < null , Readable , null > ;
function spawn ( command : string , args : ReadonlyArray < string > , options : SpawnOptionsWithStdioTuple < StdioNull , StdioNull , StdioPipe > ) : ChildProcessByStdio < null , null , Readable > ;
function spawn ( command : string , args : ReadonlyArray < string > , options : SpawnOptionsWithStdioTuple < StdioNull , StdioNull , StdioNull > ) : ChildProcessByStdio < null , null , null > ;
2021-09-29 18:17:34 +02:00
function spawn ( command : string , args : ReadonlyArray < string > , options : SpawnOptions ) : ChildProcess ;
interface ExecOptions extends CommonOptions {
shell? : string | undefined ;
2023-03-03 11:55:06 +01:00
signal? : AbortSignal | undefined ;
2021-09-29 18:17:34 +02:00
maxBuffer? : number | undefined ;
killSignal? : NodeJS.Signals | number | undefined ;
}
interface ExecOptionsWithStringEncoding extends ExecOptions {
encoding : BufferEncoding ;
}
interface ExecOptionsWithBufferEncoding extends ExecOptions {
encoding : BufferEncoding | null ; // specify `null`.
}
interface ExecException extends Error {
cmd? : string | undefined ;
killed? : boolean | undefined ;
code? : number | undefined ;
signal? : NodeJS.Signals | undefined ;
}
2023-03-03 11:55:06 +01:00
/ * *
* Spawns a shell then executes the ` command ` within that shell , buffering any
* generated output . The ` command ` string passed to the exec function is processed
* directly by the shell and special characters ( vary based on [ shell ] ( https : //en.wikipedia.org/wiki/List_of_command-line_interpreters))
* need to be dealt with accordingly :
*
* ` ` ` js
* const { exec } = require ( 'child_process' ) ;
*
* exec ( '"/path/to/test file/test.sh" arg1 arg2' ) ;
* // Double quotes are used so that the space in the path is not interpreted as
* // a delimiter of multiple arguments.
*
* exec ( 'echo "The \\$HOME variable is $HOME"' ) ;
* // The $HOME variable is escaped in the first instance, but not in the second.
* ` ` `
*
* * * Never pass unsanitized user input to this function . Any input containing shell * *
* * * metacharacters may be used to trigger arbitrary command execution . * *
*
* If a ` callback ` function is provided , it is called with the arguments ` (error, stdout, stderr) ` . On success , ` error ` will be ` null ` . On error , ` error ` will be an instance of ` Error ` . The
* ` error.code ` property will be
* the exit code of the process . By convention , any exit code other than ` 0 ` indicates an error . ` error.signal ` will be the signal that terminated the
* process .
*
* The ` stdout ` and ` stderr ` arguments passed to the callback will contain the
* stdout and stderr output of the child process . By default , Node . js will decode
* the output as UTF - 8 and pass strings to the callback . The ` encoding ` option
* can be used to specify the character encoding used to decode the stdout and
* stderr output . If ` encoding ` is ` 'buffer' ` , or an unrecognized character
* encoding , ` Buffer ` objects will be passed to the callback instead .
*
* ` ` ` js
* const { exec } = require ( 'child_process' ) ;
* exec ( 'cat *.js missing_file | wc -l' , ( error , stdout , stderr ) = > {
* if ( error ) {
* console . error ( ` exec error: ${ error } ` ) ;
* return ;
* }
* console . log ( ` stdout: ${ stdout } ` ) ;
* console . error ( ` stderr: ${ stderr } ` ) ;
* } ) ;
* ` ` `
*
* If ` timeout ` is greater than ` 0 ` , the parent will send the signal
* identified by the ` killSignal ` property ( the default is ` 'SIGTERM' ` ) if the
* child runs longer than ` timeout ` milliseconds .
*
* Unlike the [ ` exec(3) ` ] ( http : //man7.org/linux/man-pages/man3/exec.3.html) POSIX system call, `child_process.exec()` does not replace
* the existing process and uses a shell to execute the command .
*
* If this method is invoked as its ` util.promisify() ` ed version , it returns
* a ` Promise ` for an ` Object ` with ` stdout ` and ` stderr ` properties . The returned ` ChildProcess ` instance is attached to the ` Promise ` as a ` child ` property . In
* case of an error ( including any error resulting in an exit code other than 0 ) , a
* rejected promise is returned , with the same ` error ` object given in the
* callback , but with two additional properties ` stdout ` and ` stderr ` .
*
* ` ` ` js
* const util = require ( 'util' ) ;
* const exec = util . promisify ( require ( 'child_process' ) . exec ) ;
*
* async function lsExample() {
* const { stdout , stderr } = await exec ( 'ls' ) ;
* console . log ( 'stdout:' , stdout ) ;
* console . error ( 'stderr:' , stderr ) ;
* }
* lsExample ( ) ;
* ` ` `
*
* If the ` signal ` option is enabled , calling ` .abort() ` on the corresponding ` AbortController ` is similar to calling ` .kill() ` on the child process except
* the error passed to the callback will be an ` AbortError ` :
*
* ` ` ` js
* const { exec } = require ( 'child_process' ) ;
* const controller = new AbortController ( ) ;
* const { signal } = controller ;
* const child = exec ( 'grep ssh' , { signal } , ( error ) = > {
* console . log ( error ) ; // an AbortError
* } ) ;
* controller . abort ( ) ;
* ` ` `
* @since v0 . 1.90
* @param command The command to run , with space - separated arguments .
* @param callback called with the output when process terminates .
* /
2021-09-29 18:17:34 +02:00
function exec ( command : string , callback ? : ( error : ExecException | null , stdout : string , stderr : string ) = > void ) : ChildProcess ;
// `options` with `"buffer"` or `null` for `encoding` means stdout/stderr are definitely `Buffer`.
2023-03-03 11:55:06 +01:00
function exec (
command : string ,
options : {
encoding : 'buffer' | null ;
} & ExecOptions ,
callback ? : ( error : ExecException | null , stdout : Buffer , stderr : Buffer ) = > void
) : ChildProcess ;
2021-09-29 18:17:34 +02:00
// `options` with well known `encoding` means stdout/stderr are definitely `string`.
2023-03-03 11:55:06 +01:00
function exec (
command : string ,
options : {
encoding : BufferEncoding ;
} & ExecOptions ,
callback ? : ( error : ExecException | null , stdout : string , stderr : string ) = > void
) : ChildProcess ;
2021-09-29 18:17:34 +02:00
// `options` with an `encoding` whose type is `string` means stdout/stderr could either be `Buffer` or `string`.
// There is no guarantee the `encoding` is unknown as `string` is a superset of `BufferEncoding`.
function exec (
command : string ,
2023-03-03 11:55:06 +01:00
options : {
encoding : BufferEncoding ;
} & ExecOptions ,
callback ? : ( error : ExecException | null , stdout : string | Buffer , stderr : string | Buffer ) = > void
2021-09-29 18:17:34 +02:00
) : ChildProcess ;
// `options` without an `encoding` means stdout/stderr are definitely `string`.
function exec ( command : string , options : ExecOptions , callback ? : ( error : ExecException | null , stdout : string , stderr : string ) = > void ) : ChildProcess ;
// fallback if nothing else matches. Worst case is always `string | Buffer`.
function exec (
command : string ,
2023-03-03 11:55:06 +01:00
options : ( ObjectEncodingOptions & ExecOptions ) | undefined | null ,
callback ? : ( error : ExecException | null , stdout : string | Buffer , stderr : string | Buffer ) = > void
2021-09-29 18:17:34 +02:00
) : ChildProcess ;
interface PromiseWithChild < T > extends Promise < T > {
child : ChildProcess ;
}
namespace exec {
2023-03-03 11:55:06 +01:00
function __promisify__ ( command : string ) : PromiseWithChild < {
stdout : string ;
stderr : string ;
} > ;
function __promisify__ (
command : string ,
options : {
encoding : 'buffer' | null ;
} & ExecOptions
) : PromiseWithChild < {
stdout : Buffer ;
stderr : Buffer ;
} > ;
function __promisify__ (
command : string ,
options : {
encoding : BufferEncoding ;
} & ExecOptions
) : PromiseWithChild < {
stdout : string ;
stderr : string ;
} > ;
function __promisify__ (
command : string ,
options : ExecOptions
) : PromiseWithChild < {
stdout : string ;
stderr : string ;
} > ;
function __promisify__ (
command : string ,
options ? : ( ObjectEncodingOptions & ExecOptions ) | null
) : PromiseWithChild < {
stdout : string | Buffer ;
stderr : string | Buffer ;
} > ;
2021-09-29 18:17:34 +02:00
}
2023-03-03 11:55:06 +01:00
interface ExecFileOptions extends CommonOptions , Abortable {
2021-09-29 18:17:34 +02:00
maxBuffer? : number | undefined ;
killSignal? : NodeJS.Signals | number | undefined ;
windowsVerbatimArguments? : boolean | undefined ;
shell? : boolean | string | undefined ;
2023-03-03 11:55:06 +01:00
signal? : AbortSignal | undefined ;
2021-09-29 18:17:34 +02:00
}
interface ExecFileOptionsWithStringEncoding extends ExecFileOptions {
encoding : BufferEncoding ;
}
interface ExecFileOptionsWithBufferEncoding extends ExecFileOptions {
encoding : 'buffer' | null ;
}
interface ExecFileOptionsWithOtherEncoding extends ExecFileOptions {
encoding : BufferEncoding ;
}
type ExecFileException = ExecException & NodeJS . ErrnoException ;
2023-03-03 11:55:06 +01:00
/ * *
* The ` child_process.execFile() ` function is similar to { @link exec } except that it does not spawn a shell by default . Rather , the specified
* executable ` file ` is spawned directly as a new process making it slightly more
* efficient than { @link exec } .
*
* The same options as { @link exec } are supported . Since a shell is
* not spawned , behaviors such as I / O redirection and file globbing are not
* supported .
*
* ` ` ` js
* const { execFile } = require ( 'child_process' ) ;
* const child = execFile ( 'node' , [ '--version' ] , ( error , stdout , stderr ) = > {
* if ( error ) {
* throw error ;
* }
* console . log ( stdout ) ;
* } ) ;
* ` ` `
*
* The ` stdout ` and ` stderr ` arguments passed to the callback will contain the
* stdout and stderr output of the child process . By default , Node . js will decode
* the output as UTF - 8 and pass strings to the callback . The ` encoding ` option
* can be used to specify the character encoding used to decode the stdout and
* stderr output . If ` encoding ` is ` 'buffer' ` , or an unrecognized character
* encoding , ` Buffer ` objects will be passed to the callback instead .
*
* If this method is invoked as its ` util.promisify() ` ed version , it returns
* a ` Promise ` for an ` Object ` with ` stdout ` and ` stderr ` properties . The returned ` ChildProcess ` instance is attached to the ` Promise ` as a ` child ` property . In
* case of an error ( including any error resulting in an exit code other than 0 ) , a
* rejected promise is returned , with the same ` error ` object given in the
* callback , but with two additional properties ` stdout ` and ` stderr ` .
*
* ` ` ` js
* const util = require ( 'util' ) ;
* const execFile = util . promisify ( require ( 'child_process' ) . execFile ) ;
* async function getVersion() {
* const { stdout } = await execFile ( 'node' , [ '--version' ] ) ;
* console . log ( stdout ) ;
* }
* getVersion ( ) ;
* ` ` `
*
* * * If the ` shell ` option is enabled , do not pass unsanitized user input to this * *
* * * function . Any input containing shell metacharacters may be used to trigger * *
* * * arbitrary command execution . * *
*
* If the ` signal ` option is enabled , calling ` .abort() ` on the corresponding ` AbortController ` is similar to calling ` .kill() ` on the child process except
* the error passed to the callback will be an ` AbortError ` :
*
* ` ` ` js
* const { execFile } = require ( 'child_process' ) ;
* const controller = new AbortController ( ) ;
* const { signal } = controller ;
* const child = execFile ( 'node' , [ '--version' ] , { signal } , ( error ) = > {
* console . log ( error ) ; // an AbortError
* } ) ;
* controller . abort ( ) ;
* ` ` `
* @since v0 . 1.91
* @param file The name or path of the executable file to run .
* @param args List of string arguments .
* @param callback Called with the output when process terminates .
* /
2021-09-29 18:17:34 +02:00
function execFile ( file : string ) : ChildProcess ;
2023-03-03 11:55:06 +01:00
function execFile ( file : string , options : ( ObjectEncodingOptions & ExecFileOptions ) | undefined | null ) : ChildProcess ;
2021-09-29 18:17:34 +02:00
function execFile ( file : string , args? : ReadonlyArray < string > | null ) : ChildProcess ;
2023-03-03 11:55:06 +01:00
function execFile ( file : string , args : ReadonlyArray < string > | undefined | null , options : ( ObjectEncodingOptions & ExecFileOptions ) | undefined | null ) : ChildProcess ;
2021-09-29 18:17:34 +02:00
// no `options` definitely means stdout/stderr are `string`.
function execFile ( file : string , callback : ( error : ExecFileException | null , stdout : string , stderr : string ) = > void ) : ChildProcess ;
function execFile ( file : string , args : ReadonlyArray < string > | undefined | null , callback : ( error : ExecFileException | null , stdout : string , stderr : string ) = > void ) : ChildProcess ;
// `options` with `"buffer"` or `null` for `encoding` means stdout/stderr are definitely `Buffer`.
function execFile ( file : string , options : ExecFileOptionsWithBufferEncoding , callback : ( error : ExecFileException | null , stdout : Buffer , stderr : Buffer ) = > void ) : ChildProcess ;
function execFile (
file : string ,
args : ReadonlyArray < string > | undefined | null ,
options : ExecFileOptionsWithBufferEncoding ,
2023-03-03 11:55:06 +01:00
callback : ( error : ExecFileException | null , stdout : Buffer , stderr : Buffer ) = > void
2021-09-29 18:17:34 +02:00
) : ChildProcess ;
// `options` with well known `encoding` means stdout/stderr are definitely `string`.
function execFile ( file : string , options : ExecFileOptionsWithStringEncoding , callback : ( error : ExecFileException | null , stdout : string , stderr : string ) = > void ) : ChildProcess ;
function execFile (
file : string ,
args : ReadonlyArray < string > | undefined | null ,
options : ExecFileOptionsWithStringEncoding ,
2023-03-03 11:55:06 +01:00
callback : ( error : ExecFileException | null , stdout : string , stderr : string ) = > void
2021-09-29 18:17:34 +02:00
) : ChildProcess ;
// `options` with an `encoding` whose type is `string` means stdout/stderr could either be `Buffer` or `string`.
// There is no guarantee the `encoding` is unknown as `string` is a superset of `BufferEncoding`.
2023-03-03 11:55:06 +01:00
function execFile ( file : string , options : ExecFileOptionsWithOtherEncoding , callback : ( error : ExecFileException | null , stdout : string | Buffer , stderr : string | Buffer ) = > void ) : ChildProcess ;
2021-09-29 18:17:34 +02:00
function execFile (
file : string ,
args : ReadonlyArray < string > | undefined | null ,
options : ExecFileOptionsWithOtherEncoding ,
2023-03-03 11:55:06 +01:00
callback : ( error : ExecFileException | null , stdout : string | Buffer , stderr : string | Buffer ) = > void
2021-09-29 18:17:34 +02:00
) : ChildProcess ;
// `options` without an `encoding` means stdout/stderr are definitely `string`.
function execFile ( file : string , options : ExecFileOptions , callback : ( error : ExecFileException | null , stdout : string , stderr : string ) = > void ) : ChildProcess ;
function execFile (
file : string ,
args : ReadonlyArray < string > | undefined | null ,
options : ExecFileOptions ,
callback : ( error : ExecFileException | null , stdout : string , stderr : string ) = > void
) : ChildProcess ;
// fallback if nothing else matches. Worst case is always `string | Buffer`.
function execFile (
file : string ,
2023-03-03 11:55:06 +01:00
options : ( ObjectEncodingOptions & ExecFileOptions ) | undefined | null ,
callback : ( ( error : ExecFileException | null , stdout : string | Buffer , stderr : string | Buffer ) = > void ) | undefined | null
2021-09-29 18:17:34 +02:00
) : ChildProcess ;
function execFile (
file : string ,
args : ReadonlyArray < string > | undefined | null ,
2023-03-03 11:55:06 +01:00
options : ( ObjectEncodingOptions & ExecFileOptions ) | undefined | null ,
callback : ( ( error : ExecFileException | null , stdout : string | Buffer , stderr : string | Buffer ) = > void ) | undefined | null
2021-09-29 18:17:34 +02:00
) : ChildProcess ;
namespace execFile {
2023-03-03 11:55:06 +01:00
function __promisify__ ( file : string ) : PromiseWithChild < {
stdout : string ;
stderr : string ;
} > ;
function __promisify__ (
file : string ,
args : ReadonlyArray < string > | undefined | null
) : PromiseWithChild < {
stdout : string ;
stderr : string ;
} > ;
function __promisify__ (
file : string ,
options : ExecFileOptionsWithBufferEncoding
) : PromiseWithChild < {
stdout : Buffer ;
stderr : Buffer ;
} > ;
function __promisify__ (
file : string ,
args : ReadonlyArray < string > | undefined | null ,
options : ExecFileOptionsWithBufferEncoding
) : PromiseWithChild < {
stdout : Buffer ;
stderr : Buffer ;
} > ;
function __promisify__ (
file : string ,
options : ExecFileOptionsWithStringEncoding
) : PromiseWithChild < {
stdout : string ;
stderr : string ;
} > ;
function __promisify__ (
file : string ,
args : ReadonlyArray < string > | undefined | null ,
options : ExecFileOptionsWithStringEncoding
) : PromiseWithChild < {
stdout : string ;
stderr : string ;
} > ;
function __promisify__ (
file : string ,
options : ExecFileOptionsWithOtherEncoding
) : PromiseWithChild < {
stdout : string | Buffer ;
stderr : string | Buffer ;
} > ;
2021-09-29 18:17:34 +02:00
function __promisify__ (
file : string ,
args : ReadonlyArray < string > | undefined | null ,
2023-03-03 11:55:06 +01:00
options : ExecFileOptionsWithOtherEncoding
) : PromiseWithChild < {
stdout : string | Buffer ;
stderr : string | Buffer ;
} > ;
function __promisify__ (
file : string ,
options : ExecFileOptions
) : PromiseWithChild < {
stdout : string ;
stderr : string ;
} > ;
2021-09-29 18:17:34 +02:00
function __promisify__ (
file : string ,
args : ReadonlyArray < string > | undefined | null ,
2023-03-03 11:55:06 +01:00
options : ExecFileOptions
) : PromiseWithChild < {
stdout : string ;
stderr : string ;
} > ;
function __promisify__ (
file : string ,
options : ( ObjectEncodingOptions & ExecFileOptions ) | undefined | null
) : PromiseWithChild < {
stdout : string | Buffer ;
stderr : string | Buffer ;
} > ;
function __promisify__ (
file : string ,
args : ReadonlyArray < string > | undefined | null ,
options : ( ObjectEncodingOptions & ExecFileOptions ) | undefined | null
) : PromiseWithChild < {
stdout : string | Buffer ;
stderr : string | Buffer ;
} > ;
2021-09-29 18:17:34 +02:00
}
2023-03-03 11:55:06 +01:00
interface ForkOptions extends ProcessEnvOptions , MessagingOptions , Abortable {
2021-09-29 18:17:34 +02:00
execPath? : string | undefined ;
execArgv? : string [ ] | undefined ;
silent? : boolean | undefined ;
stdio? : StdioOptions | undefined ;
detached? : boolean | undefined ;
windowsVerbatimArguments? : boolean | undefined ;
}
2023-03-03 11:55:06 +01:00
/ * *
* The ` child_process.fork() ` method is a special case of { @link spawn } used specifically to spawn new Node . js processes .
* Like { @link spawn } , a ` ChildProcess ` object is returned . The
* returned ` ChildProcess ` will have an additional communication channel
* built - in that allows messages to be passed back and forth between the parent and
* child . See ` subprocess.send() ` for details .
*
* Keep in mind that spawned Node . js child processes are
* independent of the parent with exception of the IPC communication channel
* that is established between the two . Each process has its own memory , with
* their own V8 instances . Because of the additional resource allocations
* required , spawning a large number of child Node . js processes is not
* recommended .
*
* By default , ` child_process.fork() ` will spawn new Node . js instances using the ` process.execPath ` of the parent process . The ` execPath ` property in the ` options ` object allows for an alternative
* execution path to be used .
*
* Node . js processes launched with a custom ` execPath ` will communicate with the
* parent process using the file descriptor ( fd ) identified using the
* environment variable ` NODE_CHANNEL_FD ` on the child process .
*
* Unlike the [ ` fork(2) ` ] ( http : //man7.org/linux/man-pages/man2/fork.2.html) POSIX system call, `child_process.fork()` does not clone the
* current process .
*
* The ` shell ` option available in { @link spawn } is not supported by ` child_process.fork() ` and will be ignored if set .
*
* If the ` signal ` option is enabled , calling ` .abort() ` on the corresponding ` AbortController ` is similar to calling ` .kill() ` on the child process except
* the error passed to the callback will be an ` AbortError ` :
*
* ` ` ` js
* if ( process . argv [ 2 ] === 'child' ) {
* setTimeout ( ( ) = > {
* console . log ( ` Hello from ${ process . argv [ 2 ] } ! ` ) ;
* } , 1 _000 ) ;
* } else {
* const { fork } = require ( 'child_process' ) ;
* const controller = new AbortController ( ) ;
* const { signal } = controller ;
* const child = fork ( __filename , [ 'child' ] , { signal } ) ;
* child . on ( 'error' , ( err ) = > {
* // This will be called with err being an AbortError if the controller aborts
* } ) ;
* controller . abort ( ) ; // Stops the child process
* }
* ` ` `
* @since v0 . 5.0
* @param module Path The module to run in the child .
* @param args List of string arguments .
* /
2021-09-29 18:17:34 +02:00
function fork ( module Path : string , options? : ForkOptions ) : ChildProcess ;
function fork ( module Path : string , args? : ReadonlyArray < string > , options? : ForkOptions ) : ChildProcess ;
interface SpawnSyncOptions extends CommonSpawnOptions {
input? : string | NodeJS . ArrayBufferView | undefined ;
maxBuffer? : number | undefined ;
encoding? : BufferEncoding | 'buffer' | null | undefined ;
}
interface SpawnSyncOptionsWithStringEncoding extends SpawnSyncOptions {
encoding : BufferEncoding ;
}
interface SpawnSyncOptionsWithBufferEncoding extends SpawnSyncOptions {
encoding ? : 'buffer' | null | undefined ;
}
interface SpawnSyncReturns < T > {
pid : number ;
output : Array < T | null > ;
stdout : T ;
stderr : T ;
status : number | null ;
signal : NodeJS.Signals | null ;
error? : Error | undefined ;
}
2023-03-03 11:55:06 +01:00
/ * *
* The ` child_process.spawnSync() ` method is generally identical to { @link spawn } with the exception that the function will not return
* until the child process has fully closed . When a timeout has been encountered
* and ` killSignal ` is sent , the method won ' t return until the process has
* completely exited . If the process intercepts and handles the ` SIGTERM ` signal
* and doesn ' t exit , the parent process will wait until the child process has
* exited .
*
* * * If the ` shell ` option is enabled , do not pass unsanitized user input to this * *
* * * function . Any input containing shell metacharacters may be used to trigger * *
* * * arbitrary command execution . * *
* @since v0 . 11.12
* @param command The command to run .
* @param args List of string arguments .
* /
2021-09-29 18:17:34 +02:00
function spawnSync ( command : string ) : SpawnSyncReturns < Buffer > ;
2023-03-03 11:55:06 +01:00
function spawnSync ( command : string , options : SpawnSyncOptionsWithStringEncoding ) : SpawnSyncReturns < string > ;
function spawnSync ( command : string , options : SpawnSyncOptionsWithBufferEncoding ) : SpawnSyncReturns < Buffer > ;
2021-09-29 18:17:34 +02:00
function spawnSync ( command : string , options? : SpawnSyncOptions ) : SpawnSyncReturns < string | Buffer > ;
2023-03-03 11:55:06 +01:00
function spawnSync ( command : string , args : ReadonlyArray < string > ) : SpawnSyncReturns < Buffer > ;
function spawnSync ( command : string , args : ReadonlyArray < string > , options : SpawnSyncOptionsWithStringEncoding ) : SpawnSyncReturns < string > ;
function spawnSync ( command : string , args : ReadonlyArray < string > , options : SpawnSyncOptionsWithBufferEncoding ) : SpawnSyncReturns < Buffer > ;
2021-09-29 18:17:34 +02:00
function spawnSync ( command : string , args? : ReadonlyArray < string > , options? : SpawnSyncOptions ) : SpawnSyncReturns < string | Buffer > ;
2023-03-03 11:55:06 +01:00
interface CommonExecOptions extends CommonOptions {
input? : string | NodeJS . ArrayBufferView | undefined ;
2021-09-29 18:17:34 +02:00
stdio? : StdioOptions | undefined ;
killSignal? : NodeJS.Signals | number | undefined ;
maxBuffer? : number | undefined ;
encoding? : BufferEncoding | 'buffer' | null | undefined ;
}
2023-03-03 11:55:06 +01:00
interface ExecSyncOptions extends CommonExecOptions {
shell? : string | undefined ;
}
2021-09-29 18:17:34 +02:00
interface ExecSyncOptionsWithStringEncoding extends ExecSyncOptions {
encoding : BufferEncoding ;
}
interface ExecSyncOptionsWithBufferEncoding extends ExecSyncOptions {
encoding ? : 'buffer' | null | undefined ;
}
2023-03-03 11:55:06 +01:00
/ * *
* The ` child_process.execSync() ` method is generally identical to { @link exec } with the exception that the method will not return
* until the child process has fully closed . When a timeout has been encountered
* and ` killSignal ` is sent , the method won ' t return until the process has
* completely exited . If the child process intercepts and handles the ` SIGTERM ` signal and doesn ' t exit , the parent process will wait until the child process
* has exited .
*
* If the process times out or has a non - zero exit code , this method will throw .
* The ` Error ` object will contain the entire result from { @link spawnSync } .
*
* * * Never pass unsanitized user input to this function . Any input containing shell * *
* * * metacharacters may be used to trigger arbitrary command execution . * *
* @since v0 . 11.12
* @param command The command to run .
* @return The stdout from the command .
* /
2021-09-29 18:17:34 +02:00
function execSync ( command : string ) : Buffer ;
function execSync ( command : string , options : ExecSyncOptionsWithStringEncoding ) : string ;
function execSync ( command : string , options : ExecSyncOptionsWithBufferEncoding ) : Buffer ;
function execSync ( command : string , options? : ExecSyncOptions ) : string | Buffer ;
2023-03-03 11:55:06 +01:00
interface ExecFileSyncOptions extends CommonExecOptions {
2021-09-29 18:17:34 +02:00
shell? : boolean | string | undefined ;
}
interface ExecFileSyncOptionsWithStringEncoding extends ExecFileSyncOptions {
encoding : BufferEncoding ;
}
interface ExecFileSyncOptionsWithBufferEncoding extends ExecFileSyncOptions {
2023-03-03 11:55:06 +01:00
encoding ? : 'buffer' | null ; // specify `null`.
}
/ * *
* The ` child_process.execFileSync() ` method is generally identical to { @link execFile } with the exception that the method will not
* return until the child process has fully closed . When a timeout has been
* encountered and ` killSignal ` is sent , the method won ' t return until the process
* has completely exited .
*
* If the child process intercepts and handles the ` SIGTERM ` signal and
* does not exit , the parent process will still wait until the child process has
* exited .
*
* If the process times out or has a non - zero exit code , this method will throw an ` Error ` that will include the full result of the underlying { @link spawnSync } .
*
* * * If the ` shell ` option is enabled , do not pass unsanitized user input to this * *
* * * function . Any input containing shell metacharacters may be used to trigger * *
* * * arbitrary command execution . * *
* @since v0 . 11.12
* @param file The name or path of the executable file to run .
* @param args List of string arguments .
* @return The stdout from the command .
* /
function execFileSync ( file : string ) : Buffer ;
function execFileSync ( file : string , options : ExecFileSyncOptionsWithStringEncoding ) : string ;
function execFileSync ( file : string , options : ExecFileSyncOptionsWithBufferEncoding ) : Buffer ;
function execFileSync ( file : string , options? : ExecFileSyncOptions ) : string | Buffer ;
function execFileSync ( file : string , args : ReadonlyArray < string > ) : Buffer ;
function execFileSync ( file : string , args : ReadonlyArray < string > , options : ExecFileSyncOptionsWithStringEncoding ) : string ;
function execFileSync ( file : string , args : ReadonlyArray < string > , options : ExecFileSyncOptionsWithBufferEncoding ) : Buffer ;
function execFileSync ( file : string , args? : ReadonlyArray < string > , options? : ExecFileSyncOptions ) : string | Buffer ;
2021-09-29 18:17:34 +02:00
}
2022-04-10 02:18:16 +02:00
declare module 'node:child_process' {
export * from 'child_process' ;
}