From b826f4f402caefe7ff82c3652d45efb71b91a0d3 Mon Sep 17 00:00:00 2001 From: Pascal Hertleif Date: Wed, 1 Aug 2018 17:53:11 +0200 Subject: [PATCH 1/3] Book: Draft for exit code chapter Resolves #39 --- src/in-depth/exit-code.md | 54 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/src/in-depth/exit-code.md b/src/in-depth/exit-code.md index 4f13cfab..c11d6c5e 100644 --- a/src/in-depth/exit-code.md +++ b/src/in-depth/exit-code.md @@ -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. +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). +You should try to emit the correct code +for your program's state. +For example, +in the ideal case when your program succeeded, +it should exit with `0`. + +When an error ocurred, 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, many people have done many things in their programs. + +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`] +The Rust library [`exitcode`] provides these same codes +ready to be used in your application. +Please see it's 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 From d7d29992b42e864bb01b40b14f1baf57d3f47484 Mon Sep 17 00:00:00 2001 From: Pascal Hertleif Date: Wed, 1 Aug 2018 22:54:09 +0200 Subject: [PATCH 2/3] Book: Fix tpyos in exit code chapter --- src/in-depth/exit-code.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/in-depth/exit-code.md b/src/in-depth/exit-code.md index c11d6c5e..91b6496b 100644 --- a/src/in-depth/exit-code.md +++ b/src/in-depth/exit-code.md @@ -1,8 +1,8 @@ # Exit codes -A program doesn't always success. +A program doesn't always succeed. And when an error occurs, -you should make sure to use the correct ways to emit the necessary information. +you should make sure to emit the necessary information correctly. In addition to [telling the user about errors](human-communication.md), on most systems, @@ -12,21 +12,21 @@ it also emits an exit code You should try to emit the correct code for your program's state. For example, -in the ideal case when your program succeeded, +in the ideal case when your program succeeds, it should exit with `0`. -When an error ocurred, it gets a bit more complicated, though. +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, many people have done many things in their programs. +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 in a system-provided header file called [`sysexits.h`] -The Rust library [`exitcode`] provides these same codes +The Rust library [`exitcode`] provides these same codes, ready to be used in your application. -Please see it's API documentation for the possible values to use. +Please see its API documentation for the possible values to use. One way to use it is like this: From 6783658ec20a036efa7a9b7afac5c92230d7d4d6 Mon Sep 17 00:00:00 2001 From: Pascal Hertleif Date: Thu, 2 Aug 2018 09:29:03 +0200 Subject: [PATCH 3/3] Book: Exit code review feedback --- src/in-depth/exit-code.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/in-depth/exit-code.md b/src/in-depth/exit-code.md index 91b6496b..fbc4c5e6 100644 --- a/src/in-depth/exit-code.md +++ b/src/in-depth/exit-code.md @@ -8,7 +8,7 @@ In addition to on most systems, when a process exits, it also emits an exit code -(an integer between 0 and 255). +(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, @@ -23,7 +23,7 @@ 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 -in a system-provided header file called [`sysexits.h`] +(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.