spawn

Similar to Kernel::system except for not waiting for end of cmd, but returns its pid.

If a hash is given as env, the environment is updated by env before exec(2) in the child process. If a pair in env has nil as the value, the variable is deleted.

# set FOO as BAR and unset BAZ.
pid = spawn({"FOO"=>"BAR", "BAZ"=>nil}, command)

If a hash is given as options, it specifies process group, resource limit, current directory, umask and redirects for the child process. Also, it can be specified to clear environment variables.

The :unsetenv_others key in options specifies to clear environment variables, other than specified by env.

pid = spawn(command, :unsetenv_others=>true) # no environment variable
pid = spawn({"FOO"=>"BAR"}, command, :unsetenv_others=>true) # FOO only

The :pgroup key in options specifies a process group. The corresponding value should be true, zero or positive integer. true and zero means the process should be a process leader. Other values specifies a process group to be belongs.

pid = spawn(command, :pgroup=>true) # process leader
pid = spawn(command, :pgroup=>10) # belongs to the process group 10

The :rlimit_foo key specifies a resource limit. foo should be one of resource types such as core The corresponding value should be an integer or an array which have one or two integers: same as cur_limit and max_limit arguments for Process.setrlimit.

pid = spawn(command, :rlimit_core=>0) # never dump core.
cur, max = Process.getrlimit(:CORE)
pid = spawn(command, :rlimit_core=>[0,max]) # disable core temporary.
pid = spawn(command, :rlimit_core=>max) # enable core dump

The :chdir key in options specifies the current directory.

pid = spawn(command, :chdir=>"/var/tmp")

The :umask key in options specifies the umask.

pid = spawn(command, :umask=>077)

The :in, :out, :err, a fixnum, an IO and an array key specifies a redirect. The redirection maps a file descriptor in the child process.

For example, stderr can be merged into stdout:

pid = spawn(command, :err=>:out)
pid = spawn(command, STDERR=>STDOUT)
pid = spawn(command, 2=>1)

The hash keys specifies a file descriptor in the child process started by spawn. :err, STDERR and 2 specifies the standard error stream.

The hash values specifies a file descriptor in the parent process which invokes spawn. :out, STDOUT and 1 specifies the standard output stream.

The standard output in the child process is not specified. So it is inherited from the parent process.

The standard input stream can be specifed by :in, STDIN and 0.

A filename can be specified as a hash value.

pid = spawn(command, STDIN=>"/dev/null") # read mode
pid = spawn(command, STDOUT=>"/dev/null") # write mode
pid = spawn(command, STDERR=>"log") # write mode
pid = spawn(command, 3=>"/dev/null") # read mode

For standard output and standard error, it is opened in write mode. Otherwise read mode is used.

For specifying flags and permission of file creation explicitly, an array is used instead.

pid = spawn(command, STDIN=>["file"]) # read mode is assumed
pid = spawn(command, STDIN=>["file", "r"])
pid = spawn(command, STDOUT=>["log", "w"]) # 0644 assumed
pid = spawn(command, STDOUT=>["log", "w", 0600])
pid = spawn(command, STDOUT=>["log", File::WRONLY|File::EXCL|File::CREAT, 0600])

The array specifies a filename, flags and permission. The flags can be a string or an integer. If the flags is ommitted or nil, File::RDONLY is assumed. The permission should be an integer. If the permission is ommitted or nil, 0644 is assumed.

If an array of IOs and integers are specified as a hash key, all the elemetns are redirected.

# standard output and standard error is redirected to log file.
pid = spawn(command, [STDOUT, STDERR]=>["log", "w"])

spawn closes all non-standard unspecified descriptors by default. The “standard” descriptors are 0, 1 and 2. This behavior is specified by :close_others option. :close_others doesn’t affect the standard descriptors which are closed only if :close is specified explicitly.

pid = spawn(command, :close_others=>true)  # close 3,4,5,... (default)
pid = spawn(command, :close_others=>false) # don't close 3,4,5,...

:close_others is true by default for spawn and IO.popen.

So IO.pipe and spawn can be used as IO.popen.

# similar to r = IO.popen(command)
r, w = IO.pipe
pid = spawn(command, STDOUT=>w)   # r, w is closed in the child process.
w.close

:close is specified as a hash value to close a fd individualy.

f = open(foo)
system(command, f=>:close)        # don't inherit f.

It is also possible to exchange file descriptors.

pid = spawn(command, STDOUT=>STDERR, STDERR=>STDOUT)

The hash keys specify file descriptors in the child process. The hash values specifies file descriptors in the parent process. So the above specifies exchanging STDOUT and STDERR. Internally, spawn uses an extra file descriptor to resolve such cyclic file descriptor mapping.

static VALUE
rb_f_spawn(int argc, VALUE *argv)
{
    rb_pid_t pid;

    pid = rb_spawn(argc, argv);
    if (pid == -1) rb_sys_fail(RSTRING_PTR(argv[0]));
#if defined(HAVE_FORK) || defined(HAVE_SPAWNV)
    return PIDT2NUM(pid);
#else
    return Qnil;
#endif
}