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 1 commit
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 success.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

succeed

And when an error occurs,
you should make sure to use the correct ways to emit the necessary information.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

use a correct way
or
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).

Choose a reason for hiding this comment

The 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, std::process::exit takes an i32, I'm not sure why). It's probably best not to mention the actual limits until you get to a "platform-specific behaviour" section.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The 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,

Choose a reason for hiding this comment

The 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.

Choose a reason for hiding this comment

The 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.

Choose a reason for hiding this comment

The 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.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Beyond that, many people have ...


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`]

Choose a reason for hiding this comment

The 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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The 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

Choose a reason for hiding this comment

The 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.

Choose a reason for hiding this comment

The 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