How to use Linux shell command exit codes

When you execute a command in Linux, it generates a numeric return code. This happens whether you're running the command directly from the shell, from a script, or even from an Ansible playbook. You can use those return codes to handle the result of that command properly.

What the return codes mean

When running commands at a shell prompt, the special variable $? contains a number that indicates the result of the last command executed.

[ Download now: A sysadmin's guide to Bash scripting. ]

A zero (0) means everything went fine. Anything else means there is a problem.

A value of 1 generically indicates that some error has happened.

$ who
admin2   :1           2022-03-15 10:14 (:1)

$ echo $?
0

$ who | grep thisstringdoesnotexist

$ echo $?
1

In the example above, I executed the who command, which showed that I am admin2.

Immediately after that, I executed echo $?, and it returned zero because the previous command was executed successfully.

Then I executed the same who command (which I know is working fine) and piped that to grep with the non-existing argument. This time the $? variable contains a 1.

Why? It's because the last command executed was grep, which returns 1 when it cannot find the argument in its input.

[ Free eBook: Manage your Linux environment for success ]

Here is another example:

$ls myfile.cfg
ls: cannot access 'myfile.cfg': No such file or directory

$echo $?
2

Here I tried to list a file that doesn't exist. Then when I entered echo $? I got 2, which is how the ls command indicates that the argument is not a file or directory name.

Customize the return code

You can also use the exit command from a shell script to customize the return code to the caller script.

The following script illustrates this:

#!/bin/bash

if [ ! -f myfile.cfg ];
then
  echo The file does not exist and we display an error
  exit 64
fi

echo The file exists and we will do something
echo "(Not really doing anything, but this is where we could do it)"

exit 0

$./myscrypt.sh 
The file does not exist and we display an error

$echo $?
64

$touch myfile.cfg

$./myscrypt.sh 
The file exists and we will do something
(Not really doing anything, but this is where we could do it)

$echo $?
0

In this script, I explicitly provide the exit code for the failed and for the successful cases. Some observations:

1. If I do not explicitly use exit 0, the return code from myscript.sh will be the return code from the last command executed inside it. This could be what I want, but here I wanted to state the return code pretty clearly inside the script.
2. I used 64 as an arbitrary return code for the error condition. The Advanced Bash-Scripting Guide offers some guidelines about exit code values.

Test the return code with a shell script

If you need to test the return code of a command you invoked on your shell script, you just need to test the $? variable immediately after the command executes.

#!/bin/bash

# A snipet from a shell script ...
# Next we will invoke a command or another shell script

./myscript.sh

RETURN=$?

if [ $RETURN -eq 0 ];
then
  echo "The script myscript.sh was executed successfuly"
  exit 0
else
  echo "The script myscript.sh was NOT executed successfuly and returned the code $RETURN"
  exit $RETURN
fi 

In this example, after invoking my command or script, I saved the exit code from $? on a variable for further utilization. (Again, $? returns the status of the last command, so you need to be careful if you run more commands—even a simple echo.).

Test the return code with an Ansible playbook

It is recommended to avoid running shell commands from an Ansible playbook if there is an Ansible module that performs the same action. This is especially because with a module you have better odds of being idempotent.

[ Ready to start automating? Check out this Ansible quick start series. ]

To illustrate how to handle return codes from a shell command, check this simple playbook:

---
- name: Executes a shell script
  hosts: localhost
  gather_facts: no
  tasks:
  - name: Execute the shell script
    shell: ./myscript.sh
    ignore_errors: true
    register: result

  - name: Shows the result of executing the script
    debug:
      msg: 
      - "Return code...: {{ result.rc }}"
      - "{{ result.stdout_lines }}"

This is the Ansible playbook executed when a script returns an error:

[WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match
'all'

PLAY [Executes a shell script] *****************************************************************************************

TASK [Execute the shell script] ****************************************************************************************
fatal: [localhost]: FAILED! => {"changed": true, "cmd": "./myscript.sh", "delta": "0:00:00.003315", "end": "2022-06-13 15:35:06.123759", "msg": "non-zero return code", "rc": 64, "start": "2022-06-13 15:35:06.120444", "stderr": "", "stderr_lines": [], "stdout": "The file does not exist and we display an error", "stdout_lines": ["The file does not exist and we display an error"]}
...ignoring

TASK [Shows the result of executing the script] ************************************************************************
ok: [localhost] => {
    "msg": [
        "Return code...: 64",
        [
            "The file does not exist and we display an error"
        ]
    ]
}

PLAY RECAP *************************************************************************************************************
localhost                  : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=1   

I defined the task to ignore the error, so in the next task, I can simply display the return code and message from the script. I could also have handled the return code in my Ansible playbook by using the result.rc variable with some combination of the assert module or adding the when condition to another task.

Wrapping up

Now you have some knowledge about the return codes from commands and scripts invoked by your shell scripts and Ansible playbooks. I hope this helps you handle your scripts more easily.