Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Errors, Panics and Process

Exit codes and main returning Result in Rust

How Rust programs set their exit status: returning from main, process::exit, ExitCode, main returning Result, the Termination trait and panic status 101.

Every process ends with an exit status that the parent (a shell, a build system, a container runtime) reads to decide whether the run succeeded. By convention 0 means success and any other value means failure. Rust gives you four ways to choose it: let main return normally, return a Result or ExitCode from main, call std::process::exit, or panic.

main is allowed to return any type that implements the Termination trait. The standard library provides it for (), !, ExitCode, Result<T, E> (where T: Termination and E: Debug) and Infallible.

Rust
use std::process::ExitCode;

fn main() -> ExitCode {
    ExitCode::from(3)
}

Try it

Rust main returning Result

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Rust ExitCode and process exit

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Syntax

Rust
fn main() { }                                   // exit status 0
fn main() -> ExitCode { ExitCode::from(7) }     // chosen status
fn main() -> Result<(), E> where E: Debug { }   // Err prints "Error: {:?}", status 1
pub fn std::process::exit(code: i32) -> !       // immediate exit

pub trait Termination { fn report(self) -> ExitCode; }
impl ExitCode {
    pub const SUCCESS: ExitCode;                // 0
    pub const FAILURE: ExitCode;                // 1
}
impl From<u8> for ExitCode { /* ... */ }
Way to finish Exit status
main returns () or Ok(()) 0
main returns Err(e) 1, after printing Error: followed by the Debug form of e to stderr
main returns ExitCode::from(n) n (0 to 255)
process::exit(n) n, immediately
Panic in the main thread 101
Killed by a signal Platform specific (on Unix a shell reports 128 plus the signal number)

Usage notes

  • The status is a single byte on Unix; process::exit(256) becomes 0 and exit(-1) becomes 255. Windows exit codes are 32 bits, but portable programs stay within 0 to 255.
  • process::exit does not run destructors for values still alive on the stack, and it does not unwind. Buffered output held in a BufWriter can be lost, so flush first. Prefer returning an ExitCode from main, which runs destructors normally.
  • With Result the error is printed with Debug, which looks rough for users. Many programs catch the error in main, print a friendly message with Display, and return ExitCode::FAILURE.
  • A panic in a spawned thread does not change the process status unless the main thread also fails.
  • Choose meaningful codes for tools that other programs call: 0 success, 1 general failure, 2 usage error is a common convention (shells and grep follow it).
  • A custom type can implement Termination to decide what its report returns; this is rarely needed.
  • Returning Err from main still runs destructors of locals, unlike process::exit.