doc: describe child.kill() pitfalls on linux

This commit refines the documentation around child.kill(), where kill
attempts against shells will lead to unexpected results. Namely, on
linux the child process of a child process will not terminate, when
its parent gets terminated. This is different across the the
platforms.

PR-URL: https://github.com/nodejs/node/issues/2098
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Closes: https://github.com/nodejs/node/issues/2098

1 files changed, 24 insertions, 2 deletions

diff --git a/doc/api/child_process.markdown b/doc/api/child_process.markdown
index aaaa002fb4..cd325a8124 100644
--- a/doc/api/child_process.markdown
+++ b/doc/api/child_process.markdown
@@ -759,7 +759,29 @@ delivered to that process instead which can have unexpected results.
 Note that while the function is called `kill`, the signal delivered to the
 child process may not actually terminate the process.
 
-See `kill(2)`
+See `kill(2)` for reference.
+
+Also note: on Linux, child processes of child processes will not be terminated
+when attempting to kill their parent. This is likely to happen when running a
+new process in a shell or with use of the `shell` option of `ChildProcess`, such
+as in this example:
+
+```js
+'use strict';
+const spawn = require('child_process').spawn;
+
+let child = spawn('sh', ['-c',
+  `node -e "setInterval(() => {
+      console.log(process.pid + 'is alive')
+    }, 500);"`
+  ], {
+    stdio: ['inherit', 'inherit', 'inherit']
+  });
+
+setTimeout(() => {
+  child.kill(); // does not terminate the node process in the shell
+}, 2000);
+```
 
 ### child.pid
 
@@ -1025,4 +1047,4 @@ to the same value.
 [`options.stdio`]: #child_process_options_stdio
 [`stdio`]: #child_process_options_stdio
 [synchronous counterparts]: #child_process_synchronous_process_creation
-[`JSON.stringify()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
\ No newline at end of file
+[`JSON.stringify()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify