Commit c0000f4
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 ea6070b commit c0000f4
1 file changed
Lines changed: 34 additions & 3 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -921,7 +921,8 @@ changes: | |||
| 921 | 921 | * `input` {string|Buffer|TypedArray|DataView} The value which will be passed | |
| 922 | 922 | as stdin to the spawned process. If `stdio[0]` is set to `'pipe'`, Supplying | |
| 923 | 923 | 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 | ||
| 925 | 926 | be output to the parent process' stderr unless `stdio` is specified. | |
| 926 | 927 | **Default:** `'pipe'`. | |
| 927 | 928 | * `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 | |||
| 962 | 963 | function. Any input containing shell metacharacters may be used to trigger | |
| 963 | 964 | arbitrary command execution.** | |
| 964 | 965 | ||
| 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 | + | ||
| 965 | 994 | ### `child_process.execSync(command[, options])` | |
| 966 | 995 | ||
| 967 | 996 | <!-- YAML | |
@@ -991,7 +1020,8 @@ changes: | |||
| 991 | 1020 | * `input` {string|Buffer|TypedArray|DataView} The value which will be passed | |
| 992 | 1021 | as stdin to the spawned process. If `stdio[0]` is set to `'pipe'`, Supplying | |
| 993 | 1022 | 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 | ||
| 995 | 1025 | be output to the parent process' stderr unless `stdio` is specified. | |
| 996 | 1026 | **Default:** `'pipe'`. | |
| 997 | 1027 | * `env` {Object} Environment key-value pairs. **Default:** `process.env`. | |
@@ -1069,7 +1099,8 @@ changes: | |||
| 1069 | 1099 | this value will override `stdio[0]`. | |
| 1070 | 1100 | * `argv0` {string} Explicitly set the value of `argv[0]` sent to the child | |
| 1071 | 1101 | 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'`. | ||
| 1073 | 1104 | * `env` {Object} Environment key-value pairs. **Default:** `process.env`. | |
| 1074 | 1105 | * `uid` {number} Sets the user identity of the process (see setuid(2)). | |
| 1075 | 1106 | * `gid` {number} Sets the group identity of the process (see setgid(2)). | |
0 commit comments