Conventions for system headers

[Maciej Sobczak]

Hi (this is my first post to this list),

The C99 standard defines the following requirement (7.1.2/4):

"Standard headers may be included in any order [...]"

This provides guarantees for language users, but at the same time 
imposes restrictions on language implementers on how the headers should 
be written themselves.

The rationale for this paragraph is that headers which are insensitive 
to their order of inclusion ease the maintenance of user code and allow 
arbitrary conventions related to the use of #include directives (like, 
say, include in lexicographical order, etc.).

What's important here is that this guarantee relates formally to 24 
Standard C headers, enumerated in 7.1.2/2. In FreeBSD these headers are 
conveniently put in the /usr/include directory.

The problem is that the same directory contains many other headers.
Formally, the guarantee from 7.1.2/4 does not relate to those other 
headers, since they are not Standard C. But at the same time the 
rationale that stands behind this paragraph is reasonable enough that it 
could be extended to all system headers.
An important potential gain is the ease of porting of software written 
with other POSIX-compliant systems in mind, where by chance system 
headers are not sensitive to their inclusion order. Currently such 
software might not compile on FreeBSD only due to the sensitivity of 
FreeBSD's headers - whether the ordering of #include directive in the 
software matches that required on FreeBSD is a matter of luck.

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.
I'm aware of the fact that doing this requires some involvement, but at 
the same time the necessary modifications are relatively simple.


Please note that a "standard" test for compliance with 7.1.2/4 is either 
the following test source that can be applied (even automatically) for 
any header X.h:

/* X_test.h */
#include <X.h>
#include <X.h>
/* eof */

or, without testing the sensitivity to multiple inclusion, just:

$ gcc -c -x c X.h -o /dev/null

Regards,

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