J^T: John Thywissen's personal pages

exit() status and main() return codes

List of standard exit status values

Per ANSI C, POSIX, and BSD sysexits.h:

Value Symbol Description
Program terminated successfully
1 EXIT_FAILURE Generic program terminated unsuccessfully code. Also used by many shells when a command fails during word expansion or redirection.
2 to 63 Other failure, implementation/program defined
64 EX_USAGE Command line usage error
65 EX_DATAERR Data format error: "The input data was incorrect in some way. This should only be used for user's data and not system files."
66 EX_NOINPUT Cannot open input: "An input file (not a system file) did not exist or was not readable."
67 EX_NOUSER "The user specified did not exist. This might be used for mail addresses or remote logins."
68 EX_NOHOST Host name unknown
69 EX_UNAVAILABLE Service unavailable: "This can occur if a support program or file does not exist."
70 EX_SOFTWARE "An internal software error has been detected. This should be limited to non-operating system related errors as possible."
71 EX_OSERR System error (e.g., can't fork)
72 EX_OSFILE "Some system file does not exist, cannot be opened, or has some sort of error."
73 EX_CANTCREAT "A (user specified) output file cannot be created."
74 EX_IOERR Input/output error
75 EX_TEMPFAIL Temp failure; user is invited to retry
76 EX_PROTOCOL "The remote system returned something that was 'not possible' during a protocol exchange."
77 EX_NOPERM Permission denied: "This is not intended for file system problems, which should use EX_NOINPUT or EX_CANTCREAT, but rather for higher level permissions."
78 EX_CONFIG Configuration error: "Something was found in an unconfigured or misconfigured state."
126 Command not executable
127 Command not found
128 to 255 Terminated by signal; Exit status value is signo+128

NOTE: Only the lower 8 bits of the exit status value are used, even though exit statuses are often declared as int.

Quoted text above comes from the BSD sysexits(3) man page.

Usage of exit status codes

There is an important relationship between exit status values and the use of standard error:

If a program processes multiple files, or walks a directory tree, if the program encounters an error on a file, it should send a diagnostic message to standard error, and keep on trying the other files. When the program finishes, it must exit with a non-zero exit status.

Diagnostic message recommended format:
progname: pathname: SEVERITY: Message
Where progname is the basename of the program; pathname (if applicable) is the path to the input file with the problem; SEVERITY is HALT, ERROR, WARNING, or INFO; and Message is a description of the failure.

Remember that diagnostic messages may be generated in the midst of a long pipeline of commands processing multiple files, so they should indicate context of the problem.