Kernel#spawn

spawn([env, ] command_line, options = {}) → pid

spawn([env, ] exe_path, *args, options = {}) → pid

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
}

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:

Example

spawn('if true; then echo "Foo"; fi') # => 798847 # Shell reserved word.
Process.wait                          # => 798847
spawn('echo')                         # => 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:

Example

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

Output:

Example

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:

Example

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

Output:

Thu Aug 31 10:06:48 AM CDT 2023

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

Example
```
pid = spawn(['sleep', 'Hello!'], '1') # 2-element array.
p `ps -p #{pid} -o command=`
```
Output:

Example
```
"Hello! 1\n"
```

Ruby invokes the executable directly, with no shell and no shell expansion.

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

Example

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.

See also #sleep #sprintf #set_trace_func #srand also in 4.1 · 4.0 · 3.4 · 3.2 · 3.1 · 3.0

‹ prev#sleep next ›#sprintf