cpp: Include Operation

1 
1 2.2 Include Operation
1 =====================
1 
1 The '#include' directive works by directing the C preprocessor to scan
1 the specified file as input before continuing with the rest of the
1 current file.  The output from the preprocessor contains the output
1 already generated, followed by the output resulting from the included
1 file, followed by the output that comes from the text after the
1 '#include' directive.  For example, if you have a header file 'header.h'
1 as follows,
1 
1      char *test (void);
1 
1 and a main program called 'program.c' that uses the header file, like
1 this,
1 
1      int x;
1      #include "header.h"
1 
1      int
1      main (void)
1      {
1        puts (test ());
1      }
1 
1 the compiler will see the same token stream as it would if 'program.c'
1 read
1 
1      int x;
1      char *test (void);
1 
1      int
1      main (void)
1      {
1        puts (test ());
1      }
1 
1    Included files are not limited to declarations and macro definitions;
1 those are merely the typical uses.  Any fragment of a C program can be
1 included from another file.  The include file could even contain the
1 beginning of a statement that is concluded in the containing file, or
1 the end of a statement that was started in the including file.  However,
1 an included file must consist of complete tokens.  Comments and string
1 literals which have not been closed by the end of an included file are
1 invalid.  For error recovery, they are considered to end at the end of
1 the file.
1 
1    To avoid confusion, it is best if header files contain only complete
1 syntactic units--function declarations or definitions, type
1 declarations, etc.
1 
1    The line following the '#include' directive is always treated as a
1 separate line by the C preprocessor, even if the included file lacks a
1 final newline.
1