15

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, ...

Jonathan Leffler
  • 730,956
  • 141
  • 904
  • 1,278
chrm
  • 1,258
  • 1
  • 11
  • 16
  • Read this: http://stackoverflow.com/questions/1101957/are-there-any-standard-exit-status-codes-in-linux Or browse to /usr/include/sysexits.h – Icarus Sep 03 '11 at 15:46
  • In man pages they are called "exit status". You mentioned `ls`: if I enter `man ls` and then perform a search typing `/exit status` I'm taken to the related paragraph. – etuardu Sep 03 '11 at 18:22
  • 4
    To those closing as 'off topic', this is about programming in the shell and what the exit statuses mean and therefore how to program around them. As such, it is completely on-topic for SO. If you were to close it as a duplicate of 1101957, I'd have some sympathy with you; the questions cover much the same ground (but when I checked, the 3 closes were all off-topic -- and erroneously so IMNSHO). – Jonathan Leffler Sep 03 '11 at 18:47

3 Answers3

16

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.

Jonathan Leffler
  • 730,956
  • 141
  • 904
  • 1,278
  • Can you name a program without exit status? What will `echo $?` report than? AFAIK, every program has an implicit return value. I agree on the `no standardisation`-part. – user unknown Sep 03 '11 at 19:04
  • I know of some programs that don't provide reliable exit statuses - more of the 'always 0 even when something went wrong' variety than 'some random (often non-zero) value unrelated to success or failure'. Said programs tend to be local, custom-built programs rather than well-known published programs; things like the exit status get cleaned up when the program becomes well-known. – Jonathan Leffler Sep 03 '11 at 19:22
1

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.

tripleee
  • 175,061
  • 34
  • 275
  • 318
1

The advanced Bash scripting guide also provides exit codes with special meanings.

http://tldp.org/LDP/abs/html/exitcodes.html#EXITCODESREF

Ken
  • 7,847
  • 1
  • 21
  • 20