Exit Statuses & Return Codes
The course is part of this learning path
In this Course, you will learn how to determine the exit status of a given command. You'll learn how to make decisions in your scripts based on the exit statuses of various commands. Finally, you'll learn how to use exit statuses in your own scripts. We'll take a look at a demonstration that will give you a practical understanding of using exit statuses.
- Determine the exit status of a given command.
- Make decisions in your scripts based on exit statuses of commands.
- Use exit statuses in your own scripts.
This Course is intended for anyone looking to learn more about bash scripting and shell programming.
To get the most out of this Course, you should have some basic knowledge of the command line, but it's not essential.
In this lesson, you will learn how to determine the exit status of a given command. You'll learn how to make decisions in your scripts based on the exit statuses of various commands. Finally, you'll learn how to use exit statuses in your own scripts.
Every time a command is executed, it returns an exit status. The exit status, which is sometimes called a return code or exit code is an integer ranging from zero to 255 by convention commands that execute successfully return a zero exit status. If some sort of error is encountered than a non-zero exit status is returned. These return codes can be used in new script for error checking. It can be a simple check, like checking for a zero return code, or it could be more complex like checking for a specific error code.
If you want to find what the various exit statuses mean you have to consult the documentation for the given command or look at its source code. You can use the main command or info commands to read the documentation from most commands on your system. For example, in the grep man page I can see that it will exit with a status of zero. If the search pattern is found, and one if the search pattern is not found.
The special variable dollar sign question mark contains the return code of the previously executed command. In this shell script, the ls command is called with a path to a file that doesn't exist. Immediately after the ls command is executed. The return code of that command is displayed on the screen using echo dollar sign question mark. This will display a two to the screen. Remember that non-zero exit codes indicate some sort of error had the file slash not slash here existed. And LS was able to display information about that file successfully. The exit status would have been zero.
You can use an exit status of a command to make a decision or perform a different action based on the exit status. In this example, shell script snippet we use the ping command to test our network connectivity to google.com. The - c option for the ping command simply tells ping to send just one packet. After the ping command is executed we check the exit status. If the exit status is equal to zero then we echo to the screen that google.com is reachable. If the exit status is not equal to zero we echo to the screen that google.com is unreachable. This example just checks for an error condition. In the if statement, we look for a non-zero exit status. If dollar sign question mark does not equal zero then we echo that the host is unreachable. If the ping command succeeds and returns a zero exit status then the echo statement is not executed. We can assign the return code of a command to a variable and then use that variable later in the script. In this example, the value of dollar sign question mark is assigned to the return underscore code variable. So return under source code contains the exit status of the ping command.
In addition to using if statements with exit statuses you can use logical ANDs and ORs the double ampersand represents and while the double pipe represents or. You can chain together multiple commands with either ANDs or ORs the command following a double ampersand will only execute if the previous command succeeds. Said another way the command following a double ampersand will only run if the previous command exits with a zero exit status.
In the example on the screen makdir slash tmp slash bak is executed. If it succeeds and returns to zero exit status, then and only then will the cp command be executed. In this example, you can see that there is no need for the cp command to be executed. If the directory wasn't able to be created the command following a double pipe will only execute if the previous command fails. If the first command returns a non-zero exit status then the next command is executed. And the, or example, the first cp command cp test dot txt slash tmp slash bak is executed. If it succeeds, the next cp command is not executed. In this example, if the first cp command succeeds then we have successfully created a backup copy of test dot txt. So there's no need for another backup copy of that file. If the first command fails, however then the second command is executed. In this example, if tests dot txt can't be copied into slash tmp slash bak then an attempt will be made to copy it to slash tmp within or only one of the two commands will successfully execute.
Let's revisit our earlier example, instead of using an if statement here we are using an and, in this example if the ping command exits with a zero exit status then google.com reachable will be echoed to the screen. Here we are using an or instead of an if statement. In this example, if the ping command fails then google.com unreachable will be echoed to the screen. If the ping command succeeds then the echo statement will not be executed.
If you want to chain multiple commands together on a single line, you can do that by separating those commands with a semicolon. The semicolon does not check the exit status of the previous command the command following a semicolon will always get executed no matter if the previous command failed or succeeded in essence commands with a semicolon is the same as putting those commands on separate lines. I rarely use semicolons to separate commands and shell scripts but you might see this in existing shell scripts. Of course, you can always use the syntax on the command line, outside of a shell script not only do normal commands, return and exit status but shell scripts do as well.
You can control the exit status of your shell script by using the exit command. Simply use the exit command in your script and follow it with a number from zero to 255. If you do not specify a return code with the exit command then the exit status of the previously executed command is used as the exit status. This is also true. If you do not include the exit command at all in your shell script, again, in that case the last command that was executed in your shell script will determine the return code of your entire shell script. You can use the exit command anywhere in your shell script. Whenever the exit command is reached your shell script will stop running.
In this example, we are controlling the exit status of our script with the exit command. If the ping command succeeds a return code of zero is received. This means that the test and the if statement is false and the code block will not execute. This means that the exit zero line is executed. This stops the execution of our script and returns to zero as the exit status. If the ping command fails then a non-zero exit status is received. This makes the if statement true and the echo command and exit 1 commands are executed. The exit 1 command will stop the execution of the script and return and exit status of one.
Now your shell script can be called by another script and its exit status can be examined just like any other command. Since you control the exit statuses you can make them have a significant meaning. Maybe your return code of one means that one type of error occurred while a return code of two means that a different type of error occurred. If you have scripts that are executing other scripts then you can program accordingly to these return codes. If you need or want to.
In this lesson, you learned that all commands return and exit status valid exit statuses are numbers that range from zero to 255 an exit status of zero represents the successful execution of a command and a non-zero exit status represents some type of error condition. You learned about this special variable dollar sign question mark and how it contains the value of the exit status of the previously executed command. You made decisions using the exit status of commands by using if statements ANDs and ORs. Finally, you learned how to control the exit status of your own shell scripts by using the exit command.
Jason is the founder of the Linux Training Academy as well as the author of "Linux for Beginners" and "Command Line Kung Fu." He has over 20 years of professional Linux experience, having worked for industry leaders such as Hewlett-Packard, Xerox, UPS, FireEye, and Amazon.com. Nothing gives him more satisfaction than knowing he has helped thousands of IT professionals level up their careers through his many books and courses.