diff --git a/lib/child_process.js b/lib/child_process.js index 73268b05a85740..62c552d567eaad 100644 --- a/lib/child_process.js +++ b/lib/child_process.js @@ -89,6 +89,28 @@ const { const MAX_BUFFER = 1024 * 1024; +/** + * Spawns a new Node.js process + fork. + * @param {string} modulePath + * @param {string[]} [args] + * @param {{ + * cwd?: string; + * detached?: boolean; + * env?: Object; + * execPath?: string; + * execArgv?: string[]; + * gid?: number; + * serialization?: string; + * signal?: AbortSignal; + * killSignal?: string | number; + * silent?: boolean; + * stdio?: Array | string; + * uid?: number; + * windowsVerbatimArguments?: boolean; + * timeout?: number; + * }} [options] + * @returns {ChildProcess} + */ function fork(modulePath /* , args, options */) { validateString(modulePath, 'modulePath'); @@ -176,7 +198,29 @@ function normalizeExecArgs(command, options, callback) { }; } - +/** + * Spawns a shell executing the given command. + * @param {string} command + * @param {{ + * cmd?: string; + * env?: Object; + * encoding?: string; + * shell?: string; + * signal?: AbortSignal; + * timeout?: number; + * maxBuffer?: number; + * killSignal?: string | number; + * uid?: number; + * gid?: number; + * windowsHide?: boolean; + * }} [options] + * @param {( + * error?: Error, + * stdout?: string | Buffer, + * stderr?: string | Buffer + * ) => any} [callback] + * @returns {ChildProcess} + */ function exec(command, options, callback) { const opts = normalizeExecArgs(command, options, callback); return module.exports.execFile(opts.file, @@ -207,6 +251,31 @@ ObjectDefineProperty(exec, promisify.custom, { value: customPromiseExecFunction(exec) }); +/** + * Spawns the specified file as a shell. + * @param {string} file + * @param {string[]} [args] + * @param {{ + * cwd?: string; + * env?: Object; + * encoding?: string; + * timeout?: number; + * maxBuffer?: number; + * killSignal?: string | number; + * uid?: number; + * gid?: number; + * windowsHide?: boolean; + * windowsVerbatimArguments?: boolean; + * shell?: boolean | string; + * signal?: AbortSignal; + * }} [options] + * @param {( + * error?: Error, + * stdout?: string | Buffer, + * stderr?: string | Buffer + * ) => any} [callback] + * @returns {ChildProcess} + */ function execFile(file /* , args, options, callback */) { let args = []; let callback; @@ -596,7 +665,28 @@ function abortChildProcess(child, killSignal) { } } - +/** + * Spawns a new process using the given `file`. + * @param {string} file + * @param {string[]} [args] + * @param {{ + * cwd?: string; + * env?: Object; + * argv0?: string; + * stdio?: Array | string; + * detached?: boolean; + * uid?: number; + * gid?: number; + * serialization?: string; + * shell?: boolean | string; + * windowsVerbatimArguments?: boolean; + * windowsHide?: boolean; + * signal?: AbortSignal; + * timeout?: number; + * killSignal?: string | number; + * }} [options] + * @returns {ChildProcess} + */ function spawn(file, args, options) { options = normalizeSpawnArguments(file, args, options); validateTimeout(options.timeout); @@ -645,6 +735,36 @@ function spawn(file, args, options) { return child; } +/** + * Spawns a new process synchronously using the given `file`. + * @param {string} file + * @param {string[]} [args] + * @param {{ + * cwd?: string; + * input?: string | Buffer | TypedArray | DataView; + * argv0?: string; + * stdio?: string | Array; + * env?: Object; + * uid?: number; + * gid?: number; + * timeout?: number; + * killSignal?: string | number; + * maxBuffer?: number; + * encoding?: string; + * shell?: boolean | string; + * windowsVerbatimArguments?: boolean; + * windowsHide?: boolean; + * }} [options] + * @returns {{ + * pid: number; + * output: Array; + * stdout: Buffer | string; + * stderr: Buffer | string; + * status: number | null; + * signal: string | null; + * error: Error; + * }} + */ function spawnSync(file, args, options) { options = { maxBuffer: MAX_BUFFER, @@ -711,7 +831,26 @@ function checkExecSyncError(ret, args, cmd) { return err; } - +/** + * Spawns a file as a shell synchronously. + * @param {string} command + * @param {string[]} [args] + * @param {{ + * cwd?: string; + * input?: string | Buffer | TypedArray | DataView; + * stdio?: string | Array; + * env?: Object; + * uid?: number; + * gid?: number; + * timeout?: number; + * killSignal?: string | number; + * maxBuffer?: number; + * encoding?: string; + * windowsHide?: boolean; + * shell?: boolean | string; + * }} [options] + * @returns {Buffer | string} + */ function execFileSync(command, args, options) { options = normalizeSpawnArguments(command, args, options); @@ -730,7 +869,25 @@ function execFileSync(command, args, options) { return ret.stdout; } - +/** + * Spawns a shell executing the given `command` synchronously. + * @param {string} command + * @param {{ + * cwd?: string; + * input?: string | Buffer | TypedArray | DataView; + * stdio?: string | Array; + * env?: Object; + * shell?: string; + * uid?: number; + * gid?: number; + * timeout?: number; + * killSignal?: string | number; + * maxBuffer?: number; + * encoding?: string; + * windowsHide?: boolean; + * }} [options] + * @returns {Buffer | string} + */ function execSync(command, options) { const opts = normalizeExecArgs(command, options, null); const inheritStderr = !opts.options.stdio;