child_process: js bits for spawnSync/execSyncexecSync-wip

This implements the user-facing APIs that lets one run a child process
and block until it exits.

Some logic that these new functions had in common with the existing
spawn/exec/execFile implementation was refactored into separate
functions, so it could be shared.

Docs and tests are included.

1 files changed, 69 insertions, 0 deletions

diff --git a/doc/api/child_process.markdown b/doc/api/child_process.markdown
index 1e0270f2b..8bea6c6e5 100644
--- a/doc/api/child_process.markdown
+++ b/doc/api/child_process.markdown
@@ -589,4 +589,73 @@ done with care and by default will talk over the fd represented an
 environmental variable `NODE_CHANNEL_FD` on the child process. The input and
 output on this fd is expected to be line delimited JSON objects.
 
+## child_process.spawnSync(command, [args], [options])
+
+* `command` {String} The command to run
+* `args` {Array} List of string arguments
+* `options` {Object}
+  * `cwd` {String} Current working directory of the child process
+  * `input` {String|Buffer} The value which will be passed as stdin to the spawned process
+    - supplying this value will override `stdio[0]`
+  * `stdio` {Array} Child's stdio configuration.
+  * `env` {Object} Environment key-value pairs
+  * `uid` {Number} Sets the user identity of the process. (See setuid(2).)
+  * `gid` {Number} Sets the group identity of the process. (See setgid(2).)
+  * `timeout` {Number} In milliseconds the maximum amount of time the process is allowed to run. (Default: undefined)
+  * `killSignal` {String} The signal value to be used when the spawned process will be killed. (Default: 'SIGTERM')
+  * `maxBuffer` {Number}
+  * `encoding` {String} The encoding used for all stdio inputs and outputs. (Default: 'buffer')
+* return: {Object}
+  * `pid` {Number} Pid of the child process
+  * `output` {Array} Array of results from stdio output
+  * `stdout` {Buffer|String} The contents of `output[1]`
+  * `stderr` {Buffer|String} The contents of `output[2]`
+  * `status` {Number} The exit code of the child process
+  * `signal` {String} The signal used to kill the child process
+  * `error` {Error} The error object if the child process failed or timedout
+
+## child_process.execFileSync(command, [args], [options])
+
+* `command` {String} The command to run
+* `args` {Array} List of string arguments
+* `options` {Object}
+  * `cwd` {String} Current working directory of the child process
+  * `input` {String|Buffer} The value which will be passed as stdin to the spawned process
+    - supplying this value will override `stdio[0]`
+  * `stdio` {Array} Child's stdio configuration.
+  * `env` {Object} Environment key-value pairs
+  * `uid` {Number} Sets the user identity of the process. (See setuid(2).)
+  * `gid` {Number} Sets the group identity of the process. (See setgid(2).)
+  * `timeout` {Number} In milliseconds the maximum amount of time the process is allowed to run. (Default: undefined)
+  * `killSignal` {String} The signal value to be used when the spawned process will be killed. (Default: 'SIGTERM')
+  * `maxBuffer` {Number}
+  * `encoding` {String} The encoding used for all stdio inputs and outputs. (Default: 'buffer')
+* return: {Buffer|String} The stdout from the command
+
+If the process times out, or has a non-zero exit code, this method ***will***
+throw.  The `Error` object will contain the entire result from
+[`child_process.spawnSync`](#child_process_child_process_spawnsync_command_args_options)
+
+
+## child_process.execSync(command, [options])
+
+* `command` {String} The command to run
+* `options` {Object}
+  * `cwd` {String} Current working directory of the child process
+  * `input` {String|Buffer} The value which will be passed as stdin to the spawned process
+    - supplying this value will override `stdio[0]`
+  * `stdio` {Array} Child's stdio configuration.
+  * `env` {Object} Environment key-value pairs
+  * `uid` {Number} Sets the user identity of the process. (See setuid(2).)
+  * `gid` {Number} Sets the group identity of the process. (See setgid(2).)
+  * `timeout` {Number} In milliseconds the maximum amount of time the process is allowed to run. (Default: undefined)
+  * `killSignal` {String} The signal value to be used when the spawned process will be killed. (Default: 'SIGTERM')
+  * `maxBuffer` {Number}
+  * `encoding` {String} The encoding used for all stdio inputs and outputs. (Default: 'buffer')
+* return: {Buffer|String} The stdout from the command
+
+If the process times out, or has a non-zero exit code, this method ***will***
+throw.  The `Error` object will contain the entire result from
+[`child_process.spawnSync`](#child_process_child_process_spawnsync_command_args_options)
+
 [EventEmitter]: events.html#events_class_events_eventemitter