doc: describe child.kill() pitfalls on linux

eljefedelrodeodeljefe · Myles Borins · commit 5e6915f3740f · 2016-04-20T16:24:21.000-07:00
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: #2098 Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Closes: #2098
diff --git 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
+[`JSON.stringify()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
