CommonCodes v2.2.0
Description
CommonCodes is an attempt to create a standardized list of program exit statuses.
CommonCodes includes the 15 exit codes defined by BSD in sysexits.h
that range from 64 to 78.
GNU Bash uses the exit status 2 to indicate incorrect usage of shell builtins. Bash also uses codes above 125 for special exit statuses like termination by a sent signal.
CommonCodes adopts both of these rules, using 2 as a generic usage error and not defining any codes above 125.
If you're going to use the CommonCodes standard in your program, be sure to document it. A good place would be both the --help
summary and the programs manpage.
It is recommended to always add which exact version is being used.
Some ranges have been kept empty so that developers may add error messages of their own, tailored to the program that they are writing.
If statuses in these ranges are defined then they should always be documented. Again in the --help
summary and in the manpage.
In the table of the following section, these rules, which are similar to command usage patterns, apply for the messages:
- Italic and/or underlined symbols are placeholders for other text that should get replaced for real messages.
In places were formatting does not exist, placeholders are wrapped in angle brackets (<
>
) - Text and symbols in bold parenthesis are grouped
- Text and symbols in bold square brackets may be omitted in real messages
- Text and symbols followed by bold ellipsis (three consecutive dots (
...
)) may be repeated one or more times in real messages - A vertical bar (
|
) means alteration: either only the left or right side may be used
Some status messages have the suffix appendend to them and a lot of usage errors about arguments also contain the placeholder
.
may be more information on what the error represents and why it happened.
may be either a POSIX short option or a GNU long option, if that option received the argument that is invalid instead the program itself.
Exit Status Table
Code | Message | Description |
---|---|---|
0 | The program executed successfully or the | |
1 | Any other error that doesn't fit in any other category. | |
2 | Any other program usage error that doesn't fit in any other category. | |
3 | Not enough arguments have been passed down to the program or to an option of the program. | |
4 | Too many arguments have been passed down to the program or to an option of the program. | |
5 | The entered option is not specified in the program. | |
6 | The spotted option at this position with the combination and order of arguments and other options is invalid. | |
7 | The argument is invalid and cannot be used. | |
8 | The entered (sub)command of the program is not known. | |
9 | The program can not work with empty or blank argument. | |
10 | The argument is not a valid number or is not a valid integer. | |
11 | The numerical argument is out of the given range. | |
12 | The argument does not match the pattern provided. The pattern can be glob, regex or any other pattern matching system. | |
13 - 23 | Usage errors defined by the developer of the program. These should always be documented. | |
24 | The item in question could not be found. | |
25 | The item in question already exists and is of type | |
26 | The item in question is of the wrong type. | |
27 | An external program is required but could not have been found. | |
28 | A general network error occurred. | |
29 | No network connection is established. | |
30 | A network request took too long and timed out. | |
31 | A general arithmetic error occurred. | |
32 - 47 | Custom exit codes defined by the developer that aren't actually errors, but rather, feedback for the program user. These should always be documented. | |
48 - 63 | General custom errors defined by the developer. These should always be documented. | |
64 | The command was used incorrectly, e.g., with the wrong number of arguments, a bad flag, a bad syntax in a parameter, or whatever. | |
65 | The input data was incorrect in some way. | |
66 | An input file (not a system file) did not exist or was not readable. This could also include errors like "No message" to a mailer (if it cared to catch it). | |
67 | The user specified did not exist. | |
68 | The host specified did not exist. | |
69 | A service is unavailable. This can occur if a support program or file does not exist. | |
70 | An internal software error has been detected. | |
71 | An operating system error has been detected. | |
72 | Some system file (e.g., | |
73 | A (user specified) output file cannot be created. | |
74 | An error occurred while doing I/O on some file. | |
75 | Temporary failure, indicating something that is not really an error. | |
76 | The remote system returned something that was "not possible" during a protocol exchange. | |
77 | You did not have sufficient permission to perform the operation. | |
78 | Something was found in an unconfigured or misconfigured state. | |
79 - 97 | Configuration, property and setting errors defined by the developer. These should always be documented. | |
98 | Too many symlinks were encountered when trying to resolve the realpath. | |
99 | The name of the file is too long. | |
100 | A general memory error occurred. | |
101 | There was not enough free memory (either heap or kernel memory) to perform an operation. | |
102 | A stack overflow occurred. | |
103 | Generic internal fault. | |
104 - 122 | Different internal faults, defined by the developer. These should always be documented. | |
123 | The program was intentionally halted by the developer because a value is invalid and can't be worked with. | |
124 | The shell script can either only be executed interactively (using command " | |
125 | Cause of error is not known, not even to the developer. |
Footnotes
Since exit code 2 (generic usage error) and exit code 64 (command line usage error) are basically the same, it is recommended to use code 2 when distributing for GNU/Linux systems and code 64 when distributing for BSD systems.
See Also
<https://github.com/mfederczuk/commoncodes>, grep(1), glob(7), regex(7)