svn commit: r305998 - in head/usr.bin: cmp indent tr

[Bruce Evans]

On Mon, 19 Sep 2016, John Baldwin wrote:

> On Monday, September 19, 2016 01:45:01 PM Ngie Cooper wrote:
>>
>>> On Sep 19, 2016, at 1:43 PM, Conrad E. Meyer <cem at FreeBSD.org> wrote:
>>> Log:
>>>  Move sys/capsicum.h includes after types.h or param.h
>>>
>>>  This is not actually documented or even implied in style(9).  Make the change
>>>  to match convention.  Someone should document this convention in style(9).
>>>
>>>  Reported by:	jhb
>>>  Sponsored by:	EMC Dell Isilon
>>
>> Uh… yes it clearly states it in style(9). From https://www.freebsd.org/cgi/man.cgi?query=style&sektion=9 :
>>      Kernel include files (i.e. sys/*.h) come first; normally, include
>>      <sys/types.h> OR <sys/param.h>, but not both.  <sys/types.h> includes
>>      <sys/cdefs.h>, and it is okay to depend on that.
>
> It doesn't actually say that types.h/param.h has to come before other sys/*.h
> headers though.  Normally sys/foo.h requires sys/types.h to compile hence the
> rule, but sys/capsicum.h gets around this by a nested include of sys/param.h
> (which is itself probably dubious).

This and other nested includes make sys/capsicum.h of rmrf quality.

It is now not so normal to require sys/types or sys/param.h first, since
too many headers have been broken using nested includes.  Only a few have
correct fixes for pollution.  Almost none have documentation for either
their non-pollution or pollution, except possibly with directives like
-D_POSIX_SOURCE (restrict to ~1988 POSIX.1) where the standard has such
documentation and the standard is supported.  E.g., cap_enter(2) only
mentions a couple of symbols and no namespaces.  Its SYNOPSIS uses the
undocumented symbol u_int, and doesn't mention sys/types.h or _BSD_VISIBLE,
so by knowing undocumented things we can tell that its #include of
<sys/capsicum.h> is either incomplete or that it has namespace pollution
including at least u_int and probably all the undocumented symbols in
sys/types.h, but that is just the start of the pollution.

> I do think we should explicitly add a note to style.9 though to say that
> types.h|param.h comes first.

I use the following:

X Index: style.9
X ===================================================================
X RCS file: /home/ncvs/src/share/man/man9/style.9,v
X retrieving revision 1.110
X diff -u -2 -r1.110 style.9
X --- style.9	3 Jul 2004 18:29:24 -0000	1.110
X +++ style.9	7 Jul 2004 11:47:22 -0000
X @@ -90,17 +130,22 @@
X  .Ed
X  .Pp
X -Leave another blank line before the header files.
X +Leave one blank line before the header files.
X  .Pp
X -Kernel include files (i.e.\&
X +Kernel include files (i.e.,\&
X  .Pa sys/*.h )
X -come first; normally, include
X -.In sys/types.h
X -OR
X -.In sys/param.h ,
X -but not both.
X +come first; normally,
X  .In sys/types.h
X +or
X +.In sys/param.h
X +will be needed before any others.
X +.In sys/param.h
X  includes
X +.In sys/types.h .
X +Do not include both.
X +Many headers, including
X +.In sys/types.h ,
X +include
X  .In sys/cdefs.h ,
X -and it is okay to depend on that.
X +and it is OK to depend on that.
X  .Bd -literal
X  #include <sys/types.h>	/* Non-local includes in angle brackets. */
X @@ -116,12 +161,11 @@
X  .Ed
X  .Pp
X -Do not use files in
X +Do not include files in
X  .Pa /usr/include
X  for files in the kernel.
X  .Pp
X -Leave a blank line before the next group, the
X -.Pa /usr/include
X -files,
X -which should be sorted alphabetically by name.
X +Leave a blank line before the next group (XXX nah, all groups),
X +the <*.h> include files.
X +Sort the <*.h> include files (XXX nah, all groups) alphabetically.
X  .Bd -literal
X  #include <stdio.h>
X @@ -138,5 +182,6 @@
X  .Ed
X  .Pp
X -Leave another blank line before the user include files.
X +Leave another blank line before the local include files.
X +XXX nah, leave it before all groups.
X  .Bd -literal
X  #include "pathnames.h"		/* Local includes in double quotes. */

Bruce