-
Notifications
You must be signed in to change notification settings - Fork 34
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
Changes from 1 commit
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,55 @@ | ||
# Exit codes | ||
|
||
A program doesn't always success. | ||
And when an error occurs, | ||
you should make sure to use the correct ways to emit the necessary information. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. use a correct way |
||
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). | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. On POSIX, an exit code is a u8, while on Win32 an exit code is a u32 (weirdly, There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. How about "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 succeeded, | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. when your program succeeds, |
||
it should exit with `0`. | ||
|
||
When an error ocurred, it gets a bit more complicated, though. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. s/occured/occurs |
||
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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Currently, Rust sets an exit code of ... |
||
Beyond that, many people have done many things in their programs. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Beyond that, |
||
|
||
So, what to do? | ||
The BSD ecosystem has collected a common definition for their exit codes | ||
in a system-provided header file called [`sysexits.h`] | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Is it appropriate to assume the reader will understand "a system-provided header file"? A lot of people certainly will, but somebody who comes here right after finishing TRPL might not. If this book is aimed at an audience that already knows what header files are, that's fine, I just thought I'd mention it. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Good point! I wanted to point to the source of the exit code list but you're right that is probably more confusing than helpful. |
||
The Rust library [`exitcode`] provides these same codes | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. provides the same codes which are ready ... |
||
ready to be used in your application. | ||
Please see it's API documentation for the possible values to use. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. s/it's/its |
||
|
||
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
succeed