7.4 Include Files

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. These files are called “header files.” You can organize constant and macro definitions into header 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.

Syntax

control-line :
#include "path-spec" new-line /* Programmer-supplied header files */
#include <path-spec> new-line /* Standard C header files */

Both forms cause replacement of the #include directive by the contents of the source file given. The first form is usually used for header files that you write. The second form is used for the standard C header files.

The path-spec is a filename optionally preceded by a directory specification. The filename must name an existing file. The syntax of the path-spec depends on the operating system on which the program is compiled.

Microsoft Specific

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. Unambiguous path specifications are called “fully qualified.”A fully specified filename is a filename where the first character is a forward slash (/) or a backslash (\) or the second character is a colon (:). For example, F:\C7\SPECIAL\INCL\TEST.H) is a fully qualified path specification.If the filename enclosed in double quotation marks is an incomplete (or “relative”) 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 could include file3. In this case, file1 would still be the parent of file2 but would also be the “grandparent” of file3.

For include files specified as #include "path-spec", 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 file currently being processed. If there is no grandparent file and the file has not been found, the search continues as if the filename were enclosed in angle brackets.

For file specifications enclosed in angle brackets, the preprocessor does not search directories of the parent files. Instead, it begins by searching for the file in the directories specified on the compiler command line following /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. The INCLUDE environment variable can contain multiple paths separated by semicolons (;). 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 they appear.

Nesting of include files is limited by the available memory. Once the nested #include is processed, the preprocessor continues to insert the enclosing include file into the original source file.

For example, the command

CL /ID:\MSC\INCLUDE MYPROG.C

causes the preprocessor to search the directory D:\MSC\INCLUDE for include files such as STDIO.H. The commands

SET INCLUDE = D:\MSC\INCLUDE

CL MYPROG.C

have the same effect. If both sets of searches fail, a fatal error is generated.

Note:

Programs containing references to fully specified include files may not compile on other computers.¨