Trait ExitStatusExt 

pub trait ExitStatusExt {
    // Required methods
    fn from_raw(raw: i32) -> Self;
    fn signal(&self) -> Option<i32>;
    fn core_dumped(&self) -> bool;
    fn stopped_signal(&self) -> Option<i32>;
    fn continued(&self) -> bool;
    fn into_raw(self) -> i32;
}

ⓘ This trait cannot be implemented outside std.

Available on Unix only.

Unix-specific extensions to ExitStatus and ExitStatusError.

On Unix, ExitStatus does not necessarily represent an exit status, as passed to the _exit system call or returned by ExitStatus::code(). It represents any wait status as returned by one of the wait family of system calls.

A Unix wait status (a Rust ExitStatus) can represent a Unix exit status, but can also represent other kinds of process event.

Required Methods

fn from_raw(raw: i32) -> Self

Creates a new ExitStatus or ExitStatusError from the raw underlying integer status value from wait.

The value should be a wait status, not an exit status.

Example

A signal-terminated wait status carries the signal number, which ExitStatus::signal recovers using the platform’s WTERMSIG macro. Note that the bit layout of a wait status is not specified by POSIX and is platform-specific. By convention on most Unix platforms, the signal number occupies the low 7 bits with the exit-code byte left zero, so a bare signal number between 1 and 126 is treated as a signal-terminated wait status. The following example relies on that convention and is therefore not guaranteed to hold on every target:

use std::os::unix::process::ExitStatusExt;
use std::process::ExitStatus;

let signal = 15; // SIGTERM
assert!(signal > 0 && signal < 0x7f, "not a valid Unix termination signal: {signal}");

let status = ExitStatus::from_raw(signal);
assert!(!status.success());
assert_eq!(status.code(), None);
assert_eq!(status.signal(), Some(15));

Generating an ExitStatus with a given exit code (0-255) is system-dependent. The value returned by ExitStatus::code is specified to come from applying the WEXITSTATUS macro, but there is no POSIX-specified constructor and the bit layout is left unspecified. By near-universal convention every Unix libc stores the 8-bit exit code in bits 8..16, so a status built with (code & 0xff) << 8 will usually round-trip back to the original exit code:

use std::os::unix::process::ExitStatusExt;
use std::process::ExitStatus;

let code = 41;
let status = ExitStatus::from_raw((code & 0xff) << 8);
assert_eq!(status.code(), Some(41));
assert!(!status.success());

Panics

• ExitStatusError::from_raw panics on an attempt to make an ExitStatusError from a wait status of 0.
• ExitStatus::from_raw always succeeds and never panics.

fn signal(&self) -> Option<i32>

If the process was terminated by a signal, returns that signal.

In other words, if WIFSIGNALED, this returns WTERMSIG. For such a status, ExitStatus::code returns None:

use std::os::unix::process::ExitStatusExt;
use std::process::ExitStatus;

let sigterm = 15;
let status = ExitStatus::from_raw(sigterm);
assert_eq!(status.code(), None);
assert_eq!(status.signal(), Some(sigterm));

A process that receives a signal may catch and handle it, then exit normally with an exit code. When that happens, signal returns None.

Rust does not pass commands through a shell, such as bash and sh, but it is possible to do so manually. When invoking a shell, the signal value indicates whether the top-level shell itself received a terminating signal. If instead a command within an invoked shell receives a terminating signal, many shells convert the signal number into an exit code by adding 128. For example, a command run under sh that receives a SIGTERM canonically causes the shell to report an exit code of 15 + 128, i.e. 143.

fn core_dumped(&self) -> bool

If the process was terminated by a signal, says whether it dumped core.

fn stopped_signal(&self) -> Option<i32>

If the process was stopped by a signal, returns that signal.

In other words, if WIFSTOPPED, this returns WSTOPSIG. This is only possible if the status came from a wait system call which was passed WUNTRACED, and was then converted into an ExitStatus.

fn continued(&self) -> bool

Whether the process was continued from a stopped status.

I.e. WIFCONTINUED. This is only possible if the status came from a wait system call which was passed WCONTINUED, and was then converted into an ExitStatus.

fn into_raw(self) -> i32

Returns the underlying raw wait status.

The returned integer is a wait status, not an exit status.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl ExitStatusExt for ExitStatus

impl ExitStatusExt for ExitStatusError