Page MenuHomeFreeBSD

Discourage the use of sysexits(3) in new code
Needs ReviewPublic

Authored by 0mp on Nov 11 2020, 12:18 PM.

Details

Reviewers
jilles
yuripv
Group Reviewers
manpages
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:

Diff Detail

Repository
rS FreeBSD src repository - subversion
Lint
Lint OK
Unit
No Unit Test Coverage
Build Status
Buildable 34742
Build 31798: arc lint + arc unit

Event Timeline

0mp requested review of this revision.Nov 11 2020, 12:18 PM
0mp added a subscriber: des.
  • Remove "preferable" from the manual page title

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.

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 added inline comments.
share/man/man3/sysexits.3
52

broken link?