From 1a07c2a57ee449883bd5e75b24059b7cf74aef81 Mon Sep 17 00:00:00 2001 From: Henry Date: Wed, 12 Jul 2017 14:53:23 -0400 Subject: [PATCH 1/7] 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. Fixes: https://github.com/nodejs/node/issues/14156 --- doc/api/child_process.md | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/doc/api/child_process.md b/doc/api/child_process.md index a834f5151e25a1..157b35cabe4ba6 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -1,4 +1,4 @@ -# Child Process +# Child Process > Stability: 2 - Stable @@ -133,9 +133,10 @@ added: v0.1.90 * `env` {Object} Environment key-value pairs * `encoding` {string} (Default: `'utf8'`) * `shell` {string} Shell to execute the command with - (Default: `'/bin/sh'` on UNIX, `'cmd.exe'` on Windows, The shell should - understand the `-c` switch on UNIX or `/d /s /c` on Windows. On Windows, - command line parsing should be compatible with `cmd.exe`.) + (Default: `'/bin/sh'` on UNIX, `'process.env.ComSpec'` on Windows. If + `'process.env.ComSpec'` is unavailable, uses `'cmd.exe'` on Windows instead. + The shell should understand the `-c` switch on UNIX or `/d /s /c` on Windows. + On Windows, command line parsing should be compatible with `cmd.exe`.) * `timeout` {number} (Default: `0`) * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or stderr. (Default: `200*1024`) If exceeded, the child process is terminated. @@ -382,9 +383,10 @@ changes: * `uid` {number} Sets the user identity of the process. (See setuid(2).) * `gid` {number} Sets the group identity of the process. (See setgid(2).) * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses - `'/bin/sh'` on UNIX, and `'cmd.exe'` on Windows. A different shell can be - specified as a string. The shell should understand the `-c` switch on UNIX, - or `/d /s /c` on Windows. Defaults to `false` (no shell). + `'/bin/sh'` on UNIX, and `'process.env.ComSpec'` on Windows. If + `'process.env.ComSpec'` is unavailable, uses `'cmd.exe'` on Windows instead. + A different shell can be specified as a string. The shell should understand + the `-c` switch on UNIX, or `/d /s /c` on Windows. Defaults to `false` (no shell). * Returns: {ChildProcess} The `child_process.spawn()` method spawns a new process using the given @@ -707,9 +709,10 @@ changes: `stdio` is specified * `env` {Object} Environment key-value pairs * `shell` {string} Shell to execute the command with - (Default: `'/bin/sh'` on UNIX, `'cmd.exe'` on Windows, The shell should - understand the `-c` switch on UNIX or `/d /s /c` on Windows. On Windows, - command line parsing should be compatible with `cmd.exe`.) + (Default: `'/bin/sh'` on UNIX, `'process.env.ComSpec'` on Windows. + If `'process.env.ComSpec'` is unavailable, uses `'cmd.exe'` on Windows instead. + The shell should understand the `-c` switch on UNIX or `/d /s /c` on Windows. + On Windows, command line parsing should be compatible with `cmd.exe`.) * `uid` {number} Sets the user identity of the process. (See setuid(2).) * `gid` {number} Sets the group identity of the process. (See setgid(2).) * `timeout` {number} In milliseconds the maximum amount of time the process @@ -775,9 +778,10 @@ changes: * `encoding` {string} The encoding used for all stdio inputs and outputs. (Default: `'buffer'`) * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses - `'/bin/sh'` on UNIX, and `'cmd.exe'` on Windows. A different shell can be - specified as a string. The shell should understand the `-c` switch on UNIX, - or `/d /s /c` on Windows. Defaults to `false` (no shell). + `'/bin/sh'` on UNIX, and `'process.env.ComSpec'` on Windows. If + `'process.env.ComSpec'` is unavailable, uses `'cmd.exe'` on Windows instead. + A different shell can be specified as a string. The shell should understand + the `-c` switch on UNIX, or `/d /s /c` on Windows. Defaults to `false` (no shell). * Returns: {Object} * `pid` {number} Pid of the child process * `output` {Array} Array of results from stdio output From e9089d30566ecff4a98f235de80dd8328c03f806 Mon Sep 17 00:00:00 2001 From: Henry Date: Wed, 12 Jul 2017 15:17:31 -0400 Subject: [PATCH 2/7] doc: fixes default shell in child_process.md Clarifies that 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.spawnSync, and child_process.execSync. Fixes: https://github.com/nodejs/node/issues/14156 --- doc/api/child_process.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 157b35cabe4ba6..ae025a402ca116 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -385,8 +385,8 @@ changes: * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses `'/bin/sh'` on UNIX, and `'process.env.ComSpec'` on Windows. If `'process.env.ComSpec'` is unavailable, uses `'cmd.exe'` on Windows instead. - A different shell can be specified as a string. The shell should understand - the `-c` switch on UNIX, or `/d /s /c` on Windows. Defaults to `false` (no shell). + A different shell can be specified as a string. The shell should understand the + `-c` switch on UNIX, or `/d /s /c` on Windows. Defaults to `false` (no shell). * Returns: {ChildProcess} The `child_process.spawn()` method spawns a new process using the given @@ -780,8 +780,8 @@ changes: * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses `'/bin/sh'` on UNIX, and `'process.env.ComSpec'` on Windows. If `'process.env.ComSpec'` is unavailable, uses `'cmd.exe'` on Windows instead. - A different shell can be specified as a string. The shell should understand - the `-c` switch on UNIX, or `/d /s /c` on Windows. Defaults to `false` (no shell). + A different shell can be specified as a string. The shell should understand the + `-c` switch on UNIX, or `/d /s /c` on Windows. Defaults to `false` (no shell). * Returns: {Object} * `pid` {number} Pid of the child process * `output` {Array} Array of results from stdio output From a6a073ce3561ef657dad3fee23d196537879eb48 Mon Sep 17 00:00:00 2001 From: Henry Date: Wed, 12 Jul 2017 16:22:04 -0400 Subject: [PATCH 3/7] doc: fixes default shell in child_process.md Rewrapped lines over 80 characters according to the Style Guide. --- doc/api/child_process.md | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/doc/api/child_process.md b/doc/api/child_process.md index ae025a402ca116..02c44faef8243e 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -134,9 +134,10 @@ added: v0.1.90 * `encoding` {string} (Default: `'utf8'`) * `shell` {string} Shell to execute the command with (Default: `'/bin/sh'` on UNIX, `'process.env.ComSpec'` on Windows. If - `'process.env.ComSpec'` is unavailable, uses `'cmd.exe'` on Windows instead. - The shell should understand the `-c` switch on UNIX or `/d /s /c` on Windows. - On Windows, command line parsing should be compatible with `cmd.exe`.) + `'process.env.ComSpec'` is unavailable, uses `'cmd.exe'` on Windows + instead. The shell should understand the `-c` switch on UNIX or + `/d /s /c` on Windows. On Windows, command line parsing should be + compatible with `cmd.exe`.) * `timeout` {number} (Default: `0`) * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or stderr. (Default: `200*1024`) If exceeded, the child process is terminated. @@ -384,9 +385,10 @@ changes: * `gid` {number} Sets the group identity of the process. (See setgid(2).) * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses `'/bin/sh'` on UNIX, and `'process.env.ComSpec'` on Windows. If - `'process.env.ComSpec'` is unavailable, uses `'cmd.exe'` on Windows instead. - A different shell can be specified as a string. The shell should understand the - `-c` switch on UNIX, or `/d /s /c` on Windows. Defaults to `false` (no shell). + `'process.env.ComSpec'` is unavailable, uses `'cmd.exe'` on Windows + instead. A different shell can be specified as a string. The shell should + understand the `-c` switch on UNIX, or `/d /s /c` on Windows. Defaults + to `false` (no shell). * Returns: {ChildProcess} The `child_process.spawn()` method spawns a new process using the given @@ -710,9 +712,10 @@ changes: * `env` {Object} Environment key-value pairs * `shell` {string} Shell to execute the command with (Default: `'/bin/sh'` on UNIX, `'process.env.ComSpec'` on Windows. - If `'process.env.ComSpec'` is unavailable, uses `'cmd.exe'` on Windows instead. - The shell should understand the `-c` switch on UNIX or `/d /s /c` on Windows. - On Windows, command line parsing should be compatible with `cmd.exe`.) + If `'process.env.ComSpec'` is unavailable, uses `'cmd.exe'` on Windows + instead. The shell should understand the `-c` switch on UNIX or + `/d /s /c` on Windows. On Windows, command line parsing should be + compatible with `cmd.exe`.) * `uid` {number} Sets the user identity of the process. (See setuid(2).) * `gid` {number} Sets the group identity of the process. (See setgid(2).) * `timeout` {number} In milliseconds the maximum amount of time the process @@ -779,9 +782,10 @@ changes: (Default: `'buffer'`) * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses `'/bin/sh'` on UNIX, and `'process.env.ComSpec'` on Windows. If - `'process.env.ComSpec'` is unavailable, uses `'cmd.exe'` on Windows instead. - A different shell can be specified as a string. The shell should understand the - `-c` switch on UNIX, or `/d /s /c` on Windows. Defaults to `false` (no shell). + `'process.env.ComSpec'` is unavailable, uses `'cmd.exe'` on Windows + instead. A different shell can be specified as a string. The shell should + understand the `-c` switch on UNIX, or `/d /s /c` on Windows. Defaults + to `false` (no shell). * Returns: {Object} * `pid` {number} Pid of the child process * `output` {Array} Array of results from stdio output From fd92d179444972e60e1cbb54b5b6b76326ac0f29 Mon Sep 17 00:00:00 2001 From: Henry Date: Mon, 17 Jul 2017 13:40:27 -0400 Subject: [PATCH 4/7] doc: fixes default shell in child_process.md Reorganizes `child_process` shell spawning information. Fixes: https://github.com/nodejs/node/issues/14156 --- doc/api/child_process.md | 45 ++++++++++++++++++++++------------------ 1 file changed, 25 insertions(+), 20 deletions(-) mode change 100644 => 100755 doc/api/child_process.md diff --git a/doc/api/child_process.md b/doc/api/child_process.md old mode 100644 new mode 100755 index 02c44faef8243e..81690b56b28cf9 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -133,11 +133,8 @@ added: v0.1.90 * `env` {Object} Environment key-value pairs * `encoding` {string} (Default: `'utf8'`) * `shell` {string} Shell to execute the command with - (Default: `'/bin/sh'` on UNIX, `'process.env.ComSpec'` on Windows. If - `'process.env.ComSpec'` is unavailable, uses `'cmd.exe'` on Windows - instead. The shell should understand the `-c` switch on UNIX or - `/d /s /c` on Windows. On Windows, command line parsing should be - compatible with `cmd.exe`.) + (Default: `'/bin/sh'` on UNIX, `'process.env.ComSpec'` on Windows. See + [Shell Requirements][] and [Default Windows Shell][].) * `timeout` {number} (Default: `0`) * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or stderr. (Default: `200*1024`) If exceeded, the child process is terminated. @@ -384,11 +381,9 @@ changes: * `uid` {number} Sets the user identity of the process. (See setuid(2).) * `gid` {number} Sets the group identity of the process. (See setgid(2).) * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses - `'/bin/sh'` on UNIX, and `'process.env.ComSpec'` on Windows. If - `'process.env.ComSpec'` is unavailable, uses `'cmd.exe'` on Windows - instead. A different shell can be specified as a string. The shell should - understand the `-c` switch on UNIX, or `/d /s /c` on Windows. Defaults - to `false` (no shell). + `'/bin/sh'` on UNIX, and `'process.env.ComSpec'` on Windows. A different + shell can be specified as a string. See [Shell Requirements][] and + [Default Windows Shell][]. Defaults to `false` (no shell). * Returns: {ChildProcess} The `child_process.spawn()` method spawns a new process using the given @@ -711,11 +706,8 @@ changes: `stdio` is specified * `env` {Object} Environment key-value pairs * `shell` {string} Shell to execute the command with - (Default: `'/bin/sh'` on UNIX, `'process.env.ComSpec'` on Windows. - If `'process.env.ComSpec'` is unavailable, uses `'cmd.exe'` on Windows - instead. The shell should understand the `-c` switch on UNIX or - `/d /s /c` on Windows. On Windows, command line parsing should be - compatible with `cmd.exe`.) + (Default: `'/bin/sh'` on UNIX, `'process.env.ComSpec'` on Windows. See + [Shell Requirements][] and [Default Windows Shell][].) * `uid` {number} Sets the user identity of the process. (See setuid(2).) * `gid` {number} Sets the group identity of the process. (See setgid(2).) * `timeout` {number} In milliseconds the maximum amount of time the process @@ -781,11 +773,9 @@ changes: * `encoding` {string} The encoding used for all stdio inputs and outputs. (Default: `'buffer'`) * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses - `'/bin/sh'` on UNIX, and `'process.env.ComSpec'` on Windows. If - `'process.env.ComSpec'` is unavailable, uses `'cmd.exe'` on Windows - instead. A different shell can be specified as a string. The shell should - understand the `-c` switch on UNIX, or `/d /s /c` on Windows. Defaults - to `false` (no shell). + `'/bin/sh'` on UNIX, and `'process.env.ComSpec'` on Windows. See + [Shell Requirements][] and [Default Windows Shell][]. A different shell can + be specified as a string. Defaults to `false` (no shell). * Returns: {Object} * `pid` {number} Pid of the child process * `output` {Array} Array of results from stdio output @@ -1289,6 +1279,19 @@ This impacts output that includes multibyte character encodings such as UTF-8 or UTF-16. For instance, `console.log('中文测试')` will send 13 UTF-8 encoded bytes to `stdout` although there are only 4 characters. +## Shell Requirements + +The shell should understand the `-c` switch on UNIX or `/d /s /c` on Windows. +On Windows, command line parsing should be compatible with `'cmd.exe'`. + +## Default Windows Shell + +Although Microsoft specifies `'process.env.ComSpec'` must contain the path to +`'cmd.exe'` in the root environment, child processes are not always subject to +the same requirement. Thus, in `child_process` functions where a shell can be +spawned, `'cmd.exe'` is used as a fallback if `'process.env.ComSpec'` is +unavailable. + [`'error'`]: #child_process_event_error [`'exit'`]: #child_process_event_exit [`'message'`]: #child_process_event_message @@ -1311,6 +1314,8 @@ to `stdout` although there are only 4 characters. [`child_process.spawn()`]: #child_process_child_process_spawn_command_args_options [`child_process.spawnSync()`]: #child_process_child_process_spawnsync_command_args_options [`maxBuffer` and Unicode]: #child_process_maxbuffer_and_unicode +[Shell Requirements]: #child_process_shell_requirements +[Default Windows Shell]: #child_process_default_windows_shell [`net.Server`]: net.html#net_class_net_server [`net.Socket`]: net.html#net_class_net_socket [`options.detached`]: #child_process_options_detached From 33adbeb3dfae46e1dee3f89ef872ddd0bdcbdf57 Mon Sep 17 00:00:00 2001 From: Henry Date: Mon, 17 Jul 2017 14:17:23 -0400 Subject: [PATCH 5/7] doc: fixes default shell in child_process.md Small formatting fixes for shell spawning information. Fixes: https://github.com/nodejs/node/issues/14156 --- doc/api/child_process.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 81690b56b28cf9..f90ab94876a208 100755 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -773,9 +773,9 @@ changes: * `encoding` {string} The encoding used for all stdio inputs and outputs. (Default: `'buffer'`) * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses - `'/bin/sh'` on UNIX, and `'process.env.ComSpec'` on Windows. See - [Shell Requirements][] and [Default Windows Shell][]. A different shell can - be specified as a string. Defaults to `false` (no shell). + `'/bin/sh'` on UNIX, and `'process.env.ComSpec'` on Windows. A different + shell can be specified as a string. See [Shell Requirements][] and + [Default Windows Shell][]. Defaults to `false` (no shell). * Returns: {Object} * `pid` {number} Pid of the child process * `output` {Array} Array of results from stdio output @@ -1314,8 +1314,6 @@ unavailable. [`child_process.spawn()`]: #child_process_child_process_spawn_command_args_options [`child_process.spawnSync()`]: #child_process_child_process_spawnsync_command_args_options [`maxBuffer` and Unicode]: #child_process_maxbuffer_and_unicode -[Shell Requirements]: #child_process_shell_requirements -[Default Windows Shell]: #child_process_default_windows_shell [`net.Server`]: net.html#net_class_net_server [`net.Socket`]: net.html#net_class_net_socket [`options.detached`]: #child_process_options_detached @@ -1327,4 +1325,6 @@ unavailable. [`process.send()`]: process.html#process_process_send_message_sendhandle_options_callback [`stdio`]: #child_process_options_stdio [`util.promisify()`]: util.html#util_util_promisify_original +[Default Windows Shell]: #child_process_default_windows_shell +[Shell Requirements]: #child_process_shell_requirements [synchronous counterparts]: #child_process_synchronous_process_creation From e4171c3fb567137d9ddd7423595065fa0724127c Mon Sep 17 00:00:00 2001 From: Henry Date: Tue, 18 Jul 2017 11:21:10 -0400 Subject: [PATCH 6/7] doc: fixes default shell in child_process.md Notation changes for `process.env.ComSpec` Fixes: https://github.com/nodejs/node/issues/14156 --- doc/api/child_process.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/api/child_process.md b/doc/api/child_process.md index f90ab94876a208..b1f87ed01ea347 100755 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -133,7 +133,7 @@ added: v0.1.90 * `env` {Object} Environment key-value pairs * `encoding` {string} (Default: `'utf8'`) * `shell` {string} Shell to execute the command with - (Default: `'/bin/sh'` on UNIX, `'process.env.ComSpec'` on Windows. See + (Default: `'/bin/sh'` on UNIX, `process.env.ComSpec` on Windows. See [Shell Requirements][] and [Default Windows Shell][].) * `timeout` {number} (Default: `0`) * `maxBuffer` {number} Largest amount of data in bytes allowed on stdout or @@ -381,7 +381,7 @@ changes: * `uid` {number} Sets the user identity of the process. (See setuid(2).) * `gid` {number} Sets the group identity of the process. (See setgid(2).) * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses - `'/bin/sh'` on UNIX, and `'process.env.ComSpec'` on Windows. A different + `'/bin/sh'` on UNIX, and `process.env.ComSpec` on Windows. A different shell can be specified as a string. See [Shell Requirements][] and [Default Windows Shell][]. Defaults to `false` (no shell). * Returns: {ChildProcess} @@ -706,7 +706,7 @@ changes: `stdio` is specified * `env` {Object} Environment key-value pairs * `shell` {string} Shell to execute the command with - (Default: `'/bin/sh'` on UNIX, `'process.env.ComSpec'` on Windows. See + (Default: `'/bin/sh'` on UNIX, `process.env.ComSpec` on Windows. See [Shell Requirements][] and [Default Windows Shell][].) * `uid` {number} Sets the user identity of the process. (See setuid(2).) * `gid` {number} Sets the group identity of the process. (See setgid(2).) @@ -773,7 +773,7 @@ changes: * `encoding` {string} The encoding used for all stdio inputs and outputs. (Default: `'buffer'`) * `shell` {boolean|string} If `true`, runs `command` inside of a shell. Uses - `'/bin/sh'` on UNIX, and `'process.env.ComSpec'` on Windows. A different + `'/bin/sh'` on UNIX, and `process.env.ComSpec` on Windows. A different shell can be specified as a string. See [Shell Requirements][] and [Default Windows Shell][]. Defaults to `false` (no shell). * Returns: {Object} @@ -1286,10 +1286,10 @@ On Windows, command line parsing should be compatible with `'cmd.exe'`. ## Default Windows Shell -Although Microsoft specifies `'process.env.ComSpec'` must contain the path to +Although Microsoft specifies `%COMSPEC` must contain the path to `'cmd.exe'` in the root environment, child processes are not always subject to the same requirement. Thus, in `child_process` functions where a shell can be -spawned, `'cmd.exe'` is used as a fallback if `'process.env.ComSpec'` is +spawned, `'cmd.exe'` is used as a fallback if `process.env.ComSpec` is unavailable. [`'error'`]: #child_process_event_error From 46a8829043cd78290b5afb2c096d9717ac6f544d Mon Sep 17 00:00:00 2001 From: Henry Date: Tue, 18 Jul 2017 13:43:45 -0400 Subject: [PATCH 7/7] doc: fixes default shell in child_process.md Wrapped `%COMSPEC%` with percent signs. Fixes: https://github.com/nodejs/node/issues/14156 --- doc/api/child_process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/child_process.md b/doc/api/child_process.md index b1f87ed01ea347..93dbddbed75d19 100755 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -1286,7 +1286,7 @@ On Windows, command line parsing should be compatible with `'cmd.exe'`. ## Default Windows Shell -Although Microsoft specifies `%COMSPEC` must contain the path to +Although Microsoft specifies `%COMSPEC%` must contain the path to `'cmd.exe'` in the root environment, child processes are not always subject to the same requirement. Thus, in `child_process` functions where a shell can be spawned, `'cmd.exe'` is used as a fallback if `process.env.ComSpec` is