#include -- Preprocessing Directive

Read another file and include it
#include <file>
#include "file"

The preprocessing directive  #include tells the preprocessor to replace the
directive with the contents of file.

The directive  can take one  of two forms:  either the name of  the file is
enclosed within angle brackets (<header.h>), or it is enclosed within
quotation marks ("header.h").  Angle  brackets tell cpp to  look for file.h
in the directories  named with the -I options to  the cc command line,  and
then  in the  standard directory.   Quotation  marks tell  cpp to  look for
file.h in the source file's directory, then in directories named with the -
I options, and then in the standard directory.

Most  often, the  file being  included is  a header, which  is a  file that
contains function prototypes, macro definitions, and other useful material;
as its name  implies, it most often appears at  the head of a program.  The
header name must  be a string of characters, possibly  followed by a period
`.' and a  single letter, usually (but not always)  `h'.  A header name may
have up to  12 characters to the left of  the period, and names may be case
sensitive.

#include directives  may be nested up  to at least eight  deep.  That is to
say, a file included by an #include directive may use an #include directive
to include a third file; that  third file may also use a #include directive
to include a fourth file; and so on, up to at least eight files.

Note,  too,  that a  subordinate  header  file is  sought  relative to  the
original  source file,  rather than  relative to the  header that  calls it
directly.  For example, suppose  that a file example.c resides in directory
/v/fred/src.    If    example.c    contains    the    directive    #include
<header1.h>.  The operating  system will  look  for header1.h  in the
standard  directory,  /usr/include.  If  header1.h includes  the  directive
#include  <../header2.h> then  COHERENT  looks for  header2.h not  in
directory /usr, but in directory /v/fred.

A #include  directive may also take the form  #include string, where string
is a macro that expands into either of the two forms described above.

See Also

header files,
C preprocessor
ANSI Standard §6.8.2

Notes

If the header's name is enclosed  within quotation marks note that the name
is  not a  string literal,  although it  looks exactly  like one.   Thus, a
backslash `\' does not introduce an escape character.

Trigraphs that  occur within a #include  directive are substituted, because
they are  processed by  an earlier phase  of translation than  are #include
directives.

The mapping provided  for included files may map a  given name either to an
actual file, or to a member in a partitioned data set.

© 2012 by Stephen A. Ness