# 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 & mask → integer
Source

    static VALUE
    pst_bitand(VALUE st1, VALUE st2)
    {
        int status = PST2INT(st1);
        int mask = NUM2INT(st2);

        if (mask < 0) {
            rb_raise(rb_eArgError, "negative mask value: %d", mask);
        }
    #define WARN_SUGGEST(suggest) \
        rb_warn_deprecated_to_remove_at(3.5, "Process::Status#&", suggest)

        switch (mask) {
          case 0x80:
            WARN_SUGGEST("Process::Status#coredump?");
            break;
          case 0x7f:
            WARN_SUGGEST("Process::Status#signaled? or Process::Status#termsig");
            break;
          case 0xff:
            WARN_SUGGEST("Process::Status#exited?, Process::Status#stopped? or Process::Status#coredump?");
            break;
          case 0xff00:
            WARN_SUGGEST("Process::Status#exitstatus or Process::Status#stopsig");
            break;
          default:
            WARN_SUGGEST("other Process::Status predicates");
            break;
        }
    #undef WARN_SUGGEST
        status &= mask;

        return INT2NUM(status);
    }

This method is deprecated as `to_i` value is system-specific; use predicate methods like `exited?` or `stopped?`, or getters like `exitstatus` or `stopsig`.

Returns the logical AND of the value of `to_i` with `mask`:

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

`ArgumentError` is raised if `mask` is negative.

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

stat >> places → integer
Source

    static VALUE
    pst_rshift(VALUE st1, VALUE st2)
    {
        int status = PST2INT(st1);
        int places = NUM2INT(st2);

        if (places < 0) {
            rb_raise(rb_eArgError, "negative shift value: %d", places);
        }
    #define WARN_SUGGEST(suggest) \
        rb_warn_deprecated_to_remove_at(3.5, "Process::Status#>>", suggest)

        switch (places) {
          case 7:
            WARN_SUGGEST("Process::Status#coredump?");
            break;
          case 8:
            WARN_SUGGEST("Process::Status#exitstatus or Process::Status#stopsig");
            break;
          default:
            WARN_SUGGEST("other Process::Status attributes");
            break;
        }
    #undef WARN_SUGGEST
        status >>= places;

        return INT2NUM(status);
    }

This method is deprecated as `to_i` value is system-specific; use predicate methods like `exited?` or `stopped?`, or getters like `exitstatus` or `stopsig`.

Returns the value of `to_i`, shifted `places` to the right:

    `cat /nop`
    stat = $?                 # => #<Process::Status: pid 1155508 exit 1>
    stat.to_i                 # => 256
    stat >> 1                 # => 128
    stat >> 2                 # => 64

`ArgumentError` is raised if `places` is negative.

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"