#include

Go Up to Preprocessor Directives Index

Syntax

#include <header_name>
#include "header_name"
#include <macro_definition>

For information about #include syntax with Clang-enhanced C++ compilers, see Clang-enhanced C++ Compilers, #include Paths and Lookup.

Description

The #include directive pulls in other named files (known as include files, header files or headers) into the source code. The syntax has three versions:

• The first and second versions imply that no macro expansion will be attempted; in other words, header_name is never scanned for macro identifiers. header_name must be a valid file name with an extension (traditionally .h for header files) and optional path name and path delimiters.
• The third version assumes that neither < nor " appears as the first non-whitespace character following #include; further, it assumes a macro definition exists that will expand the macro identifier into a valid delimited header name with either of the <header_name> or "header_name" formats.

The preprocessor removes the #include line and conceptually replaces it with the entire text of the include file at that point in the source code. The source code itself is not changed, but the compiler "sees" the enlarged text. The placement of the #include can therefore influence the scope and duration of any identifiers in the included file.

If you place an explicit path in the header_name, only that directory will be searched.

The difference between the <header_name> and "header_name" formats lies in the searching algorithm employed in trying to locate the include file:

Syntax Form	Searching Algorithm
Quoted form	The "header_name" version specifies a user-supplied include file; the file is searched in the following order: The same directory of the file that contains the #include statement. The directories of files that include (#include) that file. The current directory. The path specified by the Include file search path (-I) option.
Angle-bracket form	The <header_name> version specifies a standard include file. The search is made successively in each of the include directories in the order they are defined by the Include file search path (-I) option. If the file is not located in any of the default directories, an error message is issued.

See Also

• Using Include Files