Conventions for system headers

Maciej Sobczak prog at msobczak.com
Mon May 7 06:54:51 UTC 2007


David Schultz wrote:

>> I would like to propose a campaign of bringing all FreeBSD system 
>> headers in line with the guarantee that C99 provides for its standard 
>> headers, for the benefit and convenience of both developers and port 
>> maintainers.
> 
> Which headers did you have in mind?

Everything that we consider "system" headers, but <net/if.h> was a 
motivating example that has led me to investigate the whole issue.
In general, I would like to see consistent conventions applied to all 
headers from /usr/include.

Additional note: it looks to me that IEEE Std 1003.1 says that 
<net/if.h> is enough for its functions to work, which is also consistent 
with FreeBSD's own man pages, for example:

http://www.freebsd.org/cgi/man.cgi?query=if_nametoindex

But in reality <net/if.h> is not complete.


> This sounds like a laudable
> goal, but I'd try to limit it to headers where the requisite
> changes won't be too obscene. For example, a lot of the networking
> headers have sensible and standard dependencies. (POSIX says that
> they may include certain headers that they depend on, but we
> don't, often resulting in a compile-time error; maybe that should
> be changed.)

Exactly.

> Generally try to avoid namespace pollution

Interestingly, namespace pollution cannot get worse by solving this 
problem - it can even be potentially reduced.
Consider (again, <net/if.h> is a good example, but let's keep the 
discussion general) that a user needs to #include header X.h. If it's 
not complete, then he has to also #include some additional header before:

#include <Y.h>  /* required by X.h */
#include <X.h>

If the user omits the first #include, his code will not compile.
Now it is clear that in his program the user gets in the global 
namespace everything from both X.h and Y.h, even though probably only 
part of Y.h is needed for X.h to work.

A simple fix, just to keep the convention that allows arbitrary order, 
is to #include Y.h from X.h. This way X.h becomes complete - but the 
namespace pollution does not increase; in fact, the sequence of tokens 
that the compiler sees is exactly the same. It is just more convenient 
for the user and consistent with the standards.

More complete solution would be of course to refactor common definitions 
from Y.h and #include them internally from both X.h and Y.h, so that X.h 
is complete with respect to its own definitions and the additional stuff 
from Y.h is not necessarily pulled if not needed.
This solution would require creating more headers in the system, which 
is probably more intrusive than it needs to be.

I would like to propose to fix the problem the simple way (for the 
moment) - by just forcibly #include'ing the required headers from their 
dependants. It will not lead to proliferation of new headers and the 
namespace pollution will remain the same as it is now.

Regards,

-- 
Maciej Sobczak : http://www.msobczak.com/
Programming    : http://www.msobczak.com/prog/


More information about the freebsd-standards mailing list