diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 34ee82e14410a0..c180176353d4a4 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -6,7 +6,7 @@ -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: @@ -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()`][]