Commit a995dd7
doc: revise introductory child_process text
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>1 parent 3f62f99 commit a995dd7
1 file changed
Lines changed: 15 additions & 12 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -6,7 +6,7 @@ | |||
| 6 | 6 | ||
| 7 | 7 | <!-- source_link=lib/child_process.js --> | |
| 8 | 8 | ||
| 9 | - The `child_process` module provides the ability to spawn child processes in | ||
| 9 | + The `child_process` module provides the ability to spawn subprocesses in | ||
| 10 | 10 | a manner that is similar, but not identical, to popen(3). This capability | |
| 11 | 11 | is primarily provided by the [`child_process.spawn()`][] function: | |
| 12 | 12 | ||
@@ -28,20 +28,23 @@ ls.on('close', (code) => { | |||
| 28 | 28 | ``` | |
| 29 | 29 | ||
| 30 | 30 | By default, pipes for `stdin`, `stdout`, and `stderr` are established between | |
| 31 | - the parent Node.js process and the spawned child. These pipes have | ||
| 32 | - limited (and platform-specific) capacity. If the child process writes to | ||
| 33 | - stdout in excess of that limit without the output being captured, the child | ||
| 34 | - process will block waiting for the pipe buffer to accept more data. This is | ||
| 31 | + the parent Node.js process and the spawned subprocess. These pipes have | ||
| 32 | + limited (and platform-specific) capacity. If the subprocess writes to | ||
| 33 | + stdout in excess of that limit without the output being captured, the | ||
| 34 | + subprocess blocks waiting for the pipe buffer to accept more data. This is | ||
| 35 | 35 | identical to the behavior of pipes in the shell. Use the `{ stdio: 'ignore' }` | |
| 36 | 36 | option if the output will not be consumed. | |
| 37 | 37 | ||
| 38 | - The command lookup will be performed using `options.env.PATH` environment | ||
| 39 | - variable if passed in `options` object, otherwise `process.env.PATH` will be | ||
| 40 | - used. To account for the fact that Windows environment variables are | ||
| 41 | - case-insensitive Node.js will lexicographically sort all `env` keys and choose | ||
| 42 | - the first one case-insensitively matching `PATH` to perform command lookup. | ||
| 43 | - This may lead to issues on Windows when passing objects to `env` option that | ||
| 44 | - have multiple variants of `PATH` variable. | ||
| 38 | + The command lookup is performed using the `options.env.PATH` environment | ||
| 39 | + variable if it is in the `options` object. Otherwise, `process.env.PATH` is | ||
| 40 | + used. | ||
| 41 | + | ||
| 42 | + On Windows, environment variables are case-insensitive. Node.js | ||
| 43 | + lexicographically sorts the `env` keys and uses the first one that | ||
| 44 | + case-insensitively matches. Only first (in lexicographic order) entry will be | ||
| 45 | + passed to the subprocess. This might lead to issues on Windows when passing | ||
| 46 | + objects to the `env` option that have multiple variants of the same key, such as | ||
| 47 | + `PATH` and `Path`. | ||
| 45 | 48 | ||
| 46 | 49 | The [`child_process.spawn()`][] method spawns the child process asynchronously, | |
| 47 | 50 | without blocking the Node.js event loop. The [`child_process.spawnSync()`][] | |
0 commit comments