.TH #include "" "" "Preprocessing Directive" "" "(Language/preprocessing)"
.II "preprocessing directive, include source file"
.II "source file inclusion"
.II "include source file"
.II "file, source, include"
.II "header, copy into program"
.II "copy header into program"
.PC "Read another file and include it"
\fB#include <\fIfile\^\fB>\fR
\fB#include "\fIfile\^\fB"\fR
.PP
The preprocessing directive
.B #include
tells the preprocessor to replace the directive with the contents of
.IR file .
.PP
The directive can take one of two forms:
either the name of the file is enclosed within angle brackets
(\fB<\fIheader\^\fB.h>\fR), or it is enclosed within
quotation marks (\fB"\fIheader\^\fB.h"\fR).
Angle brackets tell
.B cpp
to look for \fIfile\fB.h\fR in the directories
named with the \fB\-I\fR options
to the
.B cc
command line, 
and then in the
standard directory.
Quotation marks tell
.B cpp
to look for \fIfile\fB.h\fR in the source file's directory,
then in directories named with the
\fB\-I\fR options, and then in the
standard directory.
.PP
Most often, the file being included is a
.IR 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
\*(Ql.\*(Qr and a single letter, usually (but not always) \*(Qlh\*(Qr.
A header name may have up to 12 characters to the left of the period,
and names may be case sensitive.
.PP
.B #include
directives may be nested up to at least eight deep.
That is to say, a file included by an
.B #include
directive may use an
.B #include
directive to include a third file; that third file may also use a
.B #include
directive to include a fourth file; and so on, up to at least eight
files.
.PP
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
.B example.c
resides in directory
.BR /v/fred/src .
If
.B example.c
contains the directive
.BR "#include <header1.h>" .
The operating system will look for
.B header1.h
in the standard directory,
.BR /usr/include .
If
.B header1.h
includes the directive
.B "#include <../header2.h>"
then
\*(CO looks for
.B header2.h
not in directory \fB/usr\fR, but in directory
.BR /v/fred .
.PP
A
.B #include
directive may also take the form \fB#include \fIstring\fR,
where
.I string
is a macro that expands into either of the two forms described above.
.SH "See Also"
.Xr "header files," header_fi
.Xr "C preprocessor" c_preproc
.br
\*(AS \(sc6.8.2
.SH Notes
If the header's name is enclosed within quotation marks
note that the name is \fInot\fR a string literal, although it looks
exactly like one.
Thus, a backslash \*(Ql\e\*(Qr does not introduce an escape character.
.PP
Trigraphs that occur within a
.B #include
directive are substituted, because they are processed by an earlier
phase of translation than are
.B #include
directives.
.PP
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.
