Include Directive

The #include directive is a C preprocessor command that instructs the compiler to replace the directive with the sequence of preprocessing tokens from a specified file. Executed during Translation Phase 4—after the initial lexical analysis (Translation Phase 3) has decomposed the source file into preprocessing tokens—the preprocessor merges the tokenized contents of the target file into the current translation unit.

Syntax The directive supports two distinct syntactical forms, which dictate the search path algorithm the preprocessor uses to locate the file:

#include <filename>
#include "filename"

Search Path Resolution

• Angle Brackets (<filename>): Instructs the preprocessor to search for the specified file exclusively within an implementation-defined list of standard system directories. The exact search path is determined by the compiler configuration, command-line flags (e.g., -I in GCC/Clang), and environment variables.
• Double Quotes ("filename"): Instructs the preprocessor to begin the search in the local directory of the source file that contains the directive. If the file is not resolved in the local directory, the preprocessor automatically falls back to the implementation-defined system directories, effectively mimicking the behavior of the angle bracket syntax.

Processing Characteristics

• Token-Based Processing: The preprocessor operates strictly on streams of preprocessing tokens rather than raw text. The target file is independently decomposed into preprocessing tokens before its contents replace the original #include directive.
• Recursion: The preprocessor handles #include directives recursively. If an included file contains its own #include directives, the preprocessor resolves those nested directives before returning to the parent file. The compiler imposes an implementation-defined limit on the depth of this recursion.
• Idempotency Absence: By default, the #include directive is not idempotent. Including the exact same file multiple times will result in the file’s preprocessing tokens being duplicated sequentially in the translation unit. This behavior is typically managed via preprocessor conditional directives (include guards) within the target file itself.
• Computed Includes: While standard usage relies on string literals or bracketed strings, the directive also supports macro expansion if the tokens following #include do not immediately match the <> or "" forms. The macro must ultimately expand to a valid <filename> or "filename" preprocessing token sequence.

/* Computed Include Example */
#define TARGET_HEADER "config_x86.h"
#include TARGET_HEADER

Master C with Deep Grasping Methodology!

Learn More