Re: kern/46557: sys/syslog.h can't be compiled on its own with -D_KERNEL

[David Holland <dholland-bugs%netbsd.org@localhost>]

The following reply was made to PR kern/46557; it has been noted by GNATS.

From: David Holland <dholland-bugs%netbsd.org@localhost>
To: gnats-bugs%NetBSD.org@localhost
Cc: 
Subject: Re: kern/46557: sys/syslog.h can't be compiled on its own with
 -D_KERNEL
Date: Wed, 9 Sep 2015 06:23:45 +0000

 On Tue, Sep 08, 2015 at 09:35:01PM +0000, Richard Hansen wrote:
  >  Apologies for forgetting about this; comments below.
 
 No worries, I think there's at least one other of yours that *I*'ve
 been doing nothing on. :-/
 
  >  > As per longstanding tradition, you need <sys/types.h> first in kernel
  >  > source files.
  >  
  >  That's not a very discoverable tradition for coders unfamiliar with the
  >  kernel codebase.
 
 That's true; however, it's been the convention for 40-odd years, and
 lots of kernel headers don't compile if you don't include <sys/types.h> 
 (or <sys/param.h>) first.
 
 There are 2111 ordinary header files in the (arbitrarily chosen) amd64
 kernel tree I'm looking at right now. This includes MD headers (for
 amd64 and i386 only), but excludes driver headers, and also the
 compat, rump, and external subtrees as those have different ground
 rules.
 
 Using a quick hack mockup of the kernel build environment (which may
 be missing stuff(*)) I get:
 
    plain                                1411/2111 compile (67%)
    with -include .../sys/sys/types.h    1654/2111 compile (78%)
    with -include .../sys/sys/param.h    1717/2111 compile (81%)
 
 Looking at just the primary headers in sys/:
    plain                                161/266 compile (60%)
    with -include .../sys/sys/types.h    221/266 compile (83%)
    with -include .../sys/sys/param.h    239/266 compile (90%)
 
 Note that not every .h file is meant to be a standalone interface, and
 I'm likely as not missing something from the build environment (I
 haven't inspected the errors from the failed files) so the total
 numbers are lower across the board than they "ought" to be. However,
 you probably get the idea.
 
 I agree that expecting <sys/types.h> first is suboptimal. However,
 it's a bigger problem than just one header file; and adding
 <sys/types.h> indiscriminately runs the risk of polluting the user
 namespace in violation of POSIX and ISO C; in particular,
 <sys/types.h> is exactly what must *not* be included in any number of
 standards-defined headers that are only supposed to expose a limited
 set of declarations.
 
 One of these days someone will get around to reorganizing the kernel
 includes into a safer and more structured form. I've talked about this
 elsewhere, both how to set it up and what getting there entails.
 Unfortunately, any substantive organization requires moving around a
 lot of core files, so it has to wait until we've migrated to a source
 control system that tracks file renames. And that remains problematic.
 
 (After such a reorg there's a strong separation between kernel
 internal and user-exposed headers, and no user-exposed header should
 be included directly, so it becomes possible to reform this without
 making a huge mess in libc.)
 
 I'm also not really sure if reforming the historical convention is
 worthwhile. However, given that more than half of the headers
 apparently no longer rely on it anyway, maybe it's time for it to go
 in favor of now-standard practice. I have no strong opinion on this,
 but it's probably necessary to establish a consensus on the mailing
 list before moving ahead.
 
 (I don't approve of indiscriminate use of <sys/param.h>, which exposes
 all kinds of random rubbish, but that's a different and probably
 uphill battle.)
 
  >  It'd be good if there was a document saying that <sys/types.h> must be
  >  included first in all kernel .c files (and the reasons why).  There
  >  should be lots of pointers to that document to make the policy easy to
  >  discover.
 
 I have no idea where to put that document. I think the information
 appears in the style rules; but that isn't a particularly useful
 place. It ought to appear in the section 9 man pages, but it doesn't,
 and I don't see any good place to put it.
 
 Unfortunately, it's mostly part of the Unix lore. I don't remember
 when I picked it up; it was a long time ago.
 
 Any suggestions?
 
  >  > What are you trying to do? You might be looking for -D_KMEMUSER.
  >  
  >  If I remember correctly, I had created a new .c file to add some new
  >  functionality to the kernel for a project I was working on.  I got that
  >  compiler error when I wasn't magically imbued with the knowledge that I
  >  needed to #include other stuff before sys/syslog.h.  :)
 
 Fair enough... :-/
 
 -- 
 David A. Holland
 dholland%netbsd.org@localhost