archive/ruby
1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2025-09-15 16:44:01 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

[DOC] RDoc for Process::Status (#8416)

Browse source
This commit is contained in:
Burdette Lamar 2023-09-12 15:31:31 -05:00 • committed by GitHub
parent d43765c3a9
commit 5edabd1cd5
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
Notes: git 2023-09-12 20:31:53 +00:00 
Merged-By: peterzhu2118 <peter@peterzhu.ca>
1 changed files with 65 additions and 75 deletions
Download patch file Download diff file Expand all files Collapse all files

140
process.c
View file

@ -566,30 +566,21 @@ proc_get_ppid(VALUE _)
* *
* Document-class: Process::Status * Document-class: Process::Status
* *
* Process::Status encapsulates the information on the * A Process::Status contains information about a system process.
* status of a running or terminated system process. The built-in
* variable <code>$?</code> is either +nil+ or a
* Process::Status object.
* *
* fork { exit 99 } #=> 26557 * Thread-local variable <tt>$?</tt> is initially +nil+.
* Process.wait #=> 26557 * Some methods assign to it a Process::Status object
* $?.class #=> Process::Status * that represents a system process (either running or terminated):
* $?.to_i #=> 25344 *
* $? >> 8 #=> 99 * `ruby -e "exit 99"`
* $?.stopped? #=> false * stat = $? # => #<Process::Status: pid 1262862 exit 99>
* $?.exited? #=> true * stat.class # => Process::Status
* $?.exitstatus #=> 99 * stat.to_i # => 25344
* stat >> 8 # => 99
* stat.stopped? # => false
* stat.exited? # => true
* stat.exitstatus # => 99
* *
* Posix systems record information on processes using a 16-bit
* integer. The lower bits record the process status (stopped,
* exited, signaled) and the upper bits possibly contain additional
* information (for example the program's return code in the case of
* exited processes). Pre Ruby 1.8, these bits were exposed directly
* to the Ruby program. Ruby now encapsulates these in a
* Process::Status object. To maximize compatibility,
* however, these objects retain a bit-oriented interface. In the
* descriptions that follow, when we talk about the integer value of
* _stat_, we're referring to this 16 bit value.
*/ */
static VALUE rb_cProcessStatus; static VALUE rb_cProcessStatus;
@ -716,14 +707,12 @@ pst_status(VALUE pst)
/* /*
* call-seq: * call-seq:
* stat.to_i -> integer * to_i -> integer
* *
* Returns the bits in _stat_ as an Integer. Poking * Returns the system-dependent integer status of +self+:
* around in these bits is platform dependent.
* *
* fork { exit 0xab } #=> 26566 * `cat /nop`
* Process.wait #=> 26566 * $?.to_i # => 256
* sprintf('%04x', $?.to_i) #=> "ab00"
*/ */
static VALUE static VALUE
@ -737,13 +726,13 @@ pst_to_i(VALUE self)
/* /*
* call-seq: * call-seq:
* stat.pid -> integer * pid -> integer
* *
* Returns the process ID that this status object represents. * Returns the process ID of the process:
*
* system("false")
* $?.pid # => 1247002
* *
* fork { exit } #=> 26569
* Process.wait #=> 26569
* $?.pid #=> 26569
*/ */
static VALUE static VALUE
@ -799,12 +788,13 @@ pst_message_status(VALUE str, int status)
/* /*
* call-seq: * call-seq:
* stat.to_s -> string * to_s -> string
* *
* Show pid and exit status as a string. * Returns a string representation of +self+:
*
* `cat /nop`
* $?.to_s # => "pid 1262141 exit 1"
* *
* system("false")
* p $?.to_s #=> "pid 12766 exit 1"
* *
*/ */
@ -826,12 +816,12 @@ pst_to_s(VALUE st)
/* /*
* call-seq: * call-seq:
* stat.inspect -> string * inspect -> string
* *
* Override the inspection method. * Returns a string representation of +self+:
* *
* system("false") * system("false")
* p $?.inspect #=> "#<Process::Status: pid 12861 exit 1>" * $?.inspect # => "#<Process::Status: pid 1303494 exit 1>"
* *
*/ */
@ -924,11 +914,11 @@ pst_rshift(VALUE st1, VALUE st2)
/* /*
* call-seq: * call-seq:
* stat.stopped? -> true or false * stopped? -> true or false
* *
* Returns +true+ if this process is stopped. This is only returned * Returns +true+ if this process is stopped,
* if the corresponding #wait call had the Process::WUNTRACED flag * and if the corresponding #wait call had the Process::WUNTRACED flag set,
* set. * +false+ otherwise.
*/ */
static VALUE static VALUE
@ -942,10 +932,10 @@ pst_wifstopped(VALUE st)
/* /*
* call-seq: * call-seq:
* stat.stopsig -> integer or nil * stopsig -> integer or nil
* *
* Returns the number of the signal that caused _stat_ to stop * Returns the number of the signal that caused the process to stop,
* (or +nil+ if self is not stopped). * or +nil+ if the process is not stopped.
*/ */
static VALUE static VALUE
@ -961,10 +951,10 @@ pst_wstopsig(VALUE st)
/* /*
* call-seq: * call-seq:
* stat.signaled? -> true or false * signaled? -> true or false
* *
* Returns +true+ if _stat_ terminated because of * Returns +true+ if the process terminated because of an uncaught signal,
* an uncaught signal. * +false+ otherwise.
*/ */
static VALUE static VALUE
@ -978,11 +968,10 @@ pst_wifsignaled(VALUE st)
/* /*
* call-seq: * call-seq:
* stat.termsig -> integer or nil * termsig -> integer or nil
* *
* Returns the number of the signal that caused _stat_ to * Returns the number of the signal that caused the process to terminate
* terminate (or +nil+ if self was not terminated by an * or +nil+ if the process was not terminated by an uncaught signal.
* uncaught signal).
*/ */
static VALUE static VALUE
@ -998,11 +987,11 @@ pst_wtermsig(VALUE st)
/* /*
* call-seq: * call-seq:
* stat.exited? -> true or false * exited? -> true or false
* *
* Returns +true+ if _stat_ exited normally (for * Returns +true+ if the process exited normally
* example using an <code>exit()</code> call or finishing the * (for example using an <code>exit()</code> call or finishing the
* program). * program), +false+ if not.
*/ */
static VALUE static VALUE
@ -1016,20 +1005,15 @@ pst_wifexited(VALUE st)
/* /*
* call-seq: * call-seq:
* stat.exitstatus -> integer or nil * exitstatus -> integer or nil
* *
* Returns the least significant eight bits of the return code of * Returns the least significant eight bits of the return code
* _stat_. Only available if #exited? is +true+. * of the process if it has exited;
* +nil+ otherwise:
* *
* fork { } #=> 26572 * `exit 99`
* Process.wait #=> 26572 * $?.exitstatus # => 99
* $?.exited? #=> true
* $?.exitstatus #=> 0
* *
* fork { exit 99 } #=> 26573
* Process.wait #=> 26573
* $?.exited? #=> true
* $?.exitstatus #=> 99
*/ */
static VALUE static VALUE
@ -1045,10 +1029,14 @@ pst_wexitstatus(VALUE st)
/* /*
* call-seq: * call-seq:
* stat.success? -> true, false or nil * success? -> true, false, or nil
*
* 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+ if _stat_ is successful, +false+ if not.
* Returns +nil+ if #exited? is not +true+.
*/ */
static VALUE static VALUE
@ -1064,10 +1052,12 @@ pst_success_p(VALUE st)
/* /*
* call-seq: * call-seq:
* stat.coredump? -> true or false * coredump? -> true or false
* *
* Returns +true+ if _stat_ generated a coredump * Returns +true+ if the process generated a coredump
* when it terminated. Not available on all platforms. * when it terminated, +false+ if not.
*
* Not available on all platforms.
*/ */
static VALUE static VALUE