#iinncclluuddee -- Preprocessing Directive

Read another file and include it
#iinncclluuddee <_f_i_l_e>
#iinncclluuddee "_f_i_l_e"

The preprocessing directive  #iinncclluuddee tells the preprocessor to replace the
directive with the contents of _f_i_l_e.

The directive  can take one  of two forms:  either the name of  the file is
enclosed within angle brackets (<_h_e_a_d_e_r.hh>),  or   it  is  enclosed  within
quotation marks ("_h_e_a_d_e_r.hh").  Angle  brackets tell ccpppp to  look for _f_i_l_e.hh
in the directories  named with the -II options to  the cccc command line,  and
then  in the  standard directory.   Quotation  marks tell  ccpppp to  look for
_f_i_l_e.hh in the source file's directory, then in directories named with the -
II options, and then in the standard directory.

Most  often, the  file being  included is  a _h_e_a_d_e_r, 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.

#iinncclluuddee directives  may be nested up  to at least eight  deep.  That is to
say, a file included by an #iinncclluuddee directive may use an #iinncclluuddee directive
to include a third file; that  third file may also use a #iinncclluuddee 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 eexxaammppllee.cc resides in directory
/vv/ffrreedd/ssrrcc. If eexxaammppllee.cc  contains the directive #iinncclluuddee <hheeaaddeerr11.hh>. The
operating  system  will  look  for  hheeaaddeerr11.hh  in the  standard  directory,
/uussrr/iinncclluuddee. If  hheeaaddeerr11.hh includes the  directive #iinncclluuddee <../hheeaaddeerr22.hh>
then COHERENT  looks for hheeaaddeerr22.hh not in directory  /uussrr, but in directory
/vv/ffrreedd.

A #iinncclluuddee  directive may also take the form  #iinncclluuddee _s_t_r_i_n_g, where _s_t_r_i_n_g
is a macro that expands into either of the two forms described above.

_S_e_e _A_l_s_o
hheeaaddeerr ffiilleess, CC pprreepprroocceessssoorr
ANSI Standard, section 6.8.2

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

Trigraphs that  occur within a #iinncclluuddee  directive are substituted, because
they are  processed by  an earlier phase  of translation than  are #iinncclluuddee
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.
