In the manpages of diff(1), the exit status is described in the running text:
“FILES are 'FILE1 FILE2' or 'DIR1 DIR2' or 'DIR FILE' or 'FILE DIR'. If --from-file or --to-file is given, there are no restrictions on FILE(s). If a FILE is '-', read standard input. Exit status is 0 if inputs are the same, 1 if different, 2 if trouble.”
However, the standard of manpages (cf. `man man-pages`) is to have an extra subsection for it, namely, EXIT STATUS. While some other commands might hypothetically have their reasons for an exception (e.g., if an exit status is hard to describe independently of the provided options), this seems not to be the case for diff(1).
To satisfy the form and write a full English sentence:
“
EXIT STATUS
The exit status is 0 if the inputs are the same, 1 if they are different, and 2 if there is trouble.
”
However, such a specification is technically broken, as demonstrated by a situation in which there is trouble and the comparison itself finished without errors. (Example: printing to stdout or stderr failed). According to the current specification, “0 if inputs are the same, 1 if different, 2 if trouble”, diff would have to yield both [0 or 1] AND 2 simultaneously.
A clear suggestion of how diff(1) should behave:
“
EXIT STATUS
The exit status is
- 0 if the inputs are the same and no trouble occurred,
- 1 if the inputs are different and no trouble occurred, and
- >= 2 if there is trouble. The exit status is set according to sysexits.h(3).
”
This is still improvable. In the case of an error, it's possible to use the numbers unused above, i.e., the natural numbers in [0,127] \ ([0,1] U [EX__BASE, EX__MAX]); we use numbers below 128, as, according to bash(1), bit 8 is reserved to indicate getting terminated by a signal. One simple way is to use bits 4 and 5 to indicate whether the comparison itself terminated successfully with a conclusive result (inputs equal/unequal) and what the result is. Here is an improved clear suggestion:
“
EXIT STATUS
The exit status is
- 0 if the inputs are the same and no trouble occurred.
- 1 if the inputs are different and no trouble occurred.
- >= 2 if there is some trouble. If the exit code is <= 127:
* The bitwise AND of the exit status with 1001111 provides us with the error code to be interpreted as in sysexits.h(3).
* Bit 5 of the exit status tells us whether the comparison itself has finished successfully with a definite result:
- 0 means that the comparison attempt has not yielded a conclusive result.
- 1 means that the comparison has terminated with a conclusive result. In this case, bit 4 shows us the result:
* 0 means that the inputs are equal, and
* 1 means that the inputs are unequal.
”