class Process::Status - Documentation for Ruby 4.0
Description: class Process::Status: Status contains information about a system process. tt> is initially +nil+.
Keywords: ruby,class,Process::Status

🔍

No recent searches

# class Process::Status

A `Process::Status` contains information about a system process.

Thread-local variable `$?` is initially `nil`. Some methods assign to it a `Process::Status` object that represents a system process (either running or terminated):

    `ruby -e "exit 99"`
    stat = $?       # => #<Process::Status: pid 1262862 exit 99>
    stat.class      # => Process::Status
    stat.to_i       # => 25344
    stat.stopped?   # => false
    stat.exited?    # => true
    stat.exitstatus # => 99

### Public Class Methods

Process::Status.wait(pid = -1, flags = 0) → Process::Status
Source

    static VALUE
    rb_process_status_waitv(int argc, VALUE *argv, VALUE _)
    {
        rb_check_arity(argc, 0, 2);

        rb_pid_t pid = -1;
        int flags = 0;

        if (argc >= 1) {
            pid = NUM2PIDT(argv[0]);
        }

        if (argc >= 2) {
            flags = RB_NUM2INT(argv[1]);
        }

        return rb_process_status_wait(pid, flags);
    }

Like `Process.wait`, but returns a `Process::Status` object (instead of an integer pid or nil); see `Process.wait` for the values of `pid` and `flags`.

If there are child processes, waits for a child process to exit and returns a `Process::Status` object containing information on that process; sets thread-local variable `$?`:

    Process.spawn('cat /nop') # => 1155880
    Process::Status.wait      # => #<Process::Status: pid 1155880 exit 1>
    $?                        # => #<Process::Status: pid 1155508 exit 1>

If there is no child process, returns an “empty” `Process::Status` object that does not represent an actual process; does not set thread-local variable `$?`:

    Process::Status.wait # => #<Process::Status: pid -1 exit 0>
    $?                   # => #<Process::Status: pid 1155508 exit 1> # Unchanged.

May invoke the scheduler hook `Fiber::Scheduler#process_wait`.

Not available on all platforms.

### Public Instance Methods

stat == other → true or false
Source

    static VALUE
    pst_equal(VALUE st1, VALUE st2)
    {
        if (st1 == st2) return Qtrue;
        return rb_equal(pst_to_i(st1), st2);
    }

Returns whether the value of `to_i` == `other`:

    `cat /nop`
    stat = $?                # => #<Process::Status: pid 1170366 exit 1>
    sprintf('%x', stat.to_i) # => "100"
    stat == 0x100            # => true

coredump? → true or false
Source

    static VALUE
    pst_wcoredump(VALUE st)
    {
    #ifdef WCOREDUMP
        int status = PST2INT(st);

        return RBOOL(WCOREDUMP(status));
    #else
        return Qfalse;
    #endif
    }

Returns `true` if the process generated a coredump when it terminated, `false` if not.

Not available on all platforms.

exited? → true or false
Source

    static VALUE
    pst_wifexited(VALUE st)
    {
        int status = PST2INT(st);

        return RBOOL(WIFEXITED(status));
    }

Returns `true` if the process exited normally (for example using an `exit()` call or finishing the program), `false` if not.

exitstatus → integer or nil
Source

    static VALUE
    pst_wexitstatus(VALUE st)
    {
        int status = PST2INT(st);

        if (WIFEXITED(status))
            return INT2NUM(WEXITSTATUS(status));
        return Qnil;
    }

Returns the least significant eight bits of the return code of the process if it has exited; `nil` otherwise:

    `exit 99`
    $?.exitstatus # => 99

inspect → string
Source

    static VALUE
    pst_inspect(VALUE st)
    {
        rb_pid_t pid;
        int status;
        VALUE str;

        pid = pst_pid(st);
        if (!pid) {
            return rb_sprintf("#<%s: uninitialized>", rb_class2name(CLASS_OF(st)));
        }
        status = PST2INT(st);

        str = rb_sprintf("#<%s: ", rb_class2name(CLASS_OF(st)));
        pst_message(str, pid, status);
        rb_str_cat2(str, ">");
        return str;
    }

Returns a string representation of `self`:

    system("false")
    $?.inspect # => "#<Process::Status: pid 1303494 exit 1>"

pid → integer
Source

    static VALUE
    pst_pid_m(VALUE self)
    {
        rb_pid_t pid = pst_pid(self);
        return PIDT2NUM(pid);
    }

Returns the process ID of the process:

    system("false")
    $?.pid # => 1247002

signaled? → true or false
Source

    static VALUE
    pst_wifsignaled(VALUE st)
    {
        int status = PST2INT(st);

        return RBOOL(WIFSIGNALED(status));
    }

Returns `true` if the process terminated because of an uncaught signal, `false` otherwise.

stopped? → true or false
Source

    static VALUE
    pst_wifstopped(VALUE st)
    {
        int status = PST2INT(st);

        return RBOOL(WIFSTOPPED(status));
    }

Returns `true` if this process is stopped, and if the corresponding wait call had the Process::WUNTRACED flag set, `false` otherwise.

stopsig → integer or nil
Source

    static VALUE
    pst_wstopsig(VALUE st)
    {
        int status = PST2INT(st);

        if (WIFSTOPPED(status))
            return INT2NUM(WSTOPSIG(status));
        return Qnil;
    }

Returns the number of the signal that caused the process to stop, or `nil` if the process is not stopped.

success? → true, false, or nil
Source

    static VALUE
    pst_success_p(VALUE st)
    {
        int status = PST2INT(st);

        if (!WIFEXITED(status))
            return Qnil;
        return RBOOL(WEXITSTATUS(status) == EXIT_SUCCESS);
    }

Returns:

- `true` if the process has completed successfully and exited.

- `false` if the process has completed unsuccessfully and exited.

- `nil` if the process has not exited.

termsig → integer or nil
Source

    static VALUE
    pst_wtermsig(VALUE st)
    {
        int status = PST2INT(st);

        if (WIFSIGNALED(status))
            return INT2NUM(WTERMSIG(status));
        return Qnil;
    }

Returns the number of the signal that caused the process to terminate or `nil` if the process was not terminated by an uncaught signal.

to_i → integer
Source

    static VALUE
    pst_to_i(VALUE self)
    {
        int status = pst_status(self);
        return RB_INT2NUM(status);
    }

Returns the system-dependent integer status of `self`:

    `cat /nop`
    $?.to_i # => 256

to_s → string
Source

    static VALUE
    pst_to_s(VALUE st)
    {
        rb_pid_t pid;
        int status;
        VALUE str;

        pid = pst_pid(st);
        status = PST2INT(st);

        str = rb_str_buf_new(0);
        pst_message(str, pid, status);
        return str;
    }

Returns a string representation of `self`:

    `cat /nop`
    $?.to_s # => "pid 1262141 exit 1"