Discourage the use of sysexits(3) in new code

[0mp]

Summary

Commit message:

Discourage the use of sysexits(3) in new code

This commit removes an incorrect statement from the sysexits(3) manual page
about the documented exit values being encouraged by style(9). This has not
been true since 2008 (r186224).

In addition, a new section is added at the top of the manual to discourage
developers from using sysexits(3) in new code.  The usual problems people
have with sysexits(3) is that they are not portable, it's hard to pick
a good value in most situations and that good error messages are probably
better anyway.

Obtained from:	OpenBSD (partially)

Related links:

• https://reviews.freebsd.org/D24224
• https://reviews.freebsd.org/rS186224
• https://reviews.freebsd.org/D24224

[0mp]

• Remove "preferable" from the manual page title

[jilles]

Exit statuses should implement a protocol between the calling and called process. Since only 8 bits (or 32 if the calling process uses waitid()) are available, there is not much flexibility. I think distinctions between different exit statuses should have a purpose, while most of the sysexits codes categorize errors without a clear purpose. If more flexibility is needed, a channel with more capacity should be used.

I think only EX_TEMPFAIL (75) has a clear and reasonably generic purpose, and I think it is fine to use it when the calling program expects this status, which requires the called program to be aware of the context to some degree. Alternatively, a temporary failure might be considered "false" (1) and a persistent failure "failure" (2), per the second below protocol. This would probably a more consistent way to write lockf(1) in 2020, but changing it now is probably not a good idea.

More portable conventions are as follows:

The two commonly used protocols are:

• 0 = success, >0 = failure
• 0 = true, 1 = false, >1 = failure

Additionally, there are common conventions when a program starts another:

• 126 if the other program was found but could not be run
• 127 if the other program could not be found
• 128 plus the signal number if the process terminated abnormally (note: POSIX only specifies "greater than 128" and that kill -l exitstatus can be used to find the signal's short name)

share/man/man3/sysexits.3

50–53

I don't think sysexits(3) has ever been meant to be a replacement of English error messages for human interpretation.

[freebsd_igalic.co]

In D27176#606806, @jilles wrote:

I think only EX_TEMPFAIL (75) has a clear and reasonably generic purpose,

when composing D27161 , i found the only unambiguous error code to be EX_OSERR which i used whenever a syscall failed

[yuripv]

share/man/man3/sysexits.3

52

broken link?

[emaste]

share/man/man3/sysexits.3

40

Can remove "Do not use them" the "should be considered deprecated and not used in new code." is sufficient.

[jrtc27]

My opinion is that, whilst they are by no means completely unambiguous and fully descriptive, picking a value that's close to right so the user has some idea what the error was even in the absence of error messages is better than just using a hard-coded wholly-meaningless 1 everywhere, as will inevitably happen (and already does when not using sysexits) as a result of this.

[concussious.bugzilla_runbox.com]

Oops, I'm just seeing this.
We've been working on a duplicate on GitHub after a comment on a different PR asked "if this is no longer used that should be mentioned somewhere (including in the header itself).

https://github.com/freebsd/freebsd-src/pull/1195

Personally, I like sysexits and wish an improved version of that could be a standard interface. Cathedrals are beautiful. But I'm very happy to participate in improve consistency if we want to go the other way.