Skip to content

Commit af27225

Browse files
evanshortissmarco-ippolito
authored andcommittedJun 17, 2024
doc: add example for execFileSync method and ref to stdio
Added an example to the `execFileSync` method. This demonstrates how to handle exceptions and access the stderr and stdio properties that are attached to the `Error` object in a `catch` block. Added a link to the detailed stdio section nested under `child_process.spawn()` from each child_process sync method option description. Fixes: #39306 PR-URL: #39412 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
1 parent 0be8123 commit af27225

File tree

1 file changed

+34
-3
lines changed

1 file changed

+34
-3
lines changed
 

‎doc/api/child_process.md

+34-3
Original file line numberDiff line numberDiff line change
@@ -921,7 +921,8 @@ changes:
921921
* `input` {string|Buffer|TypedArray|DataView} The value which will be passed
922922
as stdin to the spawned process. If `stdio[0]` is set to `'pipe'`, Supplying
923923
this value will override `stdio[0]`.
924-
* `stdio` {string|Array} Child's stdio configuration. `stderr` by default will
924+
* `stdio` {string|Array} Child's stdio configuration.
925+
See [`child_process.spawn()`][]'s [`stdio`][]. `stderr` by default will
925926
be output to the parent process' stderr unless `stdio` is specified.
926927
**Default:** `'pipe'`.
927928
* `env` {Object} Environment key-value pairs. **Default:** `process.env`.
@@ -962,6 +963,34 @@ If the process times out or has a non-zero exit code, this method will throw an
962963
function. Any input containing shell metacharacters may be used to trigger
963964
arbitrary command execution.**
964965

966+
```js
967+
const { execFileSync } = require('node:child_process');
968+
969+
try {
970+
const stdout = execFileSync('my-script.sh', ['my-arg'], {
971+
// Capture stdout and stderr from child process. Overrides the
972+
// default behavior of streaming child stderr to the parent stderr
973+
stdio: 'pipe',
974+
975+
// Use utf8 encoding for stdio pipes
976+
encoding: 'utf8',
977+
});
978+
979+
console.log(stdout);
980+
} catch (err) {
981+
if (err.code) {
982+
// Spawning child process failed
983+
console.error(err.code);
984+
} else {
985+
// Child was spawned but exited with non-zero exit code
986+
// Error contains any stdout and stderr from the child
987+
const { stdout, stderr } = err;
988+
989+
console.error({ stdout, stderr });
990+
}
991+
}
992+
```
993+
965994
### `child_process.execSync(command[, options])`
966995

967996
<!-- YAML
@@ -991,7 +1020,8 @@ changes:
9911020
* `input` {string|Buffer|TypedArray|DataView} The value which will be passed
9921021
as stdin to the spawned process. If `stdio[0]` is set to `'pipe'`, Supplying
9931022
this value will override `stdio[0]`.
994-
* `stdio` {string|Array} Child's stdio configuration. `stderr` by default will
1023+
* `stdio` {string|Array} Child's stdio configuration.
1024+
See [`child_process.spawn()`][]'s [`stdio`][]. `stderr` by default will
9951025
be output to the parent process' stderr unless `stdio` is specified.
9961026
**Default:** `'pipe'`.
9971027
* `env` {Object} Environment key-value pairs. **Default:** `process.env`.
@@ -1069,7 +1099,8 @@ changes:
10691099
this value will override `stdio[0]`.
10701100
* `argv0` {string} Explicitly set the value of `argv[0]` sent to the child
10711101
process. This will be set to `command` if not specified.
1072-
* `stdio` {string|Array} Child's stdio configuration. **Default:** `'pipe'`.
1102+
* `stdio` {string|Array} Child's stdio configuration.
1103+
See [`child_process.spawn()`][]'s [`stdio`][]. **Default:** `'pipe'`.
10731104
* `env` {Object} Environment key-value pairs. **Default:** `process.env`.
10741105
* `uid` {number} Sets the user identity of the process (see setuid(2)).
10751106
* `gid` {number} Sets the group identity of the process (see setgid(2)).

0 commit comments

Comments
 (0)
Please sign in to comment.