diff options
author | Burdette Lamar <BurdetteLamar@Yahoo.com> | 2023-09-12 15:31:31 -0500 |
---|---|---|
committer | GitHub <noreply@github.com> | 2023-09-12 16:31:31 -0400 |
commit | 5edabd1cd57ea9a5c9fa9b782aa8df3da8781040 (patch) | |
tree | f1ecb7550af7b617cfe7deae52d89d881e51c84d /process.c | |
parent | d43765c3a9d006599895538be12b5b45c1873085 (diff) |
[DOC] RDoc for Process::Status (#8416)
Notes
Notes:
Merged-By: peterzhu2118 <peter@peterzhu.ca>
Diffstat (limited to 'process.c')
-rw-r--r-- | process.c | 144 |
1 files changed, 67 insertions, 77 deletions
@@ -566,30 +566,21 @@ proc_get_ppid(VALUE _) * * Document-class: Process::Status * - * Process::Status encapsulates the information on the - * 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 - * Process.wait #=> 26557 - * $?.class #=> Process::Status - * $?.to_i #=> 25344 - * $? >> 8 #=> 99 - * $?.stopped? #=> false - * $?.exited? #=> true - * $?.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. + * 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 >> 8 # => 99 + * stat.stopped? # => false + * stat.exited? # => true + * stat.exitstatus # => 99 + * */ static VALUE rb_cProcessStatus; @@ -716,14 +707,12 @@ pst_status(VALUE pst) /* * call-seq: - * stat.to_i -> integer + * to_i -> integer * - * Returns the bits in _stat_ as an Integer. Poking - * around in these bits is platform dependent. + * Returns the system-dependent integer status of +self+: * - * fork { exit 0xab } #=> 26566 - * Process.wait #=> 26566 - * sprintf('%04x', $?.to_i) #=> "ab00" + * `cat /nop` + * $?.to_i # => 256 */ static VALUE @@ -737,13 +726,13 @@ pst_to_i(VALUE self) /* * 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 @@ -799,12 +788,13 @@ pst_message_status(VALUE str, int status) /* * 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: - * stat.inspect -> string + * inspect -> string * - * Override the inspection method. + * Returns a string representation of +self+: * * 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: - * stat.stopped? -> true or false + * stopped? -> true or false * - * Returns +true+ if this process is stopped. This is only returned - * if the corresponding #wait call had the Process::WUNTRACED flag - * set. + * Returns +true+ if this process is stopped, + * and if the corresponding #wait call had the Process::WUNTRACED flag set, + * +false+ otherwise. */ static VALUE @@ -942,10 +932,10 @@ pst_wifstopped(VALUE st) /* * call-seq: - * stat.stopsig -> integer or nil + * stopsig -> integer or nil * - * Returns the number of the signal that caused _stat_ to stop - * (or +nil+ if self is not stopped). + * Returns the number of the signal that caused the process to stop, + * or +nil+ if the process is not stopped. */ static VALUE @@ -961,10 +951,10 @@ pst_wstopsig(VALUE st) /* * call-seq: - * stat.signaled? -> true or false + * signaled? -> true or false * - * Returns +true+ if _stat_ terminated because of - * an uncaught signal. + * Returns +true+ if the process terminated because of an uncaught signal, + * +false+ otherwise. */ static VALUE @@ -978,11 +968,10 @@ pst_wifsignaled(VALUE st) /* * call-seq: - * stat.termsig -> integer or nil + * termsig -> integer or nil * - * Returns the number of the signal that caused _stat_ to - * terminate (or +nil+ if self was not terminated by an - * uncaught signal). + * 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 @@ -998,11 +987,11 @@ pst_wtermsig(VALUE st) /* * call-seq: - * stat.exited? -> true or false + * exited? -> true or false * - * Returns +true+ if _stat_ exited normally (for - * example using an <code>exit()</code> call or finishing the - * program). + * Returns +true+ if the process exited normally + * (for example using an <code>exit()</code> call or finishing the + * program), +false+ if not. */ static VALUE @@ -1016,20 +1005,15 @@ pst_wifexited(VALUE st) /* * call-seq: - * stat.exitstatus -> integer or nil + * exitstatus -> integer or nil * - * Returns the least significant eight bits of the return code of - * _stat_. Only available if #exited? is +true+. + * Returns the least significant eight bits of the return code + * of the process if it has exited; + * +nil+ otherwise: * - * fork { } #=> 26572 - * Process.wait #=> 26572 - * $?.exited? #=> true - * $?.exitstatus #=> 0 + * `exit 99` + * $?.exitstatus # => 99 * - * fork { exit 99 } #=> 26573 - * Process.wait #=> 26573 - * $?.exited? #=> true - * $?.exitstatus #=> 99 */ static VALUE @@ -1045,10 +1029,14 @@ pst_wexitstatus(VALUE st) /* * 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 @@ -1064,10 +1052,12 @@ pst_success_p(VALUE st) /* * call-seq: - * stat.coredump? -> true or false + * coredump? -> true or false + * + * Returns +true+ if the process generated a coredump + * when it terminated, +false+ if not. * - * Returns +true+ if _stat_ generated a coredump - * when it terminated. Not available on all platforms. + * Not available on all platforms. */ static VALUE |