2.17 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, use the -I compiler option to specify the path of the directory in which it is stored. For instance, suppose 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. You might then want to use this command:

% cc  –I../defs  mycode.c

It 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.17.1 Using the -I- Option to Change the Search Algorithm

The -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.

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.

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.17.1.1 Warnings

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

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