The #include directive tells the preprocessor to treat the contents of the named file as if it appeared in the source program at the point where the directive appears. You can organize constant and macro definitions into include files and then use #include directives to add these definitions to any source file. Include files are also useful for incorporating declarations of external variables and complex data types. You only need to define and name the types once in an include file created for that purpose.
#include " q-char-sequence "
#include < h-char-sequence >
q-char-sequence:
any sequence of characters except"and
the end-of-line character specifying a filename
h-char-sequence:
any sequence of characters except< >and
the end-of-line character specifying a filename
Both forms cause replacement of that directive by the entire contents of the source file given. The difference between the two forms is how they search for header files when the path is incompletely specified:
| Syntax Form | Action |
| Quoted form | This form, specified as #include “filename.h”, instructs the preprocessor to look in the parent directory and paths specified using the INCLUDE environment variable or the /I compile option for include files. |
| Angle-bracket form | This form, specified as #include <filename.h>, causes the preprocessor to search along the path specified with the INCLUDE environment variable and the /I compile option for header files. |
The q-char-sequence and h-char-sequence are filenames optionally preceded by a directory specification. The filename must name an existing file. The syntax of the file specification depends on the operating system on which the program is compiled.
The preprocessor stops searching as soon as it finds a file with the given name. If you specify a complete, unambiguous path specification for the include file between two sets of double quotation marks (" "), the preprocessor searches only that path specification and ignores the standard directories.
If the filename enclosed in double quotation marks is an incomplete path specification, the preprocessor first searches the “parent” file's directory. A parent file is the file containing the #include directive. For example, if you include a file named file2 within a file named file1, file1 is the parent file.
Include files can be “nested”; that is, an #include directive can appear in a file named by another #include directive. For example, file2, above, could include file3. In this case, file1 would still be the parent of file2, but would be the “grandparent” of file3.
When include files are nested, directory searching begins with the directories of the parent file, then proceeds through the directories of any grandparent files. Thus, searching begins relative to the directory containing the source currently being processed. If the file is not found, the search moves to directories specified on the compiler command line. Finally, the standard directories are searched. For example:
#include <stdio.h>
This statement adds the contents of the file named STDIO.H to the source program. The angle brackets cause the preprocessor to search the standard directories for STDIO.H, after searching directories specified on the command line.
For file specifications enclosed in angle brackets, the preprocessor does not search the current working directory. It begins by searching for the file in the directories specified on the compiler command line, then in the standard directories specified in the INCLUDE environment variable. The following example shows file inclusion using the quoted form:
#include “defs.h”
This example adds the contents of the file specified by DEFS.H to the source program. The double quotation marks mean that the preprocessor searches the directory containing the “parent” source file first.
Nesting of include files can continue up to 10 levels. Once the nested #include is processed, the preprocessor continues to insert the enclosing include file into the original source file.
To locate includable source files, the preprocessor first searches the directories specified by the CL option /I. If the /I option is not present or fails, the preprocessor uses the INCLUDE environment variable to find any include files within angle brackets. If more than one directory appears as part of the /I option or within the INCLUDE environment variable, the preprocessor searches them in the order in which they appear.
For example, the command
CL /ID:\C700\INCLUDE MYPROG.C
causes the preprocessor to search the directory D:\C700\INCLUDE for include files such as STDIO.H. The commands
SET INCLUDE = D:\C700\INCLUDE
CL MYPROG.C
have the same effect. If both sets of searches fail, a fatal error is generated.¨
Microsoft Specific
If the filename is fully specified for an include file with a path that includes a colon (for example, F:\C700\SPECIAL\INCL\TEST.H), the preprocessor follows the path.If the filename is not fully specified, the preprocessor searches the directory of the file that included it. If the file is not found there, the preprocessor searches the parent directory, the parent's parent, and so on, terminating with the root directory. If the include file is not found in any of these directories, the rules specified in the previous Microsoft Specific note apply.¨