How do I get the list of exit codes (and/or return codes) and meaning for a command/utility?

Question

Is there a way I can do what stated in the title from the terminal commands, or will I have to look into the codes?

Answer 1

There is no "recipe" to get the meanings of an exit status of a given terminal command.

My first attempt would be the manpage:

user@host:~# man ls 
   Exit status:
       0      if OK,

       1      if minor problems (e.g., cannot access subdirectory),

       2      if serious trouble (e.g., cannot access command-line argument).

Second: Google. See wget as an example.

Third: The exit statuses of the shell, for example bash. Bash and it's builtins may use values above 125 specially. 127 for command not found, 126 for command not executable. For more information see the bash exit codes.

Answer 2

Exit codes indicates a failure condition when ending a program and they fall between 0 and 255. The shell and its builtins may use especially the values above 125 to indicate specific failure modes, so list of codes can vary between shells and operating systems (e.g. Bash uses the value 128+N as the exit status). See: Bash - 3.7.5 Exit Status or man bash.

In general a zero exit status indicates that a command succeeded, a non-zero exit status indicates failure.

To check which error code is returned by the command, you can print $? for the last exit code or ${PIPESTATUS[@]} which gives a list of exit status values from pipeline (in Bash) after a shell script exits.

There is no full list of all exit codes which can be found, however there has been an attempt to systematize exit status numbers in kernel source, but this is main intended for C/C++ programmers and similar standard for scripting might be appropriate.

Some list of sysexits on both Linux and BSD/OS X with preferable exit codes for programs (64-78) can be found in /usr/include/sysexits.h (or: man sysexits on BSD):

0   /* successful termination */
64  /* base value for error messages */
64  /* command line usage error */
65  /* data format error */
66  /* cannot open input */
67  /* addressee unknown */
68  /* host name unknown */
69  /* service unavailable */
70  /* internal software error */
71  /* system error (e.g., can't fork) */
72  /* critical OS file missing */
73  /* can't create (user) output file */
74  /* input/output error */
75  /* temp failure; user is invited to retry */
76  /* remote error in protocol */
77  /* permission denied */
78  /* configuration error */
/* maximum listed value */

The above list allocates previously unused exit codes from 64-78. The range of unallotted exit codes will be further restricted in the future.

However above values are mainly used in sendmail and used by pretty much nobody else, so they aren't anything remotely close to a standard (as pointed by @Gilles).

In shell the exit status are as follow (based on Bash):

• 1-125 - Command did not complete successfully. Check the command's man page for the meaning of the status, few examples below:

• 1 - Catchall for general errors

  Miscellaneous errors, such as "divide by zero" and other impermissible operations.

  Example:

  $ let "var1 = 1/0"; echo $?
  -bash: let: var1 = 1/0: division by 0 (error token is "0")
  1
  

• 2 - Misuse of shell builtins (according to Bash documentation)

  Missing keyword or command, or permission problem (and diff return code on a failed binary file comparison).

  Example:

   empty_function() {}
  

• 6 - No such device or address

  Example:

  $ curl foo; echo $?
  curl: (6) Could not resolve host: foo
  6
  

• 124 - command times out

• 125 - if a command itself fails^{see: coreutils}

• 126 - if command is found but cannot be invoked (e.g. is not executable)

  Permission problem or command is not an executable.

  Example:

  $ /dev/null
  $ /etc/hosts; echo $?
  -bash: /etc/hosts: Permission denied
  126
  

• 127 - if a command cannot be found, the child process created to execute it returns that status

  Possible problem with $PATH or a typo.

  Example:

  $ foo; echo $?
  -bash: foo: command not found
  127
  

• 128 - Invalid argument to exit

  exit takes only integer args in the range 0 - 255.

  Example:

  $ exit 3.14159
  -bash: exit: 3.14159: numeric argument required
  

• 128-254 - fatal error signal "n" - command died due to receiving a signal. The signal code is added to 128 (128 + SIGNAL) to get the status (Linux: man 7 signal, BSD: man signal), few examples below:

• 130 - command terminated due to Ctrl-C being pressed, 130-128=2 (SIGINT)

  Example:

  $ cat
  ^C
  $ echo $?
  130
  

• 137 - if command is sent the KILL(9) signal (128+9), the exit status of command otherwise

  kill -9 $PPID of script.

• 141 - SIGPIPE - write on a pipe with no reader

  Example:

  $ hexdump -n100000 /dev/urandom | tee &>/dev/null >(cat > file1.txt) >(cat > file2.txt) >(cat > file3.txt) >(cat > file4.txt) >(cat > file5.txt)
  $ find . -name '*.txt' -print0 | xargs -r0 cat | tee &>/dev/null >(head /dev/stdin > head.out) >(tail /dev/stdin > tail.out)
  xargs: cat: terminated by signal 13
  $ echo ${PIPESTATUS[@]}
  0 125 141
  

• 143 - command terminated by signal code 15 (128+15=143)

  Example:

  $ sleep 5 && killall sleep &
  [1] 19891
  $ sleep 100; echo $?
  Terminated: 15
  143
  

• 255* - exit status out of range.

  exit takes only integer args in the range 0 - 255.

  Example:

  $ sh -c 'exit 3.14159'; echo $?
  sh: line 0: exit: 3.14159: numeric argument required
  255
  

According to the above table, exit codes 1 - 2, 126 - 165, and 255 have special meanings, and should therefore be avoided for user-specified exit parameters.

Please note that out of range exit values can result in unexpected exit codes (e.g. exit 3809 gives an exit code of 225, 3809 % 256 = 225).

See:

• Appendix E. Exit Codes With Special Meanings at Advanced Bash-Scripting Guide
• Writing Better Shell Scripts – Part 2 at Innovationsts

Answer 3

You will have to look into the code/documentation. However the thing that comes closest to a "standardization" is errno.h

Answer 4

As far as I know, there are only two, more-or-less, standard values -- both defined in stdlib.h for use with exit():

• EXIT_SUCCESS (=0)
• EXIT_FAILURE (=1)

And the only de-facto standard value, i.e., having the same meaning for all programs in the world, is 0 (zero) which stands for SUCCESS.

Different programs introduce different lists of returned "failure"-codes to distinguish or emphasize different errors (different types or severity). Some programs even use the returned value to report the integer number of discovered runtime errors (e.g., the number of failed unit-tests in the suit).

I wouldn't recommend to introduce any kind of "new standard" extending the stdlib.h