Rui Paulo wrote:

>On 2005.12.03 16:59:35 -0500, Christos Zoulas wrote:
>| 
>| Hello,
>| 
>| I just made a short pass in sys/fs and sys/sys to fix multiple inclusion
>| issues. Where many files followed the current standard, there were quite
>| a few that did not.
>| 
>| My understanding of the current rules for include files [kernel] are:
>| 
>| 1. For files that get installed in /usr/include:
>|    All the code in the include file is bracketed by:
>| 
>|    #ifndef _[<DIR>_...]<FILENAME>_H_
>|    #define _[<DIR>_...]<FILENAME>_H_
>|    .... code ....
>|    #endif /* _[<DIR>_...]<FILENAME>_H_ */
>| 
>|    The DIR portion is the dirname portion of the path capitalized, and with
>|    `/' substituted by `_'. The path is the install path of the file not the
>|    source path. For example:
>| 
>|    src/sys/fs/cd9660/iso.h gets installed in /usr/include/isofs/cd9660/iso.h
>|    so the file should be protected by:
>| 
>|    #ifndef _ISOFS_CD9660_ISO_H_
>|    #define _ISOFS_CD9660_ISO_H_
>|    #endif /* _ISOFS_CD9660_ISO_H_ */
>| 
>|    Files that should not be protected against multiple inclusion should mention
>|    this prominently as a comment immediately after the copyright notice.
>
>Yes, I think this truly correct.
>
>
>| 
>| 2. Header files that are not installed are not protected for multiple inclusion
>|    but they are protected against use in the userland by:
>| 
>|    #ifndef _KERNEL
>|    #error not supposed to be exposed to userland.
>|    #endif /* _KERNEL */
>| 
>|    The rationale is that we don't want to include these files multiple times
>|    accidentally, and we also don't want userland applications to include them
>|    either.
>|    Most of the kernel files do not follow this standard right now. I.e. there
>|    are files that are used by userland programs and not being installed, and
>|    most files don't have the #error protection.
>
>We can work together on fixing this.
>  
>
For the same reason that multiple inclusion is a problem for userland,
it can be a problem for kernel space files.  I think the include guards
should be on any file, unless we create an "arbitrary" rule that says
that kernel headers cannot include other kernel headers.

(And then the question arises, what about headers that are part of
userland, but do something like

#ifdef _KERNEL
#include <kernel-defs>
#endif

Yikes.

Again, I think it is a lot easier if kernel headers have the guards,
unless there is some compelling reason why multiple inclusion should
both be legal and non-idempotent.   (Most of the cases of that that I
can think of are for #including *implementation* bits, and so maybe
those aren't really headers but some kind of shared .c file.)

    -- Garrett

>		-- Rui Paulo
>  
>


-- 
Garrett D'Amore                          http://www.tadpolecomputer.com/
Sr. Staff Engineer          Extending the Power of 64-bit UNIX Computing
Tadpole Computer, Inc.                             Phone: (951) 325-2134