Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Book: Draft for exit code chapter #61

Merged
merged 3 commits into from
Aug 2, 2018
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 54 additions & 0 deletions src/in-depth/exit-code.md
Original file line number Diff line number Diff line change
@@ -1 +1,55 @@
# Exit codes

A program doesn't always succeed.
And when an error occurs,
you should make sure to emit the necessary information correctly.
In addition to
[telling the user about errors](human-communication.md),
on most systems,
when a process exits,
it also emits an exit code
(an integer between 0 and 255 is compatible with most platforms).
You should try to emit the correct code
for your program's state.
For example,
in the ideal case when your program succeeds,
it should exit with `0`.

When an error occurs, it gets a bit more complicated, though.
In the wild,
a lot of tools exit with `1` when a general failure ocurred.
Currently, Rust set and exit code of `101` when the process panicked.
Beyond that, people have done many things in their programs.

So, what to do?
The BSD ecosystem has collected a common definition for their exit codes
(you can find them [here][`sysexits.h`]).
The Rust library [`exitcode`] provides these same codes,
ready to be used in your application.
Please see its API documentation for the possible values to use.

One way to use it is like this:

```rust
fn main() {
// ...actual work...
match result {
Ok(_) => {
println!("Done!");
std::process::exit(exitcode::OK);
}
Err(CustomError::CantReadConfig(e)) => {
eprintln!("Error: {}", e);
std::process::exit(exitcode::CONFIG);
}
Err(e) => {
eprintln!("Error: {}", e);
std::process::exit(exitcode::DATAERR);
}
}
}
```


[`exitcode`]: https://crates.io/crates/exitcode
[`sysexits.h`]: https://www.freebsd.org/cgi/man.cgi?query=sysexits&apropos=0&sektion=0&manpath=FreeBSD+11.2-stable&arch=default&format=html