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.

Solution 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}

Solution 2

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

Comments

[Admin]

For part 3, do you mean returning from a shell function? That may depend on the shell, but I note that Bash's manual says "Exit statuses fall between 0 and 255" and "Exit statuses from shell builtins and compound commands are also limited to this range." return is, of course, a shell builtin.

[Admin]

Related (has answers to most of your questions): Default exit code when process is terminated?

[Admin]

@TobySpeight, that's a limitation of the bash shell. Some other shells like zsh can return any signed 32 bit value like for exit. Some like rc or es can return data of any of the types they support (scalar or list). See the linked Q&A for details.

[Ruslan]

Do you know if there's any discussion on implementing the full exit code in si_status for Linux?

[Stéphane Chazelas]

@Ruslan, not more than the austingroupbugs.net/view.php?id=594#c1318 (from Eric Blake (RedHat)) at the link I gave

[Admin]

To be precise, in some Bourne-like shells (but not bash or other most commonly used ones) the exit code passed to the exit builtin is not treated as modulo-256, and instead causes an error. (For example, the common exit -1 is actually not a portable equivalent to exit 255 in most shells). And whether exit(-1) at the C level is equivalent to exit(255) is a detail that is de-facto certain to work, but relies on implementation defined behavior (though this isn't a problem on modern systems you're likely to use in practice).

[IhtkaS]

"is of type int, so a 32bit integer". Linux really guarantees that an int will always be 32bit? Even when running on some of those tiny microcontrollers? That strikes me as really odd. POSIX certainly doesn't.

[Stéphane Chazelas]

@Voo, those tiny microcontrollers can't run Linux. While C requires int to be at least 16 bits, POSIX more or less requires it to be at least 32 bits and programming environments to have a uint32_t. I don't know if Linux supports any programming environment where ints are anything but 32bits, I've never come across any.

[Stéphane Chazelas]

@Voo, (continued) there's nothing stopping a compiler to provide 32bit integers on your microcontroller with 16bit registers, but there are likely going to be many other things preventing this controller from running an OS like Linux, the fact that it has only a few kilobytes of memory for instance.

[schily]

On a POSIX comliant OS, you may get the full 32 bit exit code in the recent version of the Bourne Shell, see: schillix.sourceforge.net/man/man1/bosh.1.html

[Admin]

From what I know, only ksh93 limits the exit(1) parameter to 8 bits.

[schily]

You have been right before 1989 when waitid() has been introduced.

[Damon]

@schily: Not sure what you mean? waitid() does just the same thing, slightly differently. It waits for a particular id or any thread, and it writes results to the pointed-to siginfo_t structure where si_status is int (so... signed, just the same). Still, exit() only passes the lowermost 8 bits, so... absolutely the same thing under the hood.

[schily]

exit() passes all 32 bits of the parameter to the kernel and waitid() returns all 32 bits from the exit code. Maybe you checked on Linux where nobody cares to fix bugs. If you don't believe me, check it on a POSIX complient OS...

[Damon]

@schily: If that is true (I don't think it is, but anyway), then Linux is broken. Please read the linked-to-in-answer POSIX specification of exit, in particular the second line under "Description" which states: "though only the least significant 8 bits (that is, status & 0377) shall be available to a waiting parent process". That is how a conforming implementation works -- lowermost 8 bits, not 32. Do you have a reference for 32 bits being passed on?

[schily]

I thought I mentioned that Linux is broken. Even worse: the Linux kernel people refuse to fix bugs. If you read the POSIX standard, you will find that the 1995 version (SUSv1) correcly explains the feature originally introduced by SVr4 in 1989 and that recent versions (e.g. SUSv7tc2) of the standard even explicitly explain that waitid() and the siginfo_t struct passed to the SIGCHLD handler return all 32 bits from the exit() parameter.

[mvorisek]

Is there any way to read full 32b exit code from command started in bash?