doc: update child_process.md

Add an explanation of the risk of exceeding platform pipe
capacity with uncaptured output in child_process.spawn
with stdio of pipe

PR-URL: https://github.com/nodejs/node/pull/19075
Fixes: https://github.com/nodejs/node/issues/4236
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

1 files changed, 10 insertions, 4 deletions

diff --git a/doc/api/child_process.md b/doc/api/child_process.md
index 4f8089ccc7..09e43b2bd4 100644
--- a/doc/api/child_process.md
+++ b/doc/api/child_process.md
@@ -27,10 +27,16 @@ ls.on('close', (code) => {
 ```
 
 By default, pipes for `stdin`, `stdout`, and `stderr` are established between
-the parent Node.js process and the spawned child. It is possible to stream data
-through these pipes in a non-blocking way. *Note, however, that some programs
-use line-buffered I/O internally. While that does not affect Node.js, it can
-mean that data sent to the child process may not be immediately consumed.*
+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
+identical to the behavior of pipes in the shell. Use the `{ stdio: 'ignore' }`
+option if the output will not be consumed.
+It is possible to stream data through these pipes in a non-blocking way. Note,
+however, that some programs use line-buffered I/O internally. While that does
+not affect Node.js, it can mean that data sent to the child process may not be
+immediately consumed.
 
 The [`child_process.spawn()`][] method spawns the child process asynchronously,
 without blocking the Node.js event loop. The [`child_process.spawnSync()`][]