doc: child_process: document 'error' event

Fixes #5130.

diff --git a/doc/api/child_process.markdown b/doc/api/child_process.markdown
index b652e88..dade323 100644 (file)
--- a/doc/api/child_process.markdown
+++ b/doc/api/child_process.markdown
@@ -26,6 +26,19 @@ which can be piped to and from.
 The ChildProcess class is not intended to be used directly.  Use the
 `spawn()` or `fork()` methods to create a Child Process instance.
 
+### Event:  'error'
+
+* `err` {Error Object} the error.
+
+Emitted when:
+
+1. The process could not be spawned, or
+2. The process could not be killed, or
+3. Sending a message to the child process failed for whatever reason.
+
+See also [`ChildProcess#kill()`](#child_process_child_kill_signal) and
+[`ChildProcess#send()`](#child_process_child_send_message_sendhandle).
+
 ### Event:  'exit'
 
 * `code` {Number} the exit code, if it exited normally.
@@ -125,8 +138,15 @@ 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.
+May emit an `'error'` event when the signal cannot be delivered. Sending a
+signal to a child process that has already exited is not an error but may
+have unforeseen consequences: if the PID (the process ID) has been reassigned
+to another process, the signal will be delivered to that process instead.
+What happens next is anyone's guess.
+
+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.
 
 See `kill(2)`
 
@@ -172,6 +192,9 @@ The `sendHandle` option to `child.send()` is for sending a TCP server or
 socket object to another process. The child will receive the object as its
 second argument to the `message` event.
 
+Emits an `'error'` event if the message cannot be sent, for example because
+the child process has already exited.
+
 #### Example: sending server object
 
 Here is an example of sending a server: