Skip to content

Commit

Permalink
doc: revise introductory child_process text
Browse files Browse the repository at this point in the history
This consolidates information about Windows environment variables and
has a few other smaller improvements (punctuation, present tense, etc.).

PR-URL: #35344
Backport-PR-URL: #35420
Reviewed-By: Daijiro Wachi <daijiro.wachi@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
  • Loading branch information
Trott authored and danielleadams committed Oct 6, 2020
1 parent 3f62f99 commit a995dd7
Showing 1 changed file with 15 additions and 12 deletions.
27 changes: 15 additions & 12 deletions doc/api/child_process.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
<!-- source_link=lib/child_process.js -->

The `child_process` module provides the ability to spawn child processes in
The `child_process` module provides the ability to spawn subprocesses in
a manner that is similar, but not identical, to popen(3). This capability
is primarily provided by the [`child_process.spawn()`][] function:

Expand All @@ -28,20 +28,23 @@ ls.on('close', (code) => {
```

By default, pipes for `stdin`, `stdout`, and `stderr` are established between
the parent Node.js process and the spawned child. These pipes have
limited (and platform-specific) capacity. If the child process writes to
stdout in excess of that limit without the output being captured, the child
process will block waiting for the pipe buffer to accept more data. This is
the parent Node.js process and the spawned subprocess. These pipes have
limited (and platform-specific) capacity. If the subprocess writes to
stdout in excess of that limit without the output being captured, the
subprocess blocks waiting for the pipe buffer to accept more data. This is
identical to the behavior of pipes in the shell. Use the `{ stdio: 'ignore' }`
option if the output will not be consumed.

The command lookup will be performed using `options.env.PATH` environment
variable if passed in `options` object, otherwise `process.env.PATH` will be
used. To account for the fact that Windows environment variables are
case-insensitive Node.js will lexicographically sort all `env` keys and choose
the first one case-insensitively matching `PATH` to perform command lookup.
This may lead to issues on Windows when passing objects to `env` option that
have multiple variants of `PATH` variable.
The command lookup is performed using the `options.env.PATH` environment
variable if it is in the `options` object. Otherwise, `process.env.PATH` is
used.

On Windows, environment variables are case-insensitive. Node.js
lexicographically sorts the `env` keys and uses the first one that
case-insensitively matches. Only first (in lexicographic order) entry will be
passed to the subprocess. This might lead to issues on Windows when passing
objects to the `env` option that have multiple variants of the same key, such as
`PATH` and `Path`.

The [`child_process.spawn()`][] method spawns the child process asynchronously,
without blocking the Node.js event loop. The [`child_process.spawnSync()`][]
Expand Down

0 comments on commit a995dd7

Please sign in to comment.