Preprocessor Directive - File Inclusion (#include)

Syntax

A preprocessor #include directive causes the preprocessor to replace the directive with the contents of the specified file.

The preprocessor resolves macros contained in a #include directive. After macro replacement, the resulting token sequence must consist of a file name enclosed in either double quotation marks or the characters < and >.

For example:

#define MONTH <july.h>
#include MONTH

If the file name is enclosed in double quotation marks, for example: #include "payroll.h" the preprocessor treats it as a user- defined file, and searches for the file in:

  1. The directory where the original .c source file resides.
  2. Any directories specified using the includepath(path) compiler option (that have not been removed by the file(ignoreusrincpaths, ...) option). Directories specified in the ICC environment variable are searched before those specified on the command line.
  3. Any directories specified using the INCLUDE environment variable, provided the file(ignoreenvincpaths, ...) option is not in effect.

If the file name is enclosed in angle brackets, for example: # include <stdio.h> it is treated as a system-defined file, and the preprocessor searches the following places in the order given:

  1. Any directories specified using the includepath(path) compiler option (that have not been removed by the file(ignoreusrincpaths, ...) option). Directories specified in the ICC environment variable are searched before those specified on the command line.
  2. Any directories specified using the INCLUDE environment variable, provided the file(ignoreenvincpaths, ...) option is not in effect.

Note: If the file name is fully qualified, the preprocessor searches only the directory specified by the name.

The new-line and > characters cannot appear in a file name delimited by < and >. The new- line and " (double quotation marks) character cannot appear in a file name delimited by " and ", although > can.

Declarations that are used by several files can be placed in one file and included with #include in each file that uses them. For example, the following file defs.h contains several definitions and an inclusion of an additional file of declarations:

/* defs.h */
#define TRUE 1
#define FALSE 0
#define BUFFERSIZE 512
#define MAX_ROW 66
#define MAX_COLUMN 80
int hour;
int min;
int sec;
#include "mydefs.h"

You can embed the definitions that appear in defs.h with the following directive:

#include "defs.h"

In the following example, a #define combines several preprocessor macros to define a macro that represents the name of the C standard I/O header file. A #include makes the header file available to the program.

#define  IO_HEADER   <stdio.h>
      .
      .
      .
#include IO_HEADER   /* equivalent to specifying #include <stdio.h> */
      .
      .
      .


Preprocessor Directives - An Overview


Macro Definition and Expansion - #define
Scope of Macro Names - #undef
Compile and Link Option - includepath(path)
ignoreusrincpaths C File Option - file(ignoreusrincpaths, ...)
ignoreenvincpaths C File Option - file(ignoreenvincpaths, ...)
Example of Preprocessor Directives