Skip to content
Tutorials Center
My learning

Topics

Linux Command Reference ยท Bash Syntax

Bash exit status

Reference for shell exit status: what $? holds, the meaning of codes 0, 1, 2, 126, 127 and 128+N, how to set a status with exit and return, and how to test it.

Every command finishes with a number between 0 and 255 called its exit status. By convention 0 means success and anything else means some kind of failure. The shell stores the status of the most recent command in the special parameter $?, and control structures such as if, while, && and || decide what to do by testing it.

Because a status is just a small integer, the useful part is knowing the conventions: which numbers the shell itself produces, which ones programs usually agree on, and which pitfalls change the value before you read it.

Terminal
command
echo "status: $?"
if command; then echo ok; else echo "failed with $?"; fi

Try it

Bash Reading and setting statuses

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Codes produced by the shell

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
$?                     # status of the last foreground command
exit [N]               # leave the shell with status N (default: status of last command)
return [N]             # leave a function or sourced file with status N
${PIPESTATUS[@]}       # array with the status of each stage of the last pipeline
Name Description
0 Success.
1 General failure; the catch-all for "something went wrong".
2 Misuse of a shell builtin or invalid usage; also used by many tools for bad command-line options.
126 The command was found but cannot be executed (no permission, or not a program).
127 The command was not found.
128+N The process was terminated by signal N (130 = Ctrl+C / SIGINT, 137 = SIGKILL, 143 = SIGTERM, 139 = SIGSEGV).
255 Often "exit status out of range" or a generic fatal error.

Returns: an integer 0-255; larger or negative numbers wrap modulo 256.

Errors and edge cases: a non-numeric argument such as exit abc prints an error and gives status 2, and return outside a function or sourced script is an error.

Usage notes

  • Read $? immediately. Any later command, even echo or [ ], replaces it. Save it first when you need it twice: rc=$?.
  • if cmd beats cmd; if [ $? -eq 0 ]. The shorter form is clearer and also works under set -e.
  • Pipelines. Without pipefail a pipeline's status is the last command's only. See set -euo pipefail.
  • Command substitution. x=$(cmd) sets $? to cmd's status, but local x=$(cmd) or export x=$(cmd) returns the status of local or export instead, hiding failures. Declare first, assign afterwards.
  • Choose meaningful codes in your scripts. 0 for success, 1 for ordinary failure, 2 for bad usage, and a small documented range (3-125) for specific errors. Avoid 126-255, which have meanings of their own.
  • grep and diff. Both use 1 for "no match" / "differences" and 2 for real errors, so check for 2 separately when it matters.
  • A return inside $( ) or a pipe affects only that subshell.
  • exit in a trap sets the final status; a plain exit with no argument inside an EXIT trap keeps the status that triggered it.