1. Overview
In Linux, when a process is terminated, it returns an exit code. Upon successful execution, this code is equal to zero. Any non-zero exit code indicates that some error occurred.
Although we’re free to choose what exit codes we use in our scripts and programs, there are some standard codes that have a special meaning. In this tutorial, we’ll have a look at these codes and what they mean.
2. Exit Codes
In shell scripts, we use the exit command to generate exit codes. By using different exit codes for different errors, we can give an indication of what went wrong.
The exit command takes one argument, the exit code we want to use. For example:
$ bash -c "exit 42"
$ echo $?
42As we’ve already learned from the overview, some exit codes have special meanings. However, this doesn’t mean we can’t use them. They’re special, not reserved.
Also, some special codes might have different meanings in different shells. The examples in this article apply to the Bash shell.
3. Special Exit Codes
Let’s have a look at some special codes.
3.1. General Error: 1
This is the most used exit code and should be used as a catch-all value for miscellaneous errors.
3.2. Misuse of Shell Built-in: 2
Exit code 2 signifies invalid usage of some shell built-in command. Examples of built-in commands include alias, echo, and printf.
3.3. Cannot Execute: 126
In this case, the command invoked can’t be executed. This will most likely occur when there’s a permission problem or the command isn’t executable.
3.4. Command Not Found: 127
A command couldn’t be found. This may happen, for example, because there was a typo or an issue with our PATH.
3.5. Invalid Argument To Exit: 128
The exit command only takes a positive integer as its argument. This means any negative, fractional, or non-numeric values aren’t allowed.
3.6. Fatal Error Signal ‘n‘: 128+n
In Linux, programs might send one of 33 different signals. When a program terminates after receiving one of these signals, it will return an error code equal to 128 + signal-number.
For example, when we terminate a program by typing Control-C, we’re effectively sending it a SIGINT signal. This signal has a value of 2, therefore, the program will stop its execution and return an exit code with a value 128 + 2 = 130.
3.7. Exit Status Out of Range: 255
Depending on our shell, exit code 255 might mean that the returned exit code is outside of the 0-255 range.
4. Exit Codes Above 255
Because exit codes are represented by a single byte value, the highest possible exit code is 255. However, nothing prevents us from returning exit codes larger than this. Values over 255 are out of range and get wrapped around.
We should be very careful as this can be a source of unexpected results. For example, the exit code of 383 will be wrapped around and result in an effective exit code of 127, which translates to “command not found”:
$ bash -c "exit 383"
echo $?
127While it’s allowed to return exit values over 255, it’s better to avoid it at all times.
5. Conclusion
In this article, we’ve learned which exit codes should be treated as reserved and when we can use them in the scripts and programs we write. Some of them we should never use as it would be very confusing for our users.
We have to remember that different shells might have different special exit codes. This is something to be aware of.
Also, when writing programs or scripts, we should document the exit codes we use as a courtesy to our users.