svn commit: r216422 - head/usr.bin/printf

[Bruce Evans]

On Tue, 14 Dec 2010, Xin LI wrote:

> Log:
>  Make use of EX_USAGE for usage().

Most uses of sysexits are styyle bugs.  This one is no exception, since
printf is not sendmail.

> Modified: head/usr.bin/printf/printf.c
> ==============================================================================
> --- head/usr.bin/printf/printf.c	Mon Dec 13 23:53:55 2010	(r216421)
> +++ head/usr.bin/printf/printf.c	Tue Dec 14 00:21:34 2010	(r216422)
> @@ -115,14 +116,14 @@ main(int argc, char *argv[])
> 		case '?':
> 		default:
> 			usage();
> -			return (1);
> +			/* NOTREACHED */

Most uses of NOTREACHED are style bugs.  This one is no exception, since
usage() obviously doesn't return.  Even lint(1) can see this.  It used
to be necessary to declare usage() as __dead2 so that compilers see this,
but now -funit-at-a-time is a default so this ugliness is no longer useful
either (except if usage() in a separate file.  exit(3) is in a separate
file, but it is declared as __dead2.

style(9) still has the bugs of saying to use sysexits and using EX_USAGE
in its usage().  It has a bad recommendation for NOTREACHED too.  It
gives one example of using NOTREACHED.  This is after one of its calls
to usage().  This is a particularly bad example, since NOTREACHED is
not needed there, and it is not used after the other example of usage()
where it is equally [not] needed.  style(9) doesn't use NOTREACHED
after its calls to exit(), where it is almost equally [not] needed --
everyone knows that exit() doesn't return, and everyone should know
that usage() doesn't return too.  You fixed the style bug that printf(1)'s
usage did return.  Everyone knows that the err() family doesn't return,
and of course style(9) doesn't use NOTREACHED after its examples of
calls to err*() either.  These examples show that style(9)'s recomendation
that NOTREACHED should be used for [all] code that cannot be reached is so
wrong that even style(9) knows not to follow it.

style(9) still hasn't caught up with the early 1990's development of
using __dead2 to give an active declaration of functions that don't
return, so that the 1970-1980's method of using NOTREACHED can be
avoided in most cases, in particular after exit(), err*() and usage(),
except as an example of what not to do like one of calls to exit() (*).
NOTREACHED remains useful for avoiding some lint and compiler lifetime
analysis deficiencies, and for telling human readers that although the
code is tangled this part of it really is not reached.  Using it for
code that is obviously not reached reduces its force in these cases.

(*) Reading between the lines, I wilfully misinterpret this example of
being a bad example of everthing it does:

%      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."
%                               */

Things not to do that are done in this example include:
- use EX_OK, not 0 on success
- place comments to the right of the code and extend them across multiple
   lines for maximal waste of space
- when changing code to use EX_OK (or anything, be sure to neglect to change
   the comments, so that the comments don't match the code).  [Here this was
   originally just a bad example of an obvious comment.  The code said exit(0)
   and the comment said 0 too.  Now it doesn't say EX_OK, so it is not so
   obvious that this is an obvious comment (in fact, EX_OK does equal 0,
   but this is of no interest here).]
This example could be further improved by adding an obvious NOTREACHED
comment to it.

style(9) still hasn't caught up with the late 1990's development of using
EXIT_SUCCESS.  This C90 macro for spelling 0 is about as popular as POSIX's
STDIN_FILENO, but at least it is Standard, unlike EX_OK.

Bruce