bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

ExitStatus: Improve documentation re wait status vs exit status

Browse source 
The use of `ExitStatus` as the Rust type name for a Unix *wait
status*, not an *exit status*, is very confusing, but sadly probably
too late to change.

This area is confusing enough in Unix already (and many programmers
are already confuxed).  We can at least document it.

I chose *not* to mention the way shells like to exit with signal
numbers, thus turning signal numbers into exit statuses.  This is only
relevant for Rust programs using `std::process` if they run shells.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
This commit is contained in:
Ian Jackson 2021-02-22 15:26:19 +00:00
parent d8cfd56985
commit 4bb8425af6
2 changed files with 30 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

25
library/std/src/process.rs
View file

@ -885,7 +885,7 @@ impl Command {
}
/// Executes a command as a child process, waiting for it to finish and
/// collecting its exit status.
/// collecting its status.
///
/// By default, stdin, stdout and stderr are inherited from the parent.
///
@ -899,7 +899,7 @@ impl Command {
/// .status()
/// .expect("failed to execute process");
///
/// println!("process exited with: {}", status);
/// println!("process finished with: {}", status);
///
/// assert!(status.success());
/// ```
@ -1368,11 +1368,17 @@ impl From<fs::File> for Stdio {
/// Describes the result of a process after it has terminated.
///
/// This `struct` is used to represent the exit status of a child process.
/// This `struct` is used to represent the exit status or other termination of a child process.
/// Child processes are created via the [`Command`] struct and their exit
/// status is exposed through the [`status`] method, or the [`wait`] method
/// of a [`Child`] process.
///
/// An `ExitStatus` represents every possible disposition of a process. On Unix this
/// is the **wait status**. It is *not* simply an *exit status* (a value passed to `exit`).
///
/// For proper error reporting of failed processes, print the value of `ExitStatus` using its
/// implementation of [`Display`](crate::fmt::Display).
///
/// [`status`]: Command::status
/// [`wait`]: Child::wait
#[derive(PartialEq, Eq, Clone, Copy, Debug)]
@ -1400,7 +1406,7 @@ impl ExitStatus {
/// if status.success() {
/// println!("'projects/' directory created");
/// } else {
/// println!("failed to create 'projects/' directory");
/// println!("failed to create 'projects/' directory: {}", status);
/// }
/// ```
#[stable(feature = "process", since = "1.0.0")]
@ -1410,9 +1416,14 @@ impl ExitStatus {
/// Returns the exit code of the process, if any.
///
/// On Unix, this will return `None` if the process was terminated
/// by a signal; `std::os::unix` provides an extension trait for
/// extracting the signal and other details from the `ExitStatus`.
/// In Unix terms the return value is the **exit status**: the value passed to `exit`, if the
/// process finished by calling `exit`. Note that on Unix the exit status is truncated to 8
/// bits, and that values that didn't come from a program's call to `exit` may be invented the
/// runtime system (often, for example, 255, 254, 127 or 126).
///
/// On Unix, this will return `None` if the process was terminated by a signal.
/// [`ExitStatusExt`](crate::os::unix::process::ExitStatusExt) is an
/// extension trait for extracting any such signal, and other details, from the `ExitStatus`.
///
/// # Examples
///