CommonCodes v1.2.0

November 13, 2021

Description

CommonCodes is an attempt to standardize the meaning of exit statuses of programs written for Unix like systems.

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 also always be documented. Again in the --help summary and in the manpage.

In the following table, these rules apply for the status messages:

  • Italic and/or underlined symbols are placeholders for other text that should get replaced for real messages.
  • Text and symbols in bold square brackets may be ommitted in real messages.
  • Text and symbols followed by bold ellipsis may be repeated one or more times in real messages.
  • In real messages, only one field of text and symbols may be displayed if they are separated by bold vertical bars(|).

Some status messages have the suffix [: info] appendend to them and a lot of usage errors about arguments also contain the placeholder option.
info may be more information on what the error represents and why it happened.
option may be either a POSIX short option or a GNU long option, if that option received the argument that is invalid except the program itself.

Exit Status Table

Exit Statuses
Code Message Description
0 success

The program executed successfully or the --help or the --version options were specified.
1 generic error[: info]

Any other error that doesn't fit in any other category.
2 generic usage error[: info]

Any other program usage error that doesn't fit in any other category.
3 [option: ]missing argument[s][: arguments...]

Not enough arguments have been passed down to the program or to an option of the program.
arguments may be the placeholder name of the missing arguments.
4 [option: ]too many arguments[: n]

Too many arguments have been passed down to the program or to an option of the program.
n may be the amount of arguments that are not needed.
5 option: invalid option

The entered option is not specified in the program.
6 option: unexpected option

The seen option at this position with the set combination and order of arguments and other options is invalid.
7 [option: ]argument: invalid argument[: info]

The argument is invalid and cannot be used.
8 argument: unknown [sub]command

The entered (sub)command of the program is not known.
9 [option: ]argument [n: ](may|must) not be (empty|blank)

Program can not work with empty or blank argument.
"Blank" means none or only whitespace characters.
n is the position of the argument that is empty/blank and is only really needed when the program/option needs multiple arguments.
10 [option: ]argument: not a[n] (number|integer)

The argument is not a valid number or is not a valid integer.
11 [option: ]argument: out of range[ (relational_op limit)]

The numerical argument is out of the given range.
relational_op may be the four relational operators: <=, <, > or >=
limit may either be the minumum, floor, maximum or ceiling value.
12 [option: ]argument: does not match: pattern

The argument does not match the pattern provided. The pattern can be glob, regex or any other pattern matching system.
13 - 23 (custom usage errors)

Usage errors defined by the developer of the program. These should always be documented.
24 item: no such itemtype[[, itemtype]... or itemtype]

The item in question could not be found.
item can be things like paths, etc. and itemtype can be things like regular files, directories, etc.
25 item: not a[n] itemtype[[, itemtype]... or itemtype]

The item in question is of the wrong type.
26 network error[: info]

A general network error occurred.
27 no network connection

No network connection is established.
28 connection timed out

A network request took too long and timed out.
29 arithmetic error[: info]

A general arithmetic error occurred.
30 divided by 0 error

A division by 0 was tried to be executed and there was no fallback option.
31 (overflow|underflow) error

An overflow or underflow happened and it has critical effects on the program.
32 - 47 (custom feedback statuses)

Custom exit codes defined by the developer that aren't actually errors, but rather, feedback for the program user.
For example, the program grep exits with code 1 when it couldn't match an entered pattern.
48 - 63 (custom errors)

General custom errors defined by the developer. These should always be documented.
64 command line usage error[: info]

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 data format error[: info]

The input data was incorrect in some way.
66 cannot open input[: info]

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 addressee unknown[: info]

The user specified did not exist.
68 host name unknown[: info]

The host specified did not exist.
69 service unavailable[: info]

A service is unavailable. This can occur if a support program or file does not exist.
70 internal software error[: info]

An internal software error has been detected.
71 system error[: info]

An operating system error has been detected.
72 critical OS file missing[: info]

Some system file (e.g., /etc/passwd, /etc/utmp, etc.) does not exist, cannot be opened, or has some sort of error (e.g., syntax error).
73 can't create (user) output file[: info]

A (user specified) output file cannot be created.
74 input/output error[: info]

An error occurred while doing I/O on some file.
75 temp failure[: info]

Temporary failure, indicating something that is not really an error.
76 remote error in protocol[: info]

The remote system returned something that was "not possible" during a protocol exchange.
77 permission denied[: info]

You did not have sufficient permission to perform the operation.
78 configuration error[: info]

Something was found in an unconfigured or misconfigured state.
79 - 98 (custom configuration errors)

Configuration, property and setting errors defined by the developer. These should always be documented.
99 memory error[: info]

A general memory error occurred.
100 not enough [(heap|kernel) ]memory

There was not enough free memory (either heap or kernel memory) to perform an operation.
101 stack overflow error

A stack overflow occurred.
102 generic internal fault[: info]

General internal fault.
An internal fault happens when preconditions prevent the program to advance to a next stage of execution.
103 - 122 (custom internal faults)

Different internal faults, defined by the developer. These should always be documented.
123 emergency stop[: info]

The program was intentionally halted by the developer because a value is invalid and can't be worked with.
124 script was [not ]called interactively

The shell script can either only be executed interactively (using command "." or "source"), or not interactively (executing via "./").
125 unknown error

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)

Authors