From 0699f5bfb40ca365f46eab775c7e6fc8a19d3eee Mon Sep 17 00:00:00 2001 From: Bert Belder Date: Mon, 4 Jun 2012 14:04:15 +0200 Subject: [PATCH] Improve child process stdio documentation --- doc/api/child_process.markdown | 41 +++++++++++++++++++++------------- 1 file changed, 25 insertions(+), 16 deletions(-) diff --git a/doc/api/child_process.markdown b/doc/api/child_process.markdown index e9aab649f4..72597a41ca 100644 --- a/doc/api/child_process.markdown +++ b/doc/api/child_process.markdown @@ -340,22 +340,31 @@ API. The 'stdio' option to `child_process.spawn()` is an array where each index corresponds to a fd in the child. The value is one of the following: -1. `null`, `undefined` - Use default value. For 0,1,2 stdios this is the same - as `'pipe'`. For any higher value, `'ignore'` -2. `'ignore'` - Open the fd in the child, but do not expose it to the parent -3. `'pipe'` - Open the fd and expose as a `Stream` object to parent. -4. `'ipc'` - Create IPC channel for passing messages/file descriptors between - parent and child. - - Note: A ChildProcess may have at most *one* IPC stdio file descriptor. - Setting this option enables the ChildProcess.send() method. If the - child writes JSON messages to this file descriptor, then this will trigger - ChildProcess.on('message'). If the child is a Node.js program, then - the presence of an IPC channel will enable process.send() and - process.on('message') -5. positive integer - Share corresponding fd with child -6. Any TTY, TCP, File stream (or any object with `fd` property) - Share - corresponding stream with child. +1. `'pipe'` - Create a pipe between the child process and the parent process. + The parent end of the pipe is exposed to the parent as a property on the + child_process object as `ChildProcess.stdio[fd]`. Pipes created for + fds 0 - 2 are also available as ChildProcess.stdin, ChildProcess.stdout + and ChildProcess.stderr, respectively. +2. `'ipc'` - Create an IPC channel for passing messages/file descriptors + between parent and child. A ChildProcess may have at most *one* IPC stdio + file descriptor. Setting this option enables the ChildProcess.send() method. + If the child writes JSON messages to this file descriptor, then this will + trigger ChildProcess.on('message'). If the child is a Node.js program, then + the presence of an IPC channel will enable process.send() and + process.on('message'). +3. `'ignore'` - Do not set this file descriptor in the child. Note that Node + will always open fd 0 - 2 for the processes it spawns. When any of these is + ignored node will open `/dev/null` and attach it to the child's fd. +4. `Stream` object - Share a readable or writable stream that refers to a tty, + file, socket, or a pipe with the child process. The stream's underlying + file descriptor is duplicated in the child process to the fd that + corresponds to the index in the `stdio` array. +5. Positive integer - The integer value is interpreted as a file descriptor + that is is currently open in the parent process. It is shared with the child + process, similar to how `Stream` objects can be shared. +6. `null`, `undefined` - Use default value. For stdio fds 0, 1 and 2 (in other + words, stdin, stdout, and stderr) a pipe is created. For fd 3 and up, the + default is `'ignore'`. As a shorthand, the `stdio` argument may also be one of the following strings, rather than an array: