How to lookup the meaning of exit codes for Linux command line utilities?

Question

I have my prompt (bash) configured to print out the exit code from the last command, if it wasn't successful (aka not zero). Therefore I'm seeing a lot of exit codes, even when a program seems to encounter no problems. Is there a way to lookup the meaning of these exit codes?

I always try the man pages, info pages or the "--help" option, but to no avail.

To clarify, I'm asking about the utilities that come with Linux, like cd, ls, du, ...

Answer 1

There isn't a standardized meaning for the exit codes of programs beyond '0 is OK; anything else means something went wrong'. And strictly, that applies to C and C++ only - there, exit(0); or exit(EXIT_SUCCESS); both exit with success, but the value returned to the O/S might be different.

There are exceptions to even the zero-on-success rule. Obviously, there are careless programs that don't return a defined exit status; such programs are best avoided. There are other not quite so careless programs that always return 0, even when something went wrong; they too are often best avoided.

However, there are also programs that carefully encode quite a lot of information into the exit status, and simply getting a non-zero exit status does not mean such programs failed. Of course, the programs document the meanings of the exit statuses.

POSIX is careful to document exit statuses for programs.

The manual pages for a program should document the exit statuses. On Unix, if there is no such documentation, then assume zero-on-success and anything else is a failure.

Note that if bash fails to execute a command, it will return stylized statuses:

• 127 if the file does not exist or cannot be found
• 126 if you do not have execute permission on the file

Also, if the program dies because of a signal, bash lets you know by encoding the exit status as:

• 128 + signal-number

Hence SIGHUP yields 129, SIGILL yields 132, SIGTERM yields 143, etc. However, it is possible for a program to exit with any of those statuses and mean something different from what bash means. That said, it is a relatively unusual program that exits with any of those exit statuses, so you're usually safe.

Note that different operating systems have different conventions: Unix provides an 8-bit status with zero for success; Windows provides a much larger range for the exit status values (16-bits or 32-bits); VMS used zero to mean failure, I believe.

Answer 2

The man pages are the conventional place for this documentation. If you are on e.g. Debian, you would even be expected to file a bug report against utilities which have undocumented exit codes.