class Process::Status - RDoc Documentation (original) (raw)

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 = $?
stat.class
stat.to_i
stat.stopped?
stat.exited?
stat.exitstatus

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') Process::Status.wait
$?

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 $?

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 = $?
sprintf('%x', stat.to_i)
stat & 0x00

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 = $?
sprintf('%x', stat.to_i) stat == 0x100

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 = $?
stat.to_i
stat >> 1
stat >> 2

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

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

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

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:

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

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

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;

}