From d1c45e258c124439c5376c74c8b857556871cb3e Mon Sep 17 00:00:00 2001 From: Ari Leo Frankel Date: Thu, 1 Mar 2018 13:56:03 -0600 Subject: [PATCH] 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 Reviewed-By: Benjamin Gruenbaum Reviewed-By: Colin Ihrig Reviewed-By: Gireesh Punathil Reviewed-By: James M Snell --- doc/api/child_process.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 07d3b9ac0e8773..3a0398a856c64f 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()`][]