Assign the exit code of a pipeline to a variable using `PIPESTATUS`

Mastering Pipelines in Bash: How to Use `PIPESTATUS` to Capture Exit Codes

In Linux Bash scripting, pipelines allow you to send the output of one command as the input to another. Understanding how exit statuses are managed across a pipeline is crucial for robust scripting, especially in error handling. Today, we’ll answer some pivotal questions about using PIPESTATUS to capture individual exit codes in a pipeline.

What is an exit code in Bash?

An exit code, or exit status, is a numerical value returned by a command or a script upon its completion. Typically, a 0 exit status signifies success, whereas any non-zero value indicates an error or an abnormal termination.

How does Bash handle exit codes in pipelines?

By default, the exit status of a pipeline (e.g., cmd1 | cmd2) is the exit status of the last command in the pipeline, cmd2 in this case. However, other commands in the pipeline may also fail but their exit statuses are not directly visible in the final exit status of the pipeline. This is where PIPESTATUS becomes useful.

What is `PIPESTATUS`?

PIPESTATUS is an array variable in Bash that holds the exit status of each command in a most-recently-executed foreground pipeline. It allows script writers to access the individual exit statuses of commands in a pipeline.

How do I use `PIPESTATUS`?

You can access the exit status of each component of the pipeline by referencing ${PIPESTATUS[n]}, where n is the index of the command within the pipeline (starting at 0).

Q&A Example:

Q: I have a pipeline cmd1 | cmd2. How can I assign the exit status of cmd1 to a variable?

A: You can assign the exit status of cmd1 to a variable by using PIPESTATUS as follows:

cmd1 | cmd2
exit_status_cmd1=${PIPESTATUS[0]}

Background on `PIPESTATUS`

PIPESTATUS is particularly useful in complex pipelines where you need to ensure that each command succeeds before proceeding. Let’s look at some simple examples to clarify its usage:

Example 1: Basic Usage

echo "hello" | grep "o"
echo ${PIPESTATUS[@]}

This will output:

0 0

Indicating that both echo and grep were successful.

Example 2: Error Handling in Pipelines

cat nonexistentfile | sort
echo ${PIPESTATUS[@]}

This results in:

1 0

Here, cat fails to open a non-existent file (exit status 1), while sort succeeds (exit status 0).

Executable Script: Demonstrating `PIPESTATUS`

To demonstrate the power of PIPESTATUS, here’s a script that executes a multi-command pipeline and checks each command’s success:

#!/bin/bash

# A fake command simulating a failure.
cmd1() { echo "Processing input..."; return 2; }

# A successful command.
cmd2() { sort; }

cmd1 | cmd2
echo "Exit status of cmd1: ${PIPESTATUS[0]}"
echo "Exit status of cmd2: ${PIPESTATUS[1]}"

if [ ${PIPESTATUS[0]} -ne 0 ]; then
    echo "Error: cmd1 failed with status ${PIPESTATUS[0]}"
fi

Conclusion

Understanding PIPESTATUS in Bash allows for sophisticated error handling and status monitoring in script pipelines. By utilizing PIPESTATUS, script developers gain detailed control over the flow and integrity of script execution, ensuring every step of the pipeline functions as intended. Whether building simple scripts or complex automation flows, PIPESTATUS is an invaluable tool in the bash scripting arsenal for effective error management and process control.

Mastering Pipelines in Bash: How to Use PIPESTATUS to Capture Exit Codes

What is an exit code in Bash?

How does Bash handle exit codes in pipelines?

What is PIPESTATUS?

How do I use PIPESTATUS?

Q&A Example:

Background on PIPESTATUS