1 stable release
| 1.0.0 | Jan 10, 2023 |
|---|
#7 in #status-code
16KB
170 lines
Semantic Exit Codes
Usage
Go
os.Exit(exit.Forbidden) // The user isn't permitted to perform this action
os.Exit(exit.Unavailable) // An API this program consumes isn't available
Rust
use semantic_exit::{exit, Code};
exit(Code::Forbidden);
exit(Code::Unavailable);
See the complete list of exit codes.
About
Conventionally, exiting a program with zero indicates success while nonzero indicates failure.
os.Exit(0) // success
os.Exit(1) // failure
But the system call exit accepts values between 0 and 255, leaving 254 different ways of expressing failure.
This library's goals are to define exit codes that are:
- Broadly applicable to heterogenous Command Line tools
- Easy to partition into user errors and system errors
It defines codes in two unreserved ranges: 80-99 for user errors and 100-119 for software or system errors.
The Codes
| Exit Code | Name | Meaning |
|---|---|---|
| 0 | OK |
The program exited successfully. |
| 1 | NotOK |
The program exited unsuccessfully but gives no extra context as to what the failure was. |
| 80 | UsageError |
The program exited unsuccessfully because it was was used incorrectly. (e.g. a required argument was omitted or an invalid value was supplied for a flag.) |
| 81 | UnknownSubcommand |
The program exited unsuccessfully because an unrecognized subcommand was invoked. (Used by CLI multi-tools.) |
| 82 | RequirementNotMet |
The program exited unsuccessfully because a prerequisite of it wasn't met. |
| 83 | Forbidden |
The program exited unsuccessfully because the user isn't authorized to perform the requested action. |
| 84 | MovedPermanently |
The program exited unsuccessfully because it has been migrated to a new location. |
| 100 | InternalError |
The program exited unsuccessfully because of a problem in its own code. (Used instead of 1 when the problem is known to be with the program's code or dependencies.) |
| 101 | Unavailable |
The program exited unsuccessfully because a service it depends on was not available. (e.g. A local daemon or remote service did not respond, a connection was closed unexpectedly, an HTTP service responded with 503.) |
Reserved Codes and Prior Art
- Values above 128 are reserved for signals. (When a program is terminated with a signal, its exit code is 128 + the signal's numeric value. When you terminate a program with
CtrlC, for example, you send it the signalSIGINT— whose value is 2 — and the program exits with 130.) - Bash reserves 2, 126, and 127.
- sysexits.h defines 64-78. The
sysexits.hcodes were originally defined forsendmailbut have been used many places since. (Compare Semantic Exit Codes to sysexits.h codes)
Dependencies
~0.3–0.9MB
~19K SLoC