Error levels: Difference between revisions
No edit summary |
|||
Line 65: | Line 65: | ||
{|class="wikitable sortable" | {|class="wikitable sortable" | ||
! Error Level !! Convention !! Meaning | ! Error Level !! Convention !! Category || Constant || Meaning | ||
|- | |- | ||
|id=0| 0 | |id=0| 0 || || success || EXIT_SUCCESS || success! | ||
|- | |- | ||
|id=1| 1 | |id=1| 1 || || generic || EXIT_GENERIC_1 || the generic "some problem occurred" value, prefer something more specific | ||
|- | |- | ||
|id=2| 2 | |id=2| 2 || || generic || EXIT_GENERIC_2 || incorrect usage or invalid arguments, the 404 of error levels | ||
|- | |- | ||
|id=126| 126 || UNIX || command was found but could not be executed due to permissions | |id=126| 126 || UNIX || UNIX || EXIT_NO_PERMISSION || command was found but could not be executed due to permissions | ||
|- | |- | ||
|id=127| 127 || UNIX || command not found or could not be executed | |id=127| 127 || UNIX || UNIX || EXIT_NO_COMMAND || command not found or could not be executed | ||
|- | |- | ||
|id=128| 128 || UNIX || process terminated by signal | |id=128| 128 || UNIX || UNIX || EXIT_TERMINATED_BY_SIGNAL || process terminated by signal | ||
|- | |- | ||
|id=130| 130 || UNIX || process terminated by Ctrl+C | |id=130| 130 || UNIX || UNIX || EXIT_TERMINATED_BY_CTRLC || process terminated by Ctrl+C | ||
|- | |- | ||
|id=255| 255 || | |id=255| 255 || || generic || EXIT_GENERIC_255 || the other generic "some problem occurred" value, prefer something more specific | ||
|} | |} | ||
Revision as of 11:02, 9 February 2024
I should have done this a long time ago. I'm going to start allocating standard error levels for my own use.
To be clear, these are process error levels, also known as exit status and error code. I endeavour to allocate particular error levels for my own use in the range [10, 100), comfortably in two-digit territory.
Note that I mostly program in PHP, so 'error', 'exception', and 'assertion' are particular to PHP, but they might apply in other contexts.
My error levels
These are some notes about error levels specifically nominated by me.
Error Level | Category | Constant | Meaning |
---|---|---|---|
10 | logic error | EXIT_CANNOT_CONTINUE | cannot continue; but nothing is abnormal or wrong |
20 | input error | EXIT_INPUT_ERROR | input error; invalid data or inputs |
21 | input error | EXIT_NO_FILE | no file; file/directory path not nominated |
40 | user error | EXIT_USER_ERROR | user error; invalid command-line or options |
41 | user error | EXIT_WRONG_FILE | wrong file; user nominated file (or directory) missing |
42 | user error | EXIT_BAD_FILE | invalid file; user nominated file (or directory) cannot be accessed due to invalid permissions |
60 | environment error | EXIT_BAD_ENVIRONMENT | invalid run-time environment; cannot run |
61 | environment error | EXIT_FILE_MISSING | file missing; file (or directory) missing |
62 | environment error | EXIT_NO_ACCESS | no access; file (or directory) cannot be accessed due to invalid permissions |
63 | environment error | EXIT_BAD_CONFIG | invalid configuration; config file missing or invalid |
76 | environment error | EXIT_NO_SERVICE | no service; cannot establish connection to service |
77 | environment error | EXIT_NO_DATABASE | no database; cannot establish connection to database |
78 | environment error | EXIT_EXHAUSTED | resources exhausted; out of memory, disk space, inodes, etc |
79 | environment error | EXIT_OFFLINE | system offline; as configured by administrator |
80 | program error | EXIT_PROBLEM | software problem; unhandled and fatal situation encountered |
81 | program error | EXIT_ERROR | program error; error caused process termination |
82 | program error | EXIT_EXCEPTION | program exception; exception caused process termination |
83 | program error | EXIT_ASSERT | assertion violation; assertion violation caused process termination |
84 | program error | EXIT_TEST_FAILED | test failed; unit-test did not succeed |
89 | program error | EXIT_INVALID | invalid error level; the programmer nominated an invalid error level and the host exited with 89 instead |
90 | special purpose | EXIT_SPECIAL_SUCCESS | special operation successful; used for safety (in case improperly invoked) |
98 | special purpose | EXIT_OPTIONS_LISTED | program options listed; use when programs can be invoked to list their options in a machine readable format |
99 | special purpose | EXIT_HELP | help or version number requested |
Other error levels
These are some notes about how other software uses error levels.
Error Level | Convention | Category | Constant | Meaning |
---|---|---|---|---|
0 | success | EXIT_SUCCESS | success! | |
1 | generic | EXIT_GENERIC_1 | the generic "some problem occurred" value, prefer something more specific | |
2 | generic | EXIT_GENERIC_2 | incorrect usage or invalid arguments, the 404 of error levels | |
126 | UNIX | UNIX | EXIT_NO_PERMISSION | command was found but could not be executed due to permissions |
127 | UNIX | UNIX | EXIT_NO_COMMAND | command not found or could not be executed |
128 | UNIX | UNIX | EXIT_TERMINATED_BY_SIGNAL | process terminated by signal |
130 | UNIX | UNIX | EXIT_TERMINATED_BY_CTRLC | process terminated by Ctrl+C |
255 | generic | EXIT_GENERIC_255 | the other generic "some problem occurred" value, prefer something more specific |
Error level range
The errors are in increasing order of should-not-happenness. Basically:
- logic error: cannot continue now, but nothing is wrong
- input error: invalid data
- user error: invalid options
- environment error: an environment problem, cannot connect to service or incompatible versions etc
- program error: shouldn't happen, a situation the code hasn't handled yet
Whether it's an input error, user error, or environment error is basically a decision for you to make. It's not super important which number you allocate, especially when multiple categories might apply. It's probably best if you try to blame the program or environment more and the user less.
Note that special purpose "success" codes are only used in situations where you want to protect the user from making a mistake. So if a version number is printed because there was a --version command-line argument; or help was printed because there was a --help command-line argument; or if a machine-readable list of options was requested and supplied; then we exit with a non-zero error level even though technically we haven't "failed", we just might have done something by accident that the use didn't expect or intend. The main reason for these options is that when you're running in bash with `set -e` enabled (and usually you should be for most non-interactive situations) then your script will stop if a process returns an error. So we return an error just in case we did something in a script that a user didn't intend. After all if they think they've successfully invoked a command, but all they've actually done is report the version number or displayed the program help text, they'd probably like to know!
Range | Category | Meaning |
1-9 | not much meaning, prefer don't use | |
10-19 | logic error | cannot continue now, but nothing is abnormal or wrong |
20-39 | input error | invalid data or inputs |
40-59 | user error | invalid command-line or options |
60-79 | environment error | improper run-time environment |
80-89 | program error | should not happen, unsupported situation |
90-99 | special purpose | success indicators, used for safety |
100+ | some have meanings in UNIX, otherwise don't use |
PHP code
Mostly it's on you as the programmer to pick a suitable error level and exit with it, but a function like this one might help a little bit:
if ( ! function_exists( 'kickass_exit' ) ) { function kickass_exit( $error = 0, $default = 50 ) { // 2023-03-31 jj5 - I try to use more or less standard error levels, this is a work in progress // but the documentation is here... // // 2023-03-31 jj5 - SEE: https://www.jj5.net/sixsigma/Error if ( is_int( $error ) ) { exit( $error ); } if ( is_a( $error, ErrorException::class ) ) { exit( 51 ); } if ( is_a( $error, AssertionError::class ) ) { exit( 53 ); } if ( is_a( $error, Throwable::class ) ) { exit( 52 ); } exit( $default ); } }
Unit tests
There is a code allocated for unit test failure, being 54. This constant might be used from shell scripts. In PHP code a unit test will usually fail via an error, exception, or assertion violation, in which case you can just return the appropriate error level, 51, 52, or 53. But if a unit test fails due to a logic situation you can exit with 54 if you want.
BASH code
# 2023-05-26 jj5 - SEE: https://www.jj5.net/sixsigma/Error_levels # EXIT_CANNOT_CONTINUE=10 # logic error: cannot continue; but nothing is abnormal or wrong EXIT_INPUT_ERROR=20 # input error: input error; invalid data or inputs EXIT_NO_FILE=21 # input error: no file; file/directory path not nominated EXIT_USER_ERROR=40 # user error: user error; invalid command-line or options EXIT_WRONG_FILE=41 # user error: wrong file; user nominated file (or directory) missing EXIT_BAD_FILE=42 # user error: invalid file; user nominated file (or directory) cannot be accessed due to invalid permissions EXIT_BAD_ENVIRONMENT=60 # environment error: invalid run-time environment; cannot run EXIT_FILE_MISSING=61 # environment error: file missing; file (or directory) missing EXIT_NO_ACCESS=62 # environment error: no access; file (or directory) cannot be accessed due to invalid permissions EXIT_BAD_CONFIG=63 # environment error: invalid configuration; config file missing or invalid EXIT_NO_SERVICE=76 # environment error: no service; cannot establish connection to service EXIT_NO_DATABASE=77 # environment error: no database; cannot establish connection to database EXIT_EXHAUSTED=78 # environment error: resources exhausted; out of memory, disk space, inodes, etc EXIT_OFFLINE=79 # environment error: system offline; as configured by administrator EXIT_PROBLEM=80 # program error: software problem; unhandled and fatal situation encountered EXIT_ERROR=81 # program error: program error; error caused process termination EXIT_EXCEPTION=82 # program error: program exception; exception caused process termination EXIT_ASSERT=83 # program error: assertion violation; assertion violation caused process termination EXIT_TEST_FAILED=84 # program error: test failed; unit-test did not succeed EXIT_INVALID=89 # program error: invalid error level; the programmer nominated an invalid error level and the host exited with 89 instead EXIT_SPECIAL_SUCCESS=90 # special purpose: special operation successful; used for safety (in case improperly invoked) EXIT_OPTIONS_LISTED=98 # special purpose: program options listed; use when programs can be invoked to list their options in a machine readable format EXIT_HELP=99 # special purpose: help or version number requested