CommonCodes v2.2.0

November 13, 2021

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 [: 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 instead 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 spotted option at this position with the 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)

The 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 minimum, 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: itemtype already exists

The item in question already exists and is of type itemtype.

26 item: not a[n] itemtype[[, itemtype]... or itemtype]

The item in question is of the wrong type.

27 program: program missing

An external program is required but could not have been found.
If program is not an absolute path, then the program could not have been found in the system PATH.

28 network error[: info]

A general network error occurred.

29 no network connection

No network connection is established.

30 connection timed out[: waited ms ms]

A network request took too long and timed out.
ms may be how many milliseconds were waited.

31 arithmetic error[: info]

A general arithmetic error occurred.

32 - 47 (custom feedback statuses)

Custom exit codes defined by the developer that aren't actually errors, but rather, feedback for the program user. These should always be documented.
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 - 97 (custom configuration errors)

Configuration, property and setting errors defined by the developer. These should always be documented.

98 path: too many levels of symbolic links

Too many symlinks were encountered when trying to resolve the realpath.

99 filename: filename too long

The name of the file is too long.
Important distinction: this should be a filename and NOT a pathname.

100 memory error[: info]

A general memory error occurred.

101 not enough [(heap|kernel) ]memory

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

102 stack overflow error

A stack overflow occurred.

103 generic internal fault[: info]

Generic internal fault.
An internal fault happens when preconditions prevent the program to advance to a next stage of execution.

104 - 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), glob(7), regex(7)

Authors