svn commit: r245506 - head/bin/pwait

[Bruce Evans]

On Thu, 17 Jan 2013, Pawel Jakub Dawidek wrote:

> On Thu, Jan 17, 2013 at 10:50:07AM -0500, John Baldwin wrote:
>> On Wednesday, January 16, 2013 10:40:51 pm Eitan Adler wrote:
>>> On 16 January 2013 21:25, Bruce Evans <brde at optusnet.com.au> wrote:
>>>> This uses the sysexits mistake.  style(9) was fixed to not give an example
>>>> of this mistake.  Before this, sysexits was used a whole once in pwait(1)
>>>> (for EX_USAGE) in usage().  EX_USAGE happens to be 64.  As usual when the
>>>> mistake is used, this is useless for humans (the usage message gives more
>>>> info) and unusable for programs, especially since it is undocmented
>>>> (pwait(1)'s man page just says ">0 if an error occurs".  It doesn't even
>>>> use '.Std' for this, but hard-codes it.
>>>
>>> IMHO using sysexits gives more signal than using a binary 0 or 1.  It
>>> is a mistake to have changed style(9) to avoid using sysexits.
>>> Instead the man page should detail the specific error that occurs
>>> directly, or by reference to sysexit.
>>
>> Eh, I think bde@ has quite a bit more experience with this than you.
>> <sysexits.h> is not part of POSIX or any other standard.  It's comments
>> reference delivermail (the predecessor to sendmail).  Looking at its history,
>> it has never been changed in FreeBSD, and it's history in CSRG is rather
>> spartan and mostly tied to delivermail/sendmail:
>>
>> http://svnweb.freebsd.org/csrg/include/sysexits.h?view=log
>>
>> In practice it's list of error value is limited and has not grown to handle
>> new errors in over two decades (as opposed to, say, the list of errnos).
>> OTOH, it seems the history section in sysexits(3) is slightly off as the CSRG
>> history suggests it was present in at least 4.2BSD.
>
> Well, if we decide sysexits(3) are useless, then it would be nice to
> recommend against using it in sysexits(3) manual page. Currently it is
> rather seductive:
>
> 	According to style(9), it is not a good practice to call exit(3)
> 	with arbitrary values to indicate a failure condition when
> 	ending a program.  Instead, the pre-defined exit codes from
> 	sysexits should be used, so the caller of the process can get a
> 	rough estimation about the failure class without looking up the
> 	source code.

Oops, this wasn't changed when the mistake was fixed in style(9) :-).

The orignal BSD style guide (/usr/src/admin/style/style) actually says
not to use [non-arbitrary] sequential values to indicate all exit points:

% 	/*
% 	 * Exits should be 0 on success, and 1 on failure.  Don't denote
% 	 * all the possible exit points, using the integers 1 through 300.
% 	 */
% 	exit(0);    /* Avoid obvious comments such as "Exit 0 on success." */

but was changed in FreeBSD to say something quite different:

%      Exits should be 0 on success, or according to the predefined values in
%      sysexits(3).
% 
%              exit(EX_OK);    /*
%                               * Avoid obvious comments such as
%                               * "Exit 0 on success."
%                               */

and then was changed to say something even further removed from the original:

%      Exits should be 0 on success, or 1 on failure.
% 
%              exit(0);        /*
%                               * Avoid obvious comments such as
%                               * "Exit 0 on success."
%                               */
%      }

I thought that it was changed to at least mention the Standard but not
very useful EXIT_SUCCESS and EXIT_FAILURE.  It should also not disallow
an error code of 2 which is often used for more severe errors.

> I, for one, used it pretty extensively in HAST:)
>
> 	% grep EX_ /usr/src/sbin/hastd/*.c | wc -l
> 	      67
>
> In my humble opinion using sysexits(3) is better than just putting
> exit(1) everywhere. Actually HAST or some of my other projects was
> making decision about restarting a processes if the exit code was
> EX_TEMPFAIL (if the failure was temporary it is fine to restart, if it
> is not then better not to enter some infinite loop).

A set of programs like sendmail or hastd can reasonably communicate
using the exit code.  For humans, it is easier to read the message on
stderr in in a log file that should accompany almost all exits.
Non-sets of programs shouldn't be burdened by having to provide,
document and maintain unique exit codes for programs outside the set
which will almost never make decisions based on the uniqueness.

The EX_TEMPFAIL retry seems to be the only useful use of sysexits even
in hastd.  It mostly logs the error with a message giving more detail.

EX_USAGE is an especially useless exit status.  From pwait.c:

% static void
% usage(void)
% {
% 
% 	fprintf(stderr, "usage: pwait [-v] pid ...\n");
% 	exit(EX_USAGE);
% }

Consider possible users of this program:
- a human can read "usage: ".  EX_USAGE adds nothing to this.
- a program that doesn't know correct usage isn't going to be able to
   with correct usage after seeing the EX_USAGE.

Bruce