What return/exit values can I use in bash functions/scripts?

Question

I want to know what return values we can use that will not be mistaken by for ex. SIGINT?

ex.:

$sleep 10
$#hit ctrl+c
$echo $?
130

so I know I must not use anything like return 130 or exit 130

so this would be misleading:

$function FUNC(){ return 130; };FUNC;echo $?
130

Solution 1

You can use any number between 0 to 255 except for reserved exit codes (click here to know more)

Solution 2

The exit status of a process is encoded as a value between 0 and 255, so that's all you can use as an exit code. If you pass a value outside that range, most shells use the remainder modulo 256. Some shells allow a wider range of integer values for functions.

The only rule for exit codes is that 0 means success and any other value means failure. This rule goes beyond unix: it's also a common convention on other operating systems (including DOS, Windows, and many embedded systems that have a notion of exit code, but VMS does things differently). In unix systems, it's baked into the shell's boolean constructs (if, while, &&, ||, !, set -e, …), into make, and followed by all the standard utilities. In POSIX C programs,EXIT_SUCCESS is 0 and EXIT_FAILURE is some non-zero value (usually 1).

There is no rule (de facto or de jure) regarding the choice of exit codes for failure. Only a few POSIX utilities mandate specific failure status codes:

• The ! shell operator returns 1 if its operand returns 0. The && and || operator pass the status from the last command.
• cmp and diff return 1 for different files and ≥2 for error conditions.
• expr returns 1 if the expression evaluates to zero or null, 2 for an invalid expression, and ≥3 for other errors.
• grep returns 1 for “not found” and ≥2 for error conditions. Many search commands follow this (but not find, which returns 0 if no file matches).
• mesg returns 0 for yes, 1 for no, and ≥2 for error.
• patch returns 1 if a hunk was rejected and ≥2 for other errors.
• sort -c returns 1 if the file data isn't sorted and ≥2 for errors.
• compress and localedef define some small values for specific errors.

There is a common, but not universal idea that larger values mean worse failures. For commands that test a boolean condition such as grep (is this pattern present?) and diff (are these files identical?), 1 means “no” and higher values indicate an error. In addition, values from 126 up are rarely used, as they are baked into the shell (and POSIX commands command, env, nice, nohup and time):

• 126 and 127 indicate a failure to invoke an external command;
• values above 128 in $? indicate a command that was terminated by a signal.

/usr/include/sysexits.h lists some values with their meanings, but it's from sendmail and I've never seen it outside programs that are unrelated to email delivery.

In summary, return 0 for success, and either 1 or 2 for failure. If you need to distinguish between failure cases, start at 1 and increase the value for worse failures.

Solution 3

Exit Status Conventions

Technically, you can use any value between 0 and 255. However, there are a number of existing conventions you can use:

• Exit code 1 as a catch-all for general errors.
• Exit codes 64-78 from sysexits.h to indicate the class of error. You can generally look these up in /usr/include/sysexits.h, which is installed by the Debian/Ubuntu libc6-dev package.
• Exit codes from errno.h. You can also look these up with the errno command from the moreutils package. On my system, running errno --list currently displays 134 defined errors.

Document and Display

In general, it's a good idea to document the exit codes used within your script, or at least which convention you're following. It may also be useful to display a distinctive message before exiting, such as:

# using sysexits.h
echo "EX_USAGE: invalid argument: $1" > /dev/stderr
exit 64

# using errno.h
echo "ENOENT: File not found: $file" > /dev/stderr
exit 2

Comments

[Aquarius Power]

despite it speaks against exit 1, I think it is ok for general non specific errors, but if we want to identify a certain exit value, it just must not be 1 or the others on the list you provided

[Aquarius Power]

here are that values copied to stackexchange sites unix.stackexchange.com/a/162682/30352

[Aquarius Power]

cool, so "2 Misuse of shell builtins (according to Bash documentation)" can basically be ignored, as it seems to only happen as an exit value of bash builtins right? in other words, if I always set the return/exit value properly, it will not be the value of the last executed command even if such is a bash builtin that could return 2. So I can safely go from 0 to 125 (as I will ever use that much hehe)! thx!

[Gilles 'SO- stop being evil']

@AquariusPower What do you mean by “misuse of shell builtins”?

[Gilles 'SO- stop being evil']

errno.h lists return codes for C functions. It is not used by external commands. The values depend on the flavor of unix and they aren't in the right range (0–125). As for sysexits.h, it's only used in a few email-related programs, it isn't a de facto standard for return codes.

[muru]

@Gilles see the link from the accepted answer (the ABS guide). It says code 2 is for misuse of shell builtins, such as a missing keyword.