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
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.
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.
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
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.
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.
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.
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
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>"
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
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.
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.
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.
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.
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.
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
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"