posix-spawn 0.3.0

data/ext/extconf.rb

@@ -0,0 +1,6 @@
+require 'mkmf'
+
+# warnings save lives
+$CFLAGS << " -Wall "
+
+create_makefile('posix_spawn_ext')

data/ext/posix-spawn.c

@@ -0,0 +1,406 @@
+/* we want GNU extensions like POSIX_SPAWN_USEVFORK */
+#ifndef _GNU_SOURCE
+#define _GNU_SOURCE
+#endif
+
+#include <errno.h>
+#include <fcntl.h>
+#include <spawn.h>
+#include <stdio.h>
+#include <string.h>
+#include <sys/stat.h>
+#include <unistd.h>
+#include <ruby.h>
+
+#ifdef RUBY_VM
+#include <ruby/st.h>
+extern void rb_enable_interrupt(void);
+extern void rb_disable_interrupt(void);
+#else
+#include <node.h>
+#include <st.h>
+#define rb_enable_interrupt()
+#define rb_disable_interrupt()
+#endif
+
+#ifndef RARRAY_LEN
+#define RARRAY_LEN(ary) RARRAY(ary)->len
+#endif
+#ifndef RARRAY_PTR
+#define RARRAY_PTR(ary) RARRAY(ary)->ptr
+#endif
+#ifndef RHASH_SIZE
+#define RHASH_SIZE(hash) RHASH(hash)->tbl->num_entries
+#endif
+
+#ifdef __APPLE__
+#include <crt_externs.h>
+#define environ (*_NSGetEnviron())
+#else
+extern char **environ;
+#endif
+
+static VALUE rb_mPOSIX;
+static VALUE rb_mPOSIXSpawn;
+
+/* Determine the fd number for a Ruby object VALUE.
+ *
+ * obj - This can be any valid Ruby object, but only the following return
+ *       an actual fd number:
+ *         - The symbols :in, :out, or :err for fds 0, 1, or 2.
+ *         - An IO object. (IO#fileno is returned)
+ *         - A Fixnum.
+ *
+ * Returns the fd number >= 0 if one could be established, or -1 if the object
+ * does not map to an fd.
+ */
+static int
+posixspawn_obj_to_fd(VALUE obj)
+{
+	int fd = -1;
+	switch (TYPE(obj)) {
+		case T_FIXNUM:
+			/* Fixnum fd number */
+			fd = FIX2INT(obj);
+			break;
+
+		case T_SYMBOL:
+			/* (:in|:out|:err) */
+			if      (SYM2ID(obj) == rb_intern("in"))   fd = 0;
+			else if (SYM2ID(obj) == rb_intern("out"))  fd = 1;
+			else if (SYM2ID(obj) == rb_intern("err"))  fd = 2;
+			break;
+
+		case T_FILE:
+			/* IO object */
+			fd = FIX2INT(rb_funcall(obj, rb_intern("fileno"), 0));
+			break;
+
+		case T_OBJECT:
+			/* some other object */
+			if (rb_respond_to(obj, rb_intern("to_io"))) {
+				obj = rb_funcall(obj, rb_intern("to_io"), 0);
+				fd = FIX2INT(rb_funcall(obj, rb_intern("fileno"), 0));
+			}
+			break;
+	}
+	return fd;
+}
+
+/*
+ * Hash iterator that sets up the posix_spawn_file_actions_t with addclose
+ * operations. Only hash pairs whose value is :close are processed. Keys may
+ * be the :in, :out, :err, an IO object, or a Fixnum fd number.
+ *
+ * Returns ST_DELETE when an addclose operation was added; ST_CONTINUE when
+ * no operation was performed.
+ */
+static int
+posixspawn_file_actions_addclose(VALUE key, VALUE val, posix_spawn_file_actions_t *fops)
+{
+	int fd;
+
+	/* we only care about { (IO|FD|:in|:out|:err) => :close } */
+	if (TYPE(val) != T_SYMBOL || SYM2ID(val) != rb_intern("close"))
+		return ST_CONTINUE;
+
+	fd  = posixspawn_obj_to_fd(key);
+	if (fd >= 0) {
+		posix_spawn_file_actions_addclose(fops, fd);
+		return ST_DELETE;
+	} else {
+		return ST_CONTINUE;
+	}
+}
+
+/*
+ * Hash iterator that sets up the posix_spawn_file_actions_t with adddup2 +
+ * close operations for all redirects. Only hash pairs whose key and value
+ * represent fd numbers are processed.
+ *
+ * Returns ST_DELETE when an adddup2 operation was added; ST_CONTINUE when
+ * no operation was performed.
+ */
+static int
+posixspawn_file_actions_adddup2(VALUE key, VALUE val, posix_spawn_file_actions_t *fops)
+{
+	int fd, newfd;
+
+	newfd = posixspawn_obj_to_fd(key);
+	if (newfd < 0)
+		return ST_CONTINUE;
+
+	fd = posixspawn_obj_to_fd(val);
+	if (fd < 0)
+		return ST_CONTINUE;
+
+	posix_spawn_file_actions_adddup2(fops, fd, newfd);
+	return ST_DELETE;
+}
+
+/*
+ * Hash iterator that sets up the posix_spawn_file_actions_t with adddup2 +
+ * clone operations for all file redirects. Only hash pairs whose key is an
+ * fd number and value is a valid three-tuple [file, flags, mode] are
+ * processed.
+ *
+ * Returns ST_DELETE when an adddup2 operation was added; ST_CONTINUE when
+ * no operation was performed.
+ */
+static int
+posixspawn_file_actions_addopen(VALUE key, VALUE val, posix_spawn_file_actions_t *fops)
+{
+	int fd;
+	char *path;
+	int oflag;
+	mode_t mode;
+
+	fd = posixspawn_obj_to_fd(key);
+	if (fd < 0)
+		return ST_CONTINUE;
+
+	if (TYPE(val) != T_ARRAY || RARRAY_LEN(val) != 3)
+		return ST_CONTINUE;
+
+	path = StringValuePtr(RARRAY_PTR(val)[0]);
+	oflag = FIX2INT(RARRAY_PTR(val)[1]);
+	mode = FIX2INT(RARRAY_PTR(val)[2]);
+
+	posix_spawn_file_actions_addopen(fops, fd, path, oflag, mode);
+	return ST_DELETE;
+}
+
+/*
+ * Main entry point for iterating over the options hash to perform file actions.
+ * This function dispatches to the addclose and adddup2 functions, stopping once
+ * an operation was added.
+ *
+ * Returns ST_DELETE if one of the handlers performed an operation; ST_CONTINUE
+ * if not.
+ */
+static int
+posixspawn_file_actions_operations_iter(VALUE key, VALUE val, posix_spawn_file_actions_t *fops)
+{
+	int act;
+
+	act = posixspawn_file_actions_addclose(key, val, fops);
+	if (act != ST_CONTINUE) return act;
+
+	act = posixspawn_file_actions_adddup2(key, val, fops);
+	if (act != ST_CONTINUE) return act;
+
+	act = posixspawn_file_actions_addopen(key, val, fops);
+	if (act != ST_CONTINUE) return act;
+
+	return ST_CONTINUE;
+}
+
+/*
+ * Initialize the posix_spawn_file_actions_t structure and add operations from
+ * the options hash. Keys in the options Hash that are processed by handlers are
+ * removed.
+ *
+ * Returns nothing.
+ */
+static void
+posixspawn_file_actions_init(posix_spawn_file_actions_t *fops, VALUE options)
+{
+	posix_spawn_file_actions_init(fops);
+	rb_hash_foreach(options, posixspawn_file_actions_operations_iter, (VALUE)fops);
+}
+
+static int
+each_env_check_i(VALUE key, VALUE val, VALUE arg)
+{
+	StringValuePtr(key);
+	if (!NIL_P(val)) StringValuePtr(val);
+	return ST_CONTINUE;
+}
+
+static int
+each_env_i(VALUE key, VALUE val, VALUE arg)
+{
+	char *name = StringValuePtr(key);
+	size_t len = strlen(name);
+
+	/*
+	 * Delete any existing values for this variable before inserting the new value.
+	 * This implementation was copied from glibc's unsetenv().
+	 */
+	char **ep = (char **)arg;
+	while (*ep != NULL)
+		if (!strncmp (*ep, name, len) && (*ep)[len] == '=')
+		{
+			/* Found it.  Remove this pointer by moving later ones back.  */
+			char **dp = ep;
+
+			do
+				dp[0] = dp[1];
+			while (*dp++);
+			/* Continue the loop in case NAME appears again.  */
+		}
+		else
+			++ep;
+
+	/*
+	 * Insert the new value if we have one. We can assume there is space
+	 * at the end of the list, since ep was preallocated to be big enough
+	 * for the new entries.
+	 */
+	if (RTEST(val)) {
+		char **ep = (char **)arg;
+		char *cval = StringValuePtr(val);
+
+		size_t cval_len = strlen(cval);
+		size_t ep_len = len + 1 + cval_len + 1; /* +2 for null terminator and '=' separator */
+
+		/* find the last entry */
+		while (*ep != NULL) ++ep;
+		*ep = malloc(ep_len);
+
+		strncpy(*ep, name, len);
+		(*ep)[len] = '=';
+		strncpy(*ep + len + 1, cval, cval_len);
+		(*ep)[ep_len-1] = 0;
+	}
+
+	return ST_CONTINUE;
+}
+
+/*
+ * POSIX::Spawn#_pspawn(env, argv, options)
+ *
+ * env     - Hash of the new environment.
+ * argv    - The [[cmdname, argv0], argv1, ...] exec array.
+ * options - The options hash with fd redirect and close operations.
+ *
+ * Returns the pid of the newly spawned process.
+ */
+static VALUE
+rb_posixspawn_pspawn(VALUE self, VALUE env, VALUE argv, VALUE options)
+{
+	int i, ret;
+	char **envp = NULL;
+	VALUE dirname;
+	VALUE cmdname;
+	VALUE unsetenv_others_p = Qfalse;
+	char *file;
+	char *cwd = NULL;
+	pid_t pid;
+	posix_spawn_file_actions_t fops;
+	posix_spawnattr_t attr;
+
+	/* argv is a [[cmdname, argv0], argv1, argvN, ...] array. */
+	if (TYPE(argv) != T_ARRAY ||
+	    TYPE(RARRAY_PTR(argv)[0]) != T_ARRAY ||
+	    RARRAY_LEN(RARRAY_PTR(argv)[0]) != 2)
+		rb_raise(rb_eArgError, "Invalid command name");
+
+	long argc = RARRAY_LEN(argv);
+	char *cargv[argc + 1];
+
+	cmdname = RARRAY_PTR(argv)[0];
+	file = StringValuePtr(RARRAY_PTR(cmdname)[0]);
+
+	cargv[0] = StringValuePtr(RARRAY_PTR(cmdname)[1]);
+	for (i = 1; i < argc; i++)
+		cargv[i] = StringValuePtr(RARRAY_PTR(argv)[i]);
+	cargv[argc] = NULL;
+
+	if (TYPE(options) == T_HASH) {
+		unsetenv_others_p = rb_hash_delete(options, ID2SYM(rb_intern("unsetenv_others")));
+	}
+
+	if (RTEST(env)) {
+		/*
+		 * Make sure env is a hash, and all keys and values are strings.
+		 * We do this before allocating space for the new environment to
+		 * prevent a leak when raising an exception after the calloc() below.
+		 */
+		Check_Type(env, T_HASH);
+		rb_hash_foreach(env, each_env_check_i, 0);
+
+		if (RHASH_SIZE(env) > 0) {
+			int size = 0;
+
+			char **curr = environ;
+			if (curr) {
+				while (*curr != NULL) ++curr, ++size;
+			}
+
+			if (unsetenv_others_p == Qtrue) {
+				/*
+				 * ignore the parent's environment by pretending it had
+				 * no entries. the loop below will do nothing.
+				 */
+				size = 0;
+			}
+
+			char **new_env = calloc(size+RHASH_SIZE(env)+1, sizeof(char*));
+			for (i = 0; i < size; i++) {
+				new_env[i] = strdup(environ[i]);
+			}
+			envp = new_env;
+
+			rb_hash_foreach(env, each_env_i, (VALUE)envp);
+		}
+	}
+
+	posixspawn_file_actions_init(&fops, options);
+
+	posix_spawnattr_init(&attr);
+#if defined(POSIX_SPAWN_USEVFORK) || defined(__linux__)
+	/* Force USEVFORK on linux. If this is undefined, it's probably because
+	 * you forgot to define _GNU_SOURCE at the top of this file.
+	 */
+	posix_spawnattr_setflags(&attr, POSIX_SPAWN_USEVFORK);
+#endif
+
+	if (RTEST(dirname = rb_hash_delete(options, ID2SYM(rb_intern("chdir"))))) {
+		char *new_cwd = StringValuePtr(dirname);
+		cwd = getcwd(NULL, 0);
+		chdir(new_cwd);
+	}
+
+	if (RHASH_SIZE(options) == 0) {
+		rb_enable_interrupt();
+		ret = posix_spawnp(&pid, file, &fops, &attr, cargv, envp ? envp : environ);
+		rb_disable_interrupt();
+		if (cwd) {
+			chdir(cwd);
+			free(cwd);
+		}
+	} else {
+		ret = -1;
+	}
+
+	posix_spawn_file_actions_destroy(&fops);
+	posix_spawnattr_destroy(&attr);
+	if (envp) {
+		char **ep = envp;
+		while (*ep != NULL) free(*ep), ++ep;
+		free(envp);
+	}
+
+	if (RHASH_SIZE(options) > 0) {
+		rb_raise(rb_eArgError, "Invalid option: %s", RSTRING_PTR(rb_inspect(rb_funcall(options, rb_intern("first"), 0))));
+		return -1;
+	}
+
+	if (ret != 0) {
+		errno = ret;
+		rb_sys_fail("posix_spawnp");
+	}
+
+	return INT2FIX(pid);
+}
+
+void
+Init_posix_spawn_ext()
+{
+	rb_mPOSIX = rb_define_module("POSIX");
+	rb_mPOSIXSpawn = rb_define_module_under(rb_mPOSIX, "Spawn");
+	rb_define_method(rb_mPOSIXSpawn, "_pspawn", rb_posixspawn_pspawn, 3);
+}
+
+/* vim: set noexpandtab sts=0 ts=4 sw=4: */

data/lib/posix-spawn.rb

@@ -0,0 +1 @@
+require "posix/spawn"

data/lib/posix/spawn.rb

@@ -0,0 +1,472 @@
+require 'posix_spawn_ext'
+require 'posix/spawn/version'
+require 'posix/spawn/child'
+
+module POSIX
+  # The POSIX::Spawn module implements a compatible subset of Ruby 1.9's
+  # Process::spawn and related methods using the IEEE Std 1003.1 posix_spawn(2)
+  # system interfaces where available, or a pure Ruby fork/exec based
+  # implementation when not.
+  #
+  # In Ruby 1.9, a versatile new process spawning interface was added
+  # (Process::spawn) as the foundation for enhanced versions of existing
+  # process-related methods like Kernel#system, Kernel#`, and IO#popen. These
+  # methods are backward compatible with their Ruby 1.8 counterparts but
+  # support a large number of new options. The POSIX::Spawn module implements
+  # many of these methods with support for most of Ruby 1.9's features.
+  #
+  # The argument signatures for all of these methods follow a new convention,
+  # making it possible to take advantage of Process::spawn features:
+  #
+  #   spawn([env], command, [argv1, ...], [options])
+  #   system([env], command, [argv1, ...], [options])
+  #   popen([[env], command, [argv1, ...]], mode="r", [options])
+  #
+  # The env, command, and options arguments are described below.
+  #
+  # == Environment
+  #
+  # If a hash is given in the first argument (env), the child process's
+  # environment becomes a merge of the parent's and any modifications
+  # specified in the hash. When a value in env is nil, the variable is
+  # unset in the child:
+  #
+  #     # set FOO as BAR and unset BAZ.
+  #     spawn({"FOO" => "BAR", "BAZ" => nil}, 'echo', 'hello world')
+  #
+  # == Command
+  #
+  # The command and optional argvN string arguments specify the command to
+  # execute and any program arguments. When only command is given and
+  # includes a space character, the command text is executed by the system
+  # shell interpreter, as if by:
+  #
+  #     /bin/sh -c 'command'
+  #
+  # When command does not include a space character, or one or more argvN
+  # arguments are given, the command is executed as if by execve(2) with
+  # each argument forming the new program's argv.
+  #
+  # NOTE: Use of the shell variation is generally discouraged unless you
+  # indeed want to execute a shell program. Specifying an explicitly argv is
+  # typically more secure and less error prone in most cases.
+  #
+  # == Options
+  #
+  # When a hash is given in the last argument (options), it specifies a
+  # current directory and zero or more fd redirects for the child process.
+  #
+  # The :chdir option specifies the current directory:
+  #
+  #     spawn(command, :chdir => "/var/tmp")
+  #
+  # The :in, :out, :err, a Fixnum, an IO object or an Array option specify
+  # fd redirection. For example, stderr can be merged into stdout as follows:
+  #
+  #     spawn(command, :err => :out)
+  #     spawn(command, 2 => 1)
+  #     spawn(command, STDERR => :out)
+  #     spawn(command, STDERR => STDOUT)
+  #
+  # The key is a fd in the newly spawned child process (stderr in this case).
+  # The value is a fd in the parent process (stdout in this case).
+  #
+  # You can also specify a filename for redirection instead of an fd:
+  #
+  #     spawn(command, :in => "/dev/null")   # read mode
+  #     spawn(command, :out => "/dev/null")  # write mode
+  #     spawn(command, :err => "log")        # write mode
+  #     spawn(command, 3 => "/dev/null")     # read mode
+  #
+  # When redirecting to stdout or stderr, the files are opened in write mode;
+  # otherwise, read mode is used.
+  #
+  # It's also possible to control the open flags and file permissions
+  # directly by passing an array value:
+  #
+  #     spawn(command, :in=>["file"])       # read mode assumed
+  #     spawn(command, :in=>["file", "r"])  # explicit read mode
+  #     spawn(command, :out=>["log", "w"])  # explicit write mode, 0644 assumed
+  #     spawn(command, :out=>["log", "w", 0600])
+  #     spawn(command, :out=>["log", File::APPEND | File::CREAT, 0600])
+  #
+  # The array is a [filename, open_mode, perms] tuple. open_mode can be a
+  # string or an integer. When open_mode is omitted or nil, File::RDONLY is
+  # assumed. The perms element should be an integer. When perms is omitted or
+  # nil, 0644 is assumed.
+  #
+  # The :close It's possible to direct an fd be closed in the child process.  This is
+  # important for implementing `popen`-style logic and other forms of IPC between
+  # processes using `IO.pipe`:
+  #
+  #     rd, wr = IO.pipe
+  #     pid = spawn('echo', 'hello world', rd => :close, :stdout => wr)
+  #     wr.close
+  #     output = rd.read
+  #     Process.wait(pid)
+  #
+  # == Spawn Implementation
+  #
+  # The POSIX::Spawn#spawn method uses the best available implementation given
+  # the current platform and Ruby version. In order of preference, they are:
+  #
+  #  1. The posix_spawn based C extension method (pspawn).
+  #  2. Process::spawn when available (Ruby 1.9 only).
+  #  3. A simple pure-Ruby fork/exec based spawn implementation compatible
+  #     with Ruby >= 1.8.7.
+  #
+  module Spawn
+    extend self
+
+    # Spawn a child process with a variety of options using the best
+    # available implementation for the current platform and Ruby version.
+    #
+    # spawn([env], command, [argv1, ...], [options])
+    #
+    # env     - Optional hash specifying the new process's environment.
+    # command - A string command name, or shell program, used to determine the
+    #           program to execute.
+    # argvN   - Zero or more string program arguments (argv).
+    # options - Optional hash of operations to perform before executing the
+    #           new child process.
+    #
+    # Returns the integer pid of the newly spawned process.
+    # Raises any number of Errno:: exceptions on failure.
+    def spawn(*args)
+      if respond_to?(:_pspawn)
+        pspawn(*args)
+      elsif ::Process.respond_to?(:spawn)
+        ::Process::spawn(*args)
+      else
+        fspawn(*args)
+      end
+    end
+
+    # Spawn a child process with a variety of options using the posix_spawn(2)
+    # systems interfaces. Supports the standard spawn interface as described in
+    # the POSIX::Spawn module documentation.
+    #
+    # Raises NotImplementedError when the posix_spawn_ext module could not be
+    # loaded due to lack of platform support.
+    def pspawn(*args)
+      env, argv, options = extract_process_spawn_arguments(*args)
+      raise NotImplementedError unless respond_to?(:_pspawn)
+      _pspawn(env, argv, options)
+    end
+
+    # Spawn a child process with a variety of options using a pure
+    # Ruby fork + exec. Supports the standard spawn interface as described in
+    # the POSIX::Spawn module documentation.
+    def fspawn(*args)
+      env, argv, options = extract_process_spawn_arguments(*args)
+
+      if badopt = options.find{ |key,val| !fd?(key) && ![:chdir,:unsetenv_others].include?(key) }
+        raise ArgumentError, "Invalid option: #{badopt[0].inspect}"
+      elsif !argv.is_a?(Array) || !argv[0].is_a?(Array) || argv[0].size != 2
+        raise ArgumentError, "Invalid command name"
+      end
+
+      fork do
+        begin
+          # handle FD => {FD, :close, [file,mode,perms]} options
+          options.map do |key, val|
+            if fd?(key)
+              key = fd_to_io(key)
+
+              if fd?(val)
+                val = fd_to_io(val)
+                key.reopen(val)
+              elsif val == :close
+                if key.respond_to?(:close_on_exec=)
+                  key.close_on_exec = true
+                else
+                  key.close
+                end
+              elsif val.is_a?(Array)
+                file, mode_string, perms = *val
+                key.reopen(File.open(file, mode_string, perms))
+              end
+            end
+          end
+
+          # setup child environment
+          ENV.replace({}) if options[:unsetenv_others] == true
+          env.each { |k, v| ENV[k] = v }
+
+          # { :chdir => '/' } in options means change into that dir
+          ::Dir.chdir(options[:chdir]) if options[:chdir]
+
+          # do the deed
+          ::Kernel::exec(*argv)
+        ensure
+          exit!(127)
+        end
+      end
+    end
+
+    # Executes a command and waits for it to complete. The command's exit
+    # status is available as $?. Supports the standard spawn interface as
+    # described in the POSIX::Spawn module documentation.
+    #
+    # This method is compatible with Kernel#system.
+    #
+    # Returns true if the command returns a zero exit status, or false for
+    # non-zero exit.
+    def system(*args)
+      pid = spawn(*args)
+      return false if pid <= 0
+      ::Process.waitpid(pid)
+      $?.exitstatus == 0
+    rescue Errno::ENOENT
+      false
+    end
+
+    # Executes a command in a subshell using the system's shell interpreter
+    # and returns anything written to the new process's stdout. This method
+    # is compatible with Kernel#`.
+    #
+    # Returns the String output of the command.
+    def `(cmd)
+      r, w = IO.pipe
+      pid = spawn(['/bin/sh', '/bin/sh'], '-c', cmd, :out => w, r => :close)
+
+      if pid > 0
+        w.close
+        out = r.read
+        ::Process.waitpid(pid)
+        out
+      else
+        ''
+      end
+    ensure
+      [r, w].each{ |io| io.close rescue nil }
+    end
+
+    # Spawn a child process with all standard IO streams piped in and out of
+    # the spawning process. Supports the standard spawn interface as described
+    # in the POSIX::Spawn module documentation.
+    #
+    # Returns a [pid, stdin, stderr, stdout] tuple, where pid is the new
+    # process's pid, stdin is a writeable IO object, and stdout / stderr are
+    # readable IO objects. The caller should take care to close all IO objects
+    # when finished and the child process's status must be collected by a call
+    # to Process::waitpid or equivalent.
+    def popen4(*argv)
+      # create some pipes (see pipe(2) manual -- the ruby docs suck)
+      ird, iwr = IO.pipe
+      ord, owr = IO.pipe
+      erd, ewr = IO.pipe
+
+      # spawn the child process with either end of pipes hooked together
+      opts =
+        ((argv.pop if argv[-1].is_a?(Hash)) || {}).merge(
+          # redirect fds        # close other sides
+          :in  => ird,          iwr  => :close,
+          :out => owr,          ord  => :close,
+          :err => ewr,          erd  => :close
+        )
+      pid = spawn(*(argv + [opts]))
+
+      [pid, iwr, ord, erd]
+    ensure
+      # we're in the parent, close child-side fds
+      [ird, owr, ewr].each { |fd| fd.close }
+    end
+
+    ##
+    # Process::Spawn::Child Exceptions
+
+    # Exception raised when the total number of bytes output on the command's
+    # stderr and stdout streams exceeds the maximum output size (:max option).
+    # Currently
+    class MaximumOutputExceeded < StandardError
+    end
+
+    # Exception raised when timeout is exceeded.
+    class TimeoutExceeded < StandardError
+    end
+
+    private
+
+    # Turns the various varargs incantations supported by Process::spawn into a
+    # simple [env, argv, options] tuple. This just makes life easier for the
+    # extension functions.
+    #
+    # The following method signature is supported:
+    #   Process::spawn([env], command, ..., [options])
+    #
+    # The env and options hashes are optional. The command may be a variable
+    # number of strings or an Array full of strings that make up the new process's
+    # argv.
+    #
+    # Returns an [env, argv, options] tuple. All elements are guaranteed to be
+    # non-nil. When no env or options are given, empty hashes are returned.
+    def extract_process_spawn_arguments(*args)
+      # pop the options hash off the end if it's there
+      options =
+        if args[-1].respond_to?(:to_hash)
+          args.pop.to_hash
+        else
+          {}
+        end
+      flatten_process_spawn_options!(options)
+      normalize_process_spawn_redirect_file_options!(options)
+
+      # shift the environ hash off the front if it's there and account for
+      # possible :env key in options hash.
+      env =
+        if args[0].respond_to?(:to_hash)
+          args.shift.to_hash
+        else
+          {}
+        end
+      env.merge!(options.delete(:env)) if options.key?(:env)
+
+      # remaining arguments are the argv supporting a number of variations.
+      argv = adjust_process_spawn_argv(args)
+
+      [env, argv, options]
+    end
+
+    # Convert { [fd1, fd2, ...] => (:close|fd) } options to individual keys,
+    # like: { fd1 => :close, fd2 => :close }. This just makes life easier for the
+    # spawn implementations.
+    #
+    # options - The options hash. This is modified in place.
+    #
+    # Returns the modified options hash.
+    def flatten_process_spawn_options!(options)
+      options.to_a.each do |key, value|
+        if key.respond_to?(:to_ary)
+          key.to_ary.each { |fd| options[fd] = value }
+          options.delete(key)
+        end
+      end
+    end
+
+    # Mapping of string open modes to integer oflag versions.
+    OFLAGS = {
+      "r"  => File::RDONLY,
+      "r+" => File::RDWR   | File::CREAT,
+      "w"  => File::WRONLY | File::CREAT  | File::TRUNC,
+      "w+" => File::RDWR   | File::CREAT  | File::TRUNC,
+      "a"  => File::WRONLY | File::APPEND | File::CREAT,
+      "a+" => File::RDWR   | File::APPEND | File::CREAT
+    }
+
+    # Convert variations of redirecting to a file to a standard tuple.
+    #
+    # :in   => '/some/file'   => ['/some/file', 'r', 0644]
+    # :out  => '/some/file'   => ['/some/file', 'w', 0644]
+    # :err  => '/some/file'   => ['/some/file', 'w', 0644]
+    # STDIN => '/some/file'   => ['/some/file', 'r', 0644]
+    #
+    # Returns the modified options hash.
+    def normalize_process_spawn_redirect_file_options!(options)
+      options.to_a.each do |key, value|
+        next if !fd?(key)
+
+        # convert string and short array values to
+        if value.respond_to?(:to_str)
+          value = default_file_reopen_info(key, value)
+        elsif value.respond_to?(:to_ary) && value.size < 3
+          defaults = default_file_reopen_info(key, value[0])
+          value += defaults[value.size..-1]
+        else
+          value = nil
+        end
+
+        # replace string open mode flag maybe and replace original value
+        if value
+          value[1] = OFLAGS[value[1]] if value[1].respond_to?(:to_str)
+          options[key] = value
+        end
+      end
+    end
+
+    # The default [file, flags, mode] tuple for a given fd and filename. The
+    # default flags vary based on the what fd is being redirected. stdout and
+    # stderr default to write, while stdin and all other fds default to read.
+    #
+    # fd   - The file descriptor that is being redirected. This may be an IO
+    #        object, integer fd number, or :in, :out, :err for one of the standard
+    #        streams.
+    # file - The string path to the file that fd should be redirected to.
+    #
+    # Returns a [file, flags, mode] tuple.
+    def default_file_reopen_info(fd, file)
+      case fd
+      when :in, STDIN, $stdin, 0
+        [file, "r", 0644]
+      when :out, STDOUT, $stdout, 1
+        [file, "w", 0644]
+      when :err, STDERR, $stderr, 2
+        [file, "w", 0644]
+      else
+        [file, "r", 0644]
+      end
+    end
+
+    # Determine whether object is fd-like.
+    #
+    # Returns true if object is an instance of IO, Fixnum >= 0, or one of the
+    # the symbolic names :in, :out, or :err.
+    def fd?(object)
+      case object
+      when Fixnum
+        object >= 0
+      when :in, :out, :err, STDIN, STDOUT, STDERR, $stdin, $stdout, $stderr, IO
+        true
+      else
+        object.respond_to?(:to_io) && !object.to_io.nil?
+      end
+    end
+
+    # Convert a fd identifier to an IO object.
+    #
+    # Returns nil or an instance of IO.
+    def fd_to_io(object)
+      case object
+      when STDIN, STDOUT, STDERR, $stdin, $stdout, $stderr
+        object
+      when :in, 0
+        STDIN
+      when :out, 1
+        STDOUT
+      when :err, 2
+        STDERR
+      when Fixnum
+        object >= 0 ? IO.for_fd(object) : nil
+      when IO
+        object
+      else
+        object.respond_to?(:to_io) ? object.to_io : nil
+      end
+    end
+
+    # Converts the various supported command argument variations into a
+    # standard argv suitable for use with exec. This includes detecting commands
+    # to be run through the shell (single argument strings with spaces).
+    #
+    # The args array may follow any of these variations:
+    #
+    # 'true'                     => [['true', 'true']]
+    # 'echo', 'hello', 'world'   => [['echo', 'echo'], 'hello', 'world']
+    # 'echo hello world'         => [['/bin/sh', '/bin/sh'], '-c', 'echo hello world']
+    # ['echo', 'fuuu'], 'hello'  => [['echo', 'fuuu'], 'hello']
+    #
+    # Returns a [[cmdname, argv0], argv1, ...] array.
+    def adjust_process_spawn_argv(args)
+      if args.size == 1 && args[0] =~ /[ |>]/
+        # single string with these characters means run it through the shell
+        [['/bin/sh', '/bin/sh'], '-c', args[0]]
+      elsif !args[0].respond_to?(:to_ary)
+        # [argv0, argv1, ...]
+        [[args[0], args[0]], *args[1..-1]]
+      else
+        # [[cmdname, argv0], argv1, ...]
+        args
+      end
+    end
+  end
+end