Importance of carefully selected script exit code and Prevelant approaches for shell script in Linux

Introduction

Laymen explanation

If you are administrator who is running third party software, you must know the importance of error codes. You will use error codes to get idea of configuration problem, network problem, setup problem and all these without knowing internals of the software. If you are doing automation, then you will hook into return codes of these softwares and make your automation software logic based on this. What if a third party script returns success and later you found that the script always failed. Solution will eventually misbehave and you will notice is late (even too late).

Moreover If you are using software from multiple vendors, then your automation script will need to be using common approach to differentiate between successful execution and erreneous execution (Or else you need to program per vendor which will make your automation code dirty). This write-up helps in this regard.

Technical explanation

Why is this important? If you look at exit codes in the context of scripts written to be used for the command line the answer is very simple. Any script that is useful in some fashion will inevitably be either used in another script, or wrapped with a bash one liner. This becomes especially true if the script is used with automation tools like SaltStack or monitoring tools like Nagios, these programs will execute scripts and check the status code to determine whether that script was successful or not.

On top of those reasons, exit codes exist within your scripts even if you don't define them. By not defining proper exit codes you could be falsely reporting successful executions which can cause issues depending on what the script does.

What happens if I don't specify an exit code

In Linux any script run from the command line has an exit code. With Bash scripts, if the exit code is not specified in the script itself the exit code used will be the exit code of the last command run. To help explain exit codes a little better we are going to use a quick sample script.

Sample Script:

#!/bin/bash touch /root/test echo created file

The above sample script will execute both the touch command and the echocommand. When we execute this script (as a non-root user) the touch command will fail, ideally since the touch command failed we would want the exit code of the script to indicate failure with an appropriate exit code. To check the exit code we can simply print the $? special variable in bash. This variable will print the exit code of the last run command.

Execution:

$ ./tmp.sh touch: cannot touch '/root/test': Permission denied created file $ echo $? 0

As you can see after running the ./tmp.sh command the exit code was 0 which indicates success, even though the touch command failed. The sample script runs two commands touch and echo, since we did not specify an exit code the script exits with the exit code of the last run command. In this case, the last run command is the echo command, which did execute successfully.

Useful points

• • In Linux, exit code is always returned. By default, 0 is returned as exit code. In prevalence, When Linux returns 0, it means success. Anything else means failure.

  • stdlib.h does define EXIT_FAILURE as 1 and EXIT_SUCCESS as 0

  • A program has freedom to return exit code whatever they like, however common approach makes monitor program life easier in handling various cases.

  • The exit command in bash accepts integers from 0 - 255. Out of range exit values can result in unexpected exit codes. An exit value greater than 255 returns an exit code modulo 256. For example, exit 3809 gives an exit code of 225 (3809 % 256 = 225).

  • In most application cases, 0 (Success) and 1 (Failure) should be sufficient.

  • There has been an attempt to systematize exit status numbers. Please refer /usr/include/sysexits.h, which is intended for C and C++ programmers.

Reserved exit codes

These codes are collected from http://www.tldp.org/LDP/abs/html/exitcodes.html and it associates special values for few special error conditions.

Reference

http://stackoverflow.com/questions/1101957/are-there-any-standard-exit-status-codes-in-linux

http://bencane.com/2014/09/02/understanding-exit-codes-and-how-to-use-them-in-bash-scripts/

http://www.tldp.org/LDP/abs/html/exitcodes.html