Process::Status

Waits for a child process to exit and returns a Process::Status object containing information on that process. Which child it waits on depends on the value of pid:

> 0

Waits for the child whose process ID equals pid.

0

Waits for any child whose process group ID equals that of the calling process.

-1

Waits for any child process (the default if no pid is given).

< -1

Waits for any child whose process group ID equals the absolute value of pid.

The flags argument may be a logical or of the flag values Process::WNOHANG (do not block if no child available) or Process::WUNTRACED (return stopped children that haven’t been reported). Not all flags are available on all platforms, but a flag value of zero will work on all platforms.

Returns nil if there are no child processes. Not available on all platforms.

May invoke the scheduler hook process_wait.

fork { exit 99 }                              #=> 27429
Process::Status.wait                          #=> pid 27429 exit 99
$?                                            #=> nil

pid = fork { sleep 3 }                        #=> 27440
Time.now                                      #=> 2008-03-08 19:56:16 +0900
Process::Status.wait(pid, Process::WNOHANG)   #=> nil
Time.now                                      #=> 2008-03-08 19:56:16 +0900
Process::Status.wait(pid, 0)                  #=> pid 27440 exit 99
Time.now                                      #=> 2008-03-08 19:56:19 +0900

This is an EXPERIMENTAL FEATURE.

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

Logical AND of the bits in stat with num.

fork { exit 0x37 }
Process.wait
sprintf('%04x', $?.to_i)       #=> "3700"
sprintf('%04x', $? & 0x1e00)   #=> "1600"

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

    return INT2NUM(status);
}
            

Returns true if the integer value of stat equals other.

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

Shift the bits in stat right num places.

fork { exit 99 }   #=> 26563
Process.wait       #=> 26563
$?.to_i            #=> 25344
$? >> 8            #=> 99

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

    return INT2NUM(status);
}
            

Returns true if stat generated a coredump when it terminated. Not available on all platforms.

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

    if (WCOREDUMP(status))
        return Qtrue;
    else
        return Qfalse;
#else
    return Qfalse;
#endif
}
            

Returns true if stat exited normally (for example using an exit() call or finishing the program).

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

    if (WIFEXITED(status))
        return Qtrue;
    else
        return Qfalse;
}
            

Returns the least significant eight bits of the return code of stat. Only available if exited? is true.

fork { }           #=> 26572
Process.wait       #=> 26572
$?.exited?         #=> true
$?.exitstatus      #=> 0

fork { exit 99 }   #=> 26573
Process.wait       #=> 26573
$?.exited?         #=> true
$?.exitstatus      #=> 99

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

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

Override the inspection method.

system("false")
p $?.inspect #=> "#<Process::Status: pid 12861 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;
}
            

Returns the process ID that this status object represents.

fork { exit }   #=> 26569
Process.wait    #=> 26569
$?.pid          #=> 26569

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

Returns true if stat terminated because of an uncaught signal.

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

    if (WIFSIGNALED(status))
        return Qtrue;
    else
        return Qfalse;
}
            

Returns true if this process is stopped. This is only returned if the corresponding wait call had the Process::WUNTRACED flag set.

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

    if (WIFSTOPPED(status))
        return Qtrue;
    else
        return Qfalse;
}
            

Returns the number of the signal that caused stat to stop (or nil if self is not stopped).

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

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

Returns true if stat is successful, false if not. Returns nil if exited? is not true.

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

    if (!WIFEXITED(status))
        return Qnil;
    return WEXITSTATUS(status) == EXIT_SUCCESS ? Qtrue : Qfalse;
}
            

Returns the number of the signal that caused stat to terminate (or nil if self 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;
}
            

Returns the bits in stat as an Integer. Poking around in these bits is platform dependent.

fork { exit 0xab }         #=> 26566
Process.wait               #=> 26566
sprintf('%04x', $?.to_i)   #=> "ab00"

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

Show pid and exit status as a string.

system("false")
p $?.to_s         #=> "pid 12766 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;
}