14

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?

12

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.

  • yeah some man, info, ... pages do include them.. and I was concerned with those who didn't. ..and I know a web research is always an option. ..as for now it appears it was just the bash exit codes I had to look for.. – precise Jan 22 '14 at 9:09
11

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 failssee: 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:

  • errno values are used by system APIs, they are not use as exit statuses (they aren't even in the right range) and they're irrelevant for shell scripting. Sysexits values are from sendmail and used by pretty much nobody else, they aren't anything remotely close to a standard. – Gilles Sep 7 '16 at 0:27
7

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

  • thanks for pointing the header file.. tried looking into the documentation of a few utils.. hard time finding the exit codes, seems most will be the stderrs... – precise Jan 22 '14 at 9:13
  • 3
    errno.h is irrelevant when it comes to exit codes, only error messages. – Gilles Jan 22 '14 at 23:41
  • Most programs return exit codes according to the BSD convention, as laid out in sysexits.h. However, some programs do return errnos, and I actually think returning errnos makes the most sense. Unhandled errnos propagate upwards, like exceptions, (the errno stays, functions return e.g., -1 or 0|NULL). Since programs are just functions, albeit functions that are run in a separate address space, it makes sense that a program might wish to continue the errno propagation across the process boundary. – PSkocik Jan 12 '16 at 0:14
  • @PSkocik, do you have an example of such a command? errnos are not portable (values not consistent across systems), and there's no portable way to get the err name or message from the value (zsh has a builtin for that). Not to mention that some systems have errnos above 123 that would clash with common special-meaning error codes. Usually, commands print the messages from the errno and return a success/failure exit status. commands are intended for users. functions/system calls are intended for programmers. – Stéphane Chazelas Sep 7 '16 at 8:17
  • @StéphaneChazelas I've seen it a couple of times, but not in any well established programs, I have to admit. I've been personally returning errno+1 in my toy system lately ( so that 1 continues to mean "any error") because I think serializing errno's across the process boundary makes better sense than translating according to the BSD convention, as program executions are essentially function invocations, and functions use errno. I use my own last-exit-status decoder in my PROMPT_COMMAND (bash) so I get something like "($numeric_code|$bsd_decoded|$errno_plus_one_decoded)". – PSkocik Sep 7 '16 at 9:00
1

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

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.