Commit 4be373b
doc: fixes default shell in child_process.md
Clarifies the default shell in Windows is process.env.ComSpec
and that cmd.exe is only used as a fallback. Functions whose
descriptions are affected include:
child_process.spawn, child_process.exec,
child_process.spawnsSync, and child_process.execSync.
PR-URL: #14203
Fixes: #14156
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>1 parent b12924d commit 4be373b
1 file changed
Lines changed: 25 additions & 12 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -133,9 +133,8 @@ added: v0.1.90 | |||
| 133 | 133 | * `env` {Object} Environment key-value pairs | |
| 134 | 134 | * `encoding` {string} (Default: `'utf8'`) | |
| 135 | 135 | * `shell` {string} Shell to execute the command with | |
| 136 | - (Default: `'/bin/sh'` on UNIX, `'cmd.exe'` on Windows, The shell should | ||
| 137 | - understand the `-c` switch on UNIX or `/d /s /c` on Windows. On Windows, | ||
| 138 | - command line parsing should be compatible with `cmd.exe`.) | ||
| 136 | + (Default: `'/bin/sh'` on UNIX, `process.env.ComSpec` on Windows. See | ||
| 137 | + [Shell Requirements][] and [Default Windows Shell][].) | ||
| 139 | 138 | * `timeout` {number} (Default: `0`) | |
| 140 | 139 | * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or | |
| 141 | 140 | stderr. (Default: `200*1024`) If exceeded, the child process is terminated. | |
@@ -382,9 +381,9 @@ changes: | |||
| 382 | 381 | * `uid` {number} Sets the user identity of the process. (See setuid(2).) | |
| 383 | 382 | * `gid` {number} Sets the group identity of the process. (See setgid(2).) | |
| 384 | 383 | * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses | |
| 385 | - `'/bin/sh'` on UNIX, and `'cmd.exe'` on Windows. A different shell can be | ||
| 386 | - specified as a string. The shell should understand the `-c` switch on UNIX, | ||
| 387 | - or `/d /s /c` on Windows. Defaults to `false` (no shell). | ||
| 384 | + `'/bin/sh'` on UNIX, and `process.env.ComSpec` on Windows. A different | ||
| 385 | + shell can be specified as a string. See [Shell Requirements][] and | ||
| 386 | + [Default Windows Shell][]. Defaults to `false` (no shell). | ||
| 388 | 387 | * Returns: {ChildProcess} | |
| 389 | 388 | ||
| 390 | 389 | The `child_process.spawn()` method spawns a new process using the given | |
@@ -707,9 +706,8 @@ changes: | |||
| 707 | 706 | `stdio` is specified | |
| 708 | 707 | * `env` {Object} Environment key-value pairs | |
| 709 | 708 | * `shell` {string} Shell to execute the command with | |
| 710 | - (Default: `'/bin/sh'` on UNIX, `'cmd.exe'` on Windows, The shell should | ||
| 711 | - understand the `-c` switch on UNIX or `/d /s /c` on Windows. On Windows, | ||
| 712 | - command line parsing should be compatible with `cmd.exe`.) | ||
| 709 | + (Default: `'/bin/sh'` on UNIX, `process.env.ComSpec` on Windows. See | ||
| 710 | + [Shell Requirements][] and [Default Windows Shell][].) | ||
| 713 | 711 | * `uid` {number} Sets the user identity of the process. (See setuid(2).) | |
| 714 | 712 | * `gid` {number} Sets the group identity of the process. (See setgid(2).) | |
| 715 | 713 | * `timeout` {number} In milliseconds the maximum amount of time the process | |
@@ -775,9 +773,9 @@ changes: | |||
| 775 | 773 | * `encoding` {string} The encoding used for all stdio inputs and outputs. | |
| 776 | 774 | (Default: `'buffer'`) | |
| 777 | 775 | * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses | |
| 778 | - `'/bin/sh'` on UNIX, and `'cmd.exe'` on Windows. A different shell can be | ||
| 779 | - specified as a string. The shell should understand the `-c` switch on UNIX, | ||
| 780 | - or `/d /s /c` on Windows. Defaults to `false` (no shell). | ||
| 776 | + `'/bin/sh'` on UNIX, and `process.env.ComSpec` on Windows. A different | ||
| 777 | + shell can be specified as a string. See [Shell Requirements][] and | ||
| 778 | + [Default Windows Shell][]. Defaults to `false` (no shell). | ||
| 781 | 779 | * Returns: {Object} | |
| 782 | 780 | * `pid` {number} Pid of the child process | |
| 783 | 781 | * `output` {Array} Array of results from stdio output | |
@@ -1281,6 +1279,19 @@ This impacts output that includes multibyte character encodings such as UTF-8 or | |||
| 1281 | 1279 | UTF-16. For instance, `console.log('中文测试')` will send 13 UTF-8 encoded bytes | |
| 1282 | 1280 | to `stdout` although there are only 4 characters. | |
| 1283 | 1281 | ||
| 1282 | + ## Shell Requirements | ||
| 1283 | + | ||
| 1284 | + The shell should understand the `-c` switch on UNIX or `/d /s /c` on Windows. | ||
| 1285 | + On Windows, command line parsing should be compatible with `'cmd.exe'`. | ||
| 1286 | + | ||
| 1287 | + ## Default Windows Shell | ||
| 1288 | + | ||
| 1289 | + Although Microsoft specifies `%COMSPEC%` must contain the path to | ||
| 1290 | + `'cmd.exe'` in the root environment, child processes are not always subject to | ||
| 1291 | + the same requirement. Thus, in `child_process` functions where a shell can be | ||
| 1292 | + spawned, `'cmd.exe'` is used as a fallback if `process.env.ComSpec` is | ||
| 1293 | + unavailable. | ||
| 1294 | + | ||
| 1284 | 1295 | [`'error'`]: #child_process_event_error | |
| 1285 | 1296 | [`'exit'`]: #child_process_event_exit | |
| 1286 | 1297 | [`'message'`]: #child_process_event_message | |
@@ -1314,4 +1325,6 @@ to `stdout` although there are only 4 characters. | |||
| 1314 | 1325 | [`process.send()`]: process.html#process_process_send_message_sendhandle_options_callback | |
| 1315 | 1326 | [`stdio`]: #child_process_options_stdio | |
| 1316 | 1327 | [`util.promisify()`]: util.html#util_util_promisify_original | |
| 1328 | + [Default Windows Shell]: #child_process_default_windows_shell | ||
| 1329 | + [Shell Requirements]: #child_process_shell_requirements | ||
| 1317 | 1330 | [synchronous counterparts]: #child_process_synchronous_process_creation | |
0 commit comments