cpp: Include Syntax

1 
1 2.1 Include Syntax
1 ==================
1 
1 Both user and system header files are included using the preprocessing
1 directive '#include'.  It has two variants:
1 
1 '#include <FILE>'
1      This variant is used for system header files.  It searches for a
1      file named FILE in a standard list of system directories.  You can
11      prepend directories to this list with the '-I' option (⇒
      Invocation).
1 
1 '#include "FILE"'
1      This variant is used for header files of your own program.  It
1      searches for a file named FILE first in the directory containing
1      the current file, then in the quote directories and then the same
1      directories used for '<FILE>'.  You can prepend directories to the
1      list of quote directories with the '-iquote' option.
1 
1    The argument of '#include', whether delimited with quote marks or
1 angle brackets, behaves like a string constant in that comments are not
1 recognized, and macro names are not expanded.  Thus, '#include <x/*y>'
1 specifies inclusion of a system header file named 'x/*y'.
1 
1    However, if backslashes occur within FILE, they are considered
1 ordinary text characters, not escape characters.  None of the character
1 escape sequences appropriate to string constants in C are processed.
1 Thus, '#include "x\n\\y"' specifies a filename containing three
1 backslashes.  (Some systems interpret '\' as a pathname separator.  All
1 of these also interpret '/' the same way.  It is most portable to use
1 only '/'.)
1 
1    It is an error if there is anything (other than comments) on the line
1 after the file name.
1