Class: Process::Status

Inherits:
Object show all
Defined in:
process.c,
process.c

Overview

*******************************************************************

A Process::Status contains information about a system process.

Thread-local variable <tt>$?</tt> 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

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.Process::Status.wait(pid = -1, flags = 0) ⇒ Process::Status

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.

Returns:



1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
 
# File 'process.c', line 1251

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

Instance Method Details

#&(mask) ⇒ Integer

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.

Returns:



894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
 
# File 'process.c', line 894

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

#==(other) ⇒ Boolean

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

Returns:

  • (Boolean) 


868
869
870
871
872
873
 
# File 'process.c', line 868

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

#>>(places) ⇒ Integer

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.

Returns:



949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
 
# File 'process.c', line 949

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? ⇒ Boolean

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

Not available on all platforms.

Returns:

  • (Boolean) 


1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
 
# File 'process.c', line 1127

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

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

#exited? ⇒ Boolean

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

Returns:

  • (Boolean) 


1061
1062
1063
1064
1065
1066
1067
 
# File 'process.c', line 1061

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

    return RBOOL(WIFEXITED(status));
}

#exitstatus ⇒ Integer?

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

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

Returns:



1083
1084
1085
1086
1087
1088
1089
1090
1091
 
# File 'process.c', line 1083

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

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

#inspect ⇒ String

Returns a string representation of self:

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

Returns:



835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
 
# File 'process.c', line 835

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

Returns the process ID of the process:

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

Returns:



745
746
747
748
749
750
 
# File 'process.c', line 745

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

#signaled? ⇒ Boolean

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

Returns:

  • (Boolean) 


1024
1025
1026
1027
1028
1029
1030
 
# File 'process.c', line 1024

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

    return RBOOL(WIFSIGNALED(status));
}

#stopped? ⇒ Boolean

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

Returns:

  • (Boolean) 


988
989
990
991
992
993
994
 
# File 'process.c', line 988

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

    return RBOOL(WIFSTOPPED(status));
}

#stopsig ⇒ Integer?

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

Returns:



1005
1006
1007
1008
1009
1010
1011
1012
1013
 
# File 'process.c', line 1005

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

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

#success? ⇒ true, ...

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.

Returns:

  • (true, false, nil) 


1106
1107
1108
1109
1110
1111
1112
1113
1114
 
# File 'process.c', line 1106

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

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

#termsig ⇒ Integer?

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

Returns:



1041
1042
1043
1044
1045
1046
1047
1048
1049
 
# File 'process.c', line 1041

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

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

#to_i ⇒ Integer

Returns the system-dependent integer status of self:

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

Returns:



725
726
727
728
729
730
 
# File 'process.c', line 725

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

#to_s ⇒ String

Returns a string representation of self:

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

Returns:



808
809
810
811
812
813
814
815
816
817
818
819
820
821
 
# File 'process.c', line 808

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