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.
use std::process::ExitCode; fn main() -> ExitCode { ExitCode::from(3) }
Try it
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.
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
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 andexit(-1)becomes 255. Windows exit codes are 32 bits, but portable programs stay within 0 to 255. process::exitdoes not run destructors for values still alive on the stack, and it does not unwind. Buffered output held in aBufWritercan be lost, so flush first. Prefer returning anExitCodefrommain, which runs destructors normally.- With
Resultthe error is printed withDebug, which looks rough for users. Many programs catch the error inmain, print a friendly message withDisplay, and returnExitCode::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
grepfollow it). - A custom type can implement
Terminationto decide what itsreportreturns; this is rarely needed. - Returning
Errfrommainstill runs destructors of locals, unlikeprocess::exit.