Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: fixes default shell in child_process.md #14203

Closed
wants to merge 7 commits into from
Closed

doc: fixes default shell in child_process.md #14203

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
1a07c2a
doc: fixes default shell in child_process.md
henryzxu Jul 12, 2017
e9089d3
doc: fixes default shell in child_process.md
henryzxu Jul 12, 2017
a6a073c
doc: fixes default shell in child_process.md
henryzxu Jul 12, 2017
fd92d17
doc: fixes default shell in child_process.md
henryzxu Jul 17, 2017
33adbeb
doc: fixes default shell in child_process.md
henryzxu Jul 17, 2017
e4171c3
doc: fixes default shell in child_process.md
henryzxu Jul 18, 2017
46a8829
doc: fixes default shell in child_process.md
henryzxu Jul 18, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 25 additions & 20 deletions doc/api/child_process.md
100644 → 100755
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

process.env.ComSpec is a property (variable), not a string literal, so it should not be quoted.

[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.
Expand Down Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here.

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
Expand Down Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here.

[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
Expand Down Expand Up @@ -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).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any reason why you swapped the last two sentences compared to spawn?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh oops! That was an accident. It should be fixed in the latest commit.

* Returns: {Object}
* `pid` {number} Pid of the child process
* `output` {Array} Array of results from stdio output
Expand Down Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Microsoft does not specify anything regarding process.env.ComSpec. This is just node's representation of the process environment. Actually, Microsoft only holds that assertion for the environment variable as stored in the registry. The technical background will be too complex for our docs and is not really relevant, but I would prefer %COMSPEC% instead of process.env.ComSpec here (and only here).

`'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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See above.

unavailable.

[`'error'`]: #child_process_event_error
[`'exit'`]: #child_process_event_exit
[`'message'`]: #child_process_event_message
Expand All @@ -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
Copy link
Contributor

@vsemozhetbyt vsemozhetbyt Jul 17, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This and the next references are out of ASCII sort order (should be placed before the last reference).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the heads up! They should be in the correct order in the latest commit.

[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
Expand Down