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 click to toggle source

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.

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);
}

Public Instance Methods

stat & mask → integer click to toggle source

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.

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);
}

stat == other → true or false click to toggle source

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

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

stat >> places → integer click to toggle source

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.

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);
}

coredump? → true or false click to toggle source

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

Not available on all platforms.

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

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

exited? → true or false click to toggle source

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

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

    return RBOOL(WIFEXITED(status));
}

exitstatus → integer or nil click to toggle source

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

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

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

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

inspect → string click to toggle source

Returns a string representation of self:

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

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;
}

pid → integer click to toggle source

Returns the process ID of the process:

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

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

signaled? → true or false click to toggle source

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

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

    return RBOOL(WIFSIGNALED(status));
}

stopped? → true or false click to toggle source

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

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

    return RBOOL(WIFSTOPPED(status));
}

stopsig → integer or nil click to toggle source

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

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

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

success? → true, false, or nil click to toggle source

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.

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

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

termsig → integer or nil click to toggle source

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

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

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

to_i → integer click to toggle source

Returns the system-dependent integer status of self:

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

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

to_s → string click to toggle source

Returns a string representation of self:

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

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;
}