GNU Info

(cpp-295.info)Include Syntax

---

Next: Include Operation Prev: Header Uses Up: Header Files

---

Enter node , (file) or (file)node

The `#include' Directive
------------------------

   Both user and system header files are included using the
preprocessing directive `#include'.  It has three variants:

`#include <FILE>'
     This variant is used for system header files.  It searches for a
     file named FILE in a list of directories specified by you, then in
     a standard list of system directories.  You specify directories to
     search for header files with the command option `-I' (Note:
     Invocation.).  The option `-nostdinc' inhibits searching the
     standard system directories; in this case only the directories you
     specify are searched.

     The parsing of this form of `#include' is slightly special because
     comments are not recognized within the `<...>'.  Thus, in
     `#include <x/*y>' the `/*' does not start a comment and the
     directive specifies inclusion of a system header file named
     `x/*y'.  Of course, a header file with such a name is unlikely to
     exist on Unix, where shell wildcard features would make it hard to
     manipulate.

     The argument FILE may not contain a `>' character.  It may,
     however, contain a `<' character.

`#include "FILE"'
     This variant is used for header files of your own program.  It
     searches for a file named FILE first in the current directory,
     then in the same directories used for system header files.  The
     current directory is the directory of the current input file.  It
     is tried first because it is presumed to be the location of the
     files that the current input file refers to.  (If the `-I-' option
     is used, the special treatment of the current directory is
     inhibited.)

     The argument FILE may not contain `"' characters.  If backslashes
     occur within FILE, they are considered ordinary text characters,
     not escape characters.  None of the character escape sequences
     appropriate to string constants in C are processed.  Thus,
     `#include "x\n\\y"' specifies a filename containing three
     backslashes.  It is not clear why this behavior is ever useful, but
     the ANSI standard specifies it.

`#include ANYTHING ELSE'
     This variant is called a "computed #include".  Any `#include'
     directive whose argument does not fit the above two forms is a
     computed include.  The text ANYTHING ELSE is checked for macro
     calls, which are expanded (Note: Macros.).  When this is done,
     the result must fit one of the above two variants--in particular,
     the expanded text must in the end be surrounded by either quotes
     or angle braces.

     This feature allows you to define a macro which controls the file
     name to be used at a later point in the program.  One application
     of this is to allow a site-specific configuration file for your
     program to specify the names of the system include files to be
     used.  This can help in porting the program to various operating
     systems in which the necessary system header files are found in
     different places.