2.14 How to Specify Include Files

To include any of the standard header files supplied with the C compilation system, use this format:

#include <stdio.h>

The angle brackets (<>) cause the preprocessor to search for the header file in the standard place for header files on your system, usually the /usr/include directory.

The format is different for header files that you have stored in your own directories:

#include "header.h"

For statements of the form #include "foo.h" (where quotation marks are used), the compiler searches for include files in the following order:

1. The current directory (that is, the directory containing the “including” file)

2. The directories named with -I options, if any

3. The /usr/include directory

If your header file is not in the same directory as the source files that include it, specify the path of the directory in which it is stored with the– I option to cc. Suppose, for instance, that you have included both stdio.h and header.h in the source file mycode.c:

#include <stdio.h>
#include "header.h"

Suppose further that header.h is stored in the directory../defs. The command:

% cc– I../defs mycode.c

directs the preprocessor to search for header.h first in the directory containing mycode.c, then in the directory ../defs, and finally in the standard place. It also directs the preprocessor to search for stdio.h first in ../defs, then in the standard place. The difference is that the current directory is searched only for header files whose names you have enclosed in quotation marks.

You can specify the– I option more than once on the cc command-line. The preprocessor searches the specified directories in the order they appear. You can specify multiple options to cc on the same command-line:

% cc– o prog– I../defs mycode.c

2.14.1 Using the -I- Option to Change the Search Algorithm

The new -I- option gives more control over the default search rules. Only the first -I- option on the command line works as described in this section. When -I- appears in the command line:

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.

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

prog.c
#include "a.h"

#include <b.h>

#include "c.h"


c.h
#ifndef _C_H_1

#define _C_H_1

int c1;

#endif


int/a.h
#ifndef _A_H

#define _A_H

#include "c.h"

int a;

#endif


int/b.h
#ifndef _B_H

#define _B_H

#include <c.h>

int b;

#endif
int/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 preprocessor includes the c.h header file from the inc subdirectory. When processing the #include "c.h" statement in prog.c, the preprocessor includes the c.h file from the directory containing prog.c. Note that the -H option instructs the compiler to print the paths of the included files.

example% cc -c -Iinc -H prog.c
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 preprocessor 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 preprocessor includes the ./c.h header file instead of the inc/c.h header file.

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

2.14.1.1 Warnings

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

For more information, see B.2.34 -I[-|dir].