Method: Kernel#spawn

Defined in:

process.c

#spawn([env, ], options = {}) ⇒ Object #spawn([env, ], *args, options = {}) ⇒ Object

Creates a new child process by doing one of the following in that process:

• Passing string command_line to the shell.

• Invoking the executable at exe_path.

This method has potential security vulnerabilities if called with untrusted input; see Command Injection.

Returns the process ID (pid) of the new process, without waiting for it to complete.

To avoid zombie processes, the parent process should call either:

• Process.wait, to collect the termination statuses of its children.

• Process.detach, to register disinterest in their status.

The new process is created using the exec system call; it may inherit some of its environment from the calling program (possibly including open file descriptors).

Argument env, if given, is a hash that affects ENV for the new process; see Execution Environment.

Argument options is a hash of options for the new process; see Execution Options.

The first required argument is one of the following:

• command_line if it is a string, and if it begins with a shell reserved word or special built-in, or if it contains one or more meta characters.

• exe_path otherwise.

Argument command_line

String argument command_line is a command line to be passed to a shell; it must begin with a shell reserved word, begin with a special built-in, or contain meta characters:

spawn('if true; then echo "Foo"; fi') # => 798847 # Shell reserved word.
Process.wait                          # => 798847
spawn('exit')                         # => 798848 # Built-in.
Process.wait                          # => 798848
spawn('date > /tmp/date.tmp')         # => 798879 # Contains meta character.
Process.wait                          # => 798849
spawn('date > /nop/date.tmp')         # => 798882 # Issues error message.
Process.wait                          # => 798882

The command line may also contain arguments and options for the command:

spawn('echo "Foo"') # => 799031
Process.wait        # => 799031

Output:

Foo

See Execution Shell for details about the shell.

Raises an exception if the new process could not execute.

Argument exe_path

Argument exe_path is one of the following:

• The string path to an executable to be called.

• A 2-element array containing the path to an executable to be called, and the string to be used as the name of the executing process.

  spawn('/usr/bin/date') # Path to date on Unix-style system.
  Process.wait
  

  Output:

  Mon Aug 28 11:43:10 AM CDT 2023
  

Ruby invokes the executable directly. This form does not use the shell; see Arguments args for caveats.

If one or more args is given, each is an argument or option to be passed to the executable:

spawn('echo', 'C*')             # => 799392
Process.wait                    # => 799392
spawn('echo', 'hello', 'world') # => 799393
Process.wait                    # => 799393

Output:

C*
hello world

Raises an exception if the new process could not execute.

# File 'process.c', line 5010

static VALUE
rb_f_spawn(int argc, VALUE *argv, VALUE _)
{
    rb_pid_t pid;
    char errmsg[CHILD_ERRMSG_BUFLEN] = { '\0' };
    VALUE execarg_obj, fail_str;
    struct rb_execarg *eargp;

    execarg_obj = rb_execarg_new(argc, argv, TRUE, FALSE);
    eargp = rb_execarg_get(execarg_obj);
    fail_str = eargp->use_shell ? eargp->invoke.sh.shell_script : eargp->invoke.cmd.command_name;

    pid = rb_execarg_spawn(execarg_obj, errmsg, sizeof(errmsg));

    if (pid == -1) {
        int err = errno;
        rb_exec_fail(eargp, err, errmsg);
        RB_GC_GUARD(execarg_obj);
        rb_syserr_fail_str(err, fail_str);
    }
#if defined(HAVE_WORKING_FORK) || defined(HAVE_SPAWNV)
    return PIDT2NUM(pid);
#else
    return Qnil;
#endif
}