A.2.37 -I-

Change the include-file search rules to the following:

For include files of the form #include "foo.h", search the directories in the following order.

For include files of the form #include "foo.h", search the directories in the following order:

1. The directories named with -I options (both before and after -I-).

2. The directories for compiler-provided C++ header files, ANSI C header files, and special-purpose files.

3. The /usr/include directory.

For include files of the form #include <foo.h>, search the directories in the following order:

1. The directories named in the -I options that appear after -I-.

2. The directories for compiler-provided C++ header files, ANSI C header files, and special-purpose files.

3. The /usr/include directory.

If the name of the include file matches the name of a standard header, also refer to 12.7.5 Standard Header Implementation .

A.2.37.1 Examples

The following example shows the results of using -I- when compiling prog.cc.

prog.cc
#include "a.h"
#include <b.h>
#include "c.h"
c.h
#ifndef _C_H_1
#define _C_H_1
int c1;
#endif
inc/a.h
#ifndef _A_H
#define _A_H
#include "c.h"
int a;
#endif
inc/b.h
#ifndef _B_H
#define _B_H
#include <c.h>
int b;
#endif
inc/c.h
#ifndef _C_H_2
#define _C_H_2
int c2;
#endif

The following command shows the default behavior of searching the current directory (the directory of the including file) for include statements of the form #include "foo.h". When processing the #include "c.h" statement in inc/a.h, the compiler includes the c.h header file from the inc subdirectory. When processing the #include "c.h" statement in prog.cc, the compiler includes the c.h file from the directory containing prog.cc. Note that the -H option instructs the compiler to print the paths of the included files.

example% CC -c -Iinc -H prog.cc
inc/a.h
        inc/c.h
inc/b.h
        inc/c.h
c.h

The next command shows the effect of the -I- option. The compiler does not look in the including directory first when it processes statements of the form #include "foo.h". Instead, it searches the directories named by the -I options in the order that they appear in the command line. When processing the #include "c.h" statement in inc/a.h, the compiler includes the ./c.h header file instead of the inc/c.h header file.

example% CC -c -I. -I- -Iinc -H prog.cc
inc/a.h
        ./c.h
inc/b.h
        inc/c.h
./c.h

Interactions

When -I- appears in the command line, the compiler never searches the current directory, unless the directory is listed explicitly in a -I directive. This effect applies even for include statements of the form #include "foo.h".

Warnings

Only the first -I- in a command line causes the described behavior.

Never specify the compiler installation area, /usr/include, /lib, or /usr/lib, as search directories.