What is the min and max values of exit codes in Linux?

Question

What is the min and max values of the following exit codes in Linux:

1. The exit code returned from a binary executable (for example: a C program).
2. The exit code returned from a bash script (when calling exit).
3. The exit code returned from a function (when calling return). I think this is between 0 and 255.

Answer 1

The number passed to the _exit()/exit_group() system call (sometimes referred as the exit code to avoid the ambiguity with exit status which is also referring to an encoding of either the exit code or signal number and additional info depending on whether the process was killed or exited normally) is of type int, so on Unix-like systems like Linux, typically a 32bit integer with values from -2147483648 (-2³¹) to 2147483647 (2³¹-1).

However, on all systems, when the parent process (or the child subreaper or init if the parent died) uses the wait(), waitpid(), wait3(), wait4() system calls to retrieve it, only the lower 8 bits of it are available (values 0 to 255 (2⁸-1)).

When using the waitid() API (or a signal handler on SIGCHLD), on most systems (and as POSIX now more clearly requires in the 2016 edition of the standard (see _exit() specification)), the full number is available (in the si_status field of the returned structure). That is not the case on Linux yet though which also truncates the number to 8 bits with the waitid() API, though that's likely to change in the future.

Generally, you'd want to only use values 0 (generally meaning success) to 125 only, as many shells use values above 128 in their $? representation of the exit status to encode the signal number of a process being killed and 126 and 127 for special conditions.

You may want to use 126 to 255 on exit() to mean the same thing as they do for the shell's $? (like when a script does ret=$?; ...; exit "$ret"). Using values outside 0 -> 255 is generally not useful. You'd generally only do that if you know the parent will use the waitid() API on systems that don't truncate and you happen to have a need for the 32bit range of values. Note that if you do a exit(2048) for instance, that will be seen as success by parents using the traditional wait*() APIs.

More info at:

• Default exit code when process is terminated?

That Q&A should hopefully answer most of your other questions and clarify what is meant by exit status. I'll add a few more things:

A process cannot terminate unless it's killed or calls the _exit()/exit_group() system calls. When you return from main() in C, the libc calls that system call with the return value.

Most languages have a exit() function that wraps that system call, and the value they take, if any is generally passed as is to the system call. (note that those generally do more things like the clean-up done by C's exit() function that flushes the stdio buffers, runs the atexit() hooks...)

That's the case of at least:

$ strace -e exit_group awk 'BEGIN{exit(1234)}'
exit_group(1234)                        = ?
$ strace -e exit_group mawk 'BEGIN{exit(1234)}'
exit_group(1234)                        = ?
$ strace -e exit_group busybox awk 'BEGIN{exit(1234)}'
exit_group(1234)                        = ?
$ echo | strace -e exit_group sed 'Q1234'
exit_group(1234)                        = ?
$ strace -e exit_group perl -e 'exit(1234)'
exit_group(1234)                        = ?
$ strace -e exit_group python -c 'exit(1234)'
exit_group(1234)                        = ?
$ strace -e exit_group expect -c 'exit 1234'
exit_group(1234)                        = ?
$ strace -e exit_group php -r 'exit(1234);'
exit_group(1234)                        = ?
$ strace -e exit_group zsh -c 'exit 1234'
exit_group(1234)

You occasionaly see some that complain when you use a value outside of 0-255:

$ echo 'm4exit(1234)' | strace -e exit_group m4
m4:stdin:1: exit status out of range: `1234'
exit_group(1)                           = ?

Some shells complain when you use a negative value:

$ strace -e exit_group dash -c 'exit -1234'
dash: 1: exit: Illegal number: -1234
exit_group(2)                           = ?
$ strace -e exit_group yash -c 'exit -- -1234'
exit: `-1234' is not a valid integer
exit_group(2)                           = ?

POSIX leaves the behaviour undefined if the value passed to the exit special builtin is outside 0->255.

Some shells show some unexpected behaviours if you do:

• bash (and mksh but not pdksh on which it is based) takes upon itself to truncate the value to 8 bits:

  $ strace -e exit_group bash -c 'exit 1234'
  exit_group(210)                         = ?
  

  So in those shells, if you do want to exit with a value outside of 0-255, you have to do something like:

  exec zsh -c 'exit -- -12345'
  exec perl -e 'exit(-12345)'
  

  That is execute another command in the same process that can call the system call with the value you want.

• as mentioned at that other Q&A, ksh93 has the weirdest behaviour for exit values from 257 to 256+max_signal_number where instead of calling exit_group(), it kills itself with the corresponding signal¹.

  $ ksh -c 'exit "$((256 + $(kill -l STOP)))"'
  zsh: suspended (signal)  ksh -c 'exit "$((256 + $(kill -l STOP)))"'
  

  and otherwise truncates the number like bash/mksh.

---

^{¹ That's likely to change in the next version though. Now that the development of ksh93 has been taken over as a community effort outside of AT&T, that behaviour, even though encouraged somehow by POSIX, is being reverted}

Answer 2

The minimum is 0, and that's considered the success value. All the other ones are failure. The maximum is 255 also known as -1.

These rules apply for both scripts and other executables, as well as shell functions.

Bigger values result to modulo 256.

Answer 3

This looks so simple, but oh teh woes.

The C language (and following that most other languages directly or indirectly) requires that returning from main be equivalent to calling exit with the same argument as the return value. This is an integer (the return type is very clearly int), so in principle the range would be INT_MIN to INT_MAX.

However, POSIX states that only the lowermost 8 bits passed to exit shall be made available to a waiting parent process, literally as if it was "status & 0xFF".
So, in practice, the exit code is a (still signed) integer of which only the lowest 8 bits are set.

The minimum will thus be -128, and the maximum 127. Hang on, that's not true. It will be 0 to 255.

But alas, of course it cannot be that simple. In practice, Linux (or rather bash) does it differently. The valid range of return codes is 0 to 255 (i.e. unsigned).

To be on the safe side in terms of avoiding confusion, it's probably a good idea to just assume that return codes are unsigned, and cast anything you get back from wait to unsigned. That way it's consistent with what you see in a shell. Since the topmost bits (including the most significant one) are cleared out, that's not even "wrong" because although technically signed, the actual values are always unsigned (since the sign bit is never set).
It also helps avoiding the common error of comparing an exit code to -1, which for some strange reason never seems to appear even when a program exits with -1 (well, guess why!).

About your last point, returning from a function, if this function happens to be main, then see above. Otherwise, it depends on what the function's return type is, it could in principle be anything (including void).

Answer 4

1. The exit code returned from a binary executable (for example: a C program).
2. The exit code returned from a bash script (when calling exit).

Exit codes from any process -- whether it's a binary executable, a shell script, or anything else -- range from 0 to 255. It's possible to pass a larger value to exit(), but only the lower 8 bits of the status are made available to other processes through wait().

3. The exit code returned from a function (when calling return). I think this is between 0 and 255.

A C function can be declared as returning almost any type. The limits of its return value are determined entirely by that type: for instance, -128 to 127 for a function returning signed char, or 0 to 4.2 billion for a function returning unsigned int, or any floating-point number up to and including inf for a function returning double. And that isn't counting the non-numeric types, like void * or a struct...