how #include directives are handled

[Charles Mills]

What does the C standard (C99) say about which version of header2.h
should be included in the following case - where directory1 is the
current directory and directory2 is included in the list of directories
to be searched for headers?

contents of directory1:

file1.c:
#include "file1.h"
int main(void) { return 0; }
-- EOF

file1.h:
#include "header1.h"
-- EOF

header2.h:
#warning ---> In directory1/header2.h
-- EOF


contents of directory2:

header1.h:
#include "header2.h"
-- EOF

header2.h:
#warning ---> In directory2/header2.h
-- EOF


Perhaps this is all implemtation defined... if it is what happens
typically in the real world? GCC gives

$ gcc -Iother file1.c
In file included from other/header1.h:1,
from file1.h:2,
from file1.c:2:
other/header2.h:1:2: warning: #warning ---> In other/header2.h

-Charlie

 

[Eric Sosman]

What does the C standard (C99) say about which version of header2.h
should be included in the following case - where directory1 is the
current directory and directory2 is included in the list of directories
to be searched for headers?

The Standard says it's "implementation-defined," and
that's all.

[...]
Perhaps this is all implemtation defined... if it is what happens
typically in the real world? [...]

You can count on the real world to be variegated, maybe
even chaotic. "There are more things in Heaven and Earth,
Horatio, than are dreamt of in your philosophy." A few
behaviors that I've seen:

- The search path is fixed throughout the compilation,
so every #include traverses the same list of places
in the same order, regardless of where the #include
directive itself resides.

- The search begins where the #include directive is
found, and only if the #include'd file isn't found
there does it search the global path.

- The search begins where the topmost .c file is found,
and then proceeds along the global path if necessary.
The location of the #include directive itself doesn't
matter.

I've even used a system where the notion of "directory"
could itself involve a kind of a search path -- and different
releases of the compiler disagreed on how the location of an
#include in "the same directory" but at different positions
in the implied path were treated ...

Suggestions: Insofar as possible, give every header file
a globally unique name. If that's not possible (on a large
project it often isn't), try to limit the departures to
strictly-local headers that are #include'd only by C sources
in the same directory; avoid nesting references to these
"colliding" headers inside headers that are used in wider
contexts. If even that much isn't possible, try to audit
the set of headers each compilation actually pulls in; gcc,
for example, can tell you exactly which headers it #includes.