docs: add race warning to `child_process.kill()`

1 files changed, 19 insertions, 2 deletions

diff --git a/doc/api/child_processes.markdown b/doc/api/child_processes.markdown
index a8cc8780eec..dca4bdc3d07 100644
--- a/doc/api/child_processes.markdown
+++ b/doc/api/child_processes.markdown
@@ -234,7 +234,24 @@ be sent `'SIGTERM'`. See `signal(7)` for a list of available signals.
     // send SIGHUP to process
     grep.kill('SIGHUP');
 
-Note that while the function is called `kill`, the signal delivered to the child
-process may not actually kill it.  `kill` really just sends a signal to a process.
+Note that while the function is called `kill`, the signal delivered to the
+child process may not actually kill it.  `kill` really just sends a signal
+to a process.
+
+Please note that the example contains a potential race condition on
+(at least) UNIX systems. Here is why:
+
+The canonical approach to starting a child process is to call `fork()` to
+create a copy of the current process, followed by a call to `execve()` to
+replace the copy with the actual child process. This runs in tandem with
+the parent process.
+
+The time between `fork()` and `execve()` is short but it's not zero.
+The child process may not have actually started when `spawn()` returns.
+Thus, if you send a signal immediately after the call to `spawn()`, it may
+end up being delivered to the copy of the current process and *not* the
+actual child process.
+
+The resulting behavior is undefined. It likely won't do what you want it to.
 
 See `kill(2)`