7.5 KiB
[cpp.include]
15 Preprocessing directives [cpp]
15.3 Source file inclusion [cpp.include]
A header search for a sequence of characters searches a sequence of places for a header identified uniquely by that sequence of characters.
How the places are determined or the header identified is implementation-defined.
A source file search for a sequence of characters attempts to identify a source file that is named by the sequence of characters.
The named source file is searched for in an implementation-defined manner.
If the implementation does not support a source file search for that sequence of characters, or if the search fails, the result of the source file search is the result of a header search for the same sequence of characters.
A preprocessing directive of the form
include header-name new-line
causes the replacement of that directive by the entire contents of the header or source file identified by header-name.
If the header-name is of the form
< h-char-sequence >
a header is identified by a header search for the sequence of characters of the h-char-sequence.
If the header-name is of the form
" q-char-sequence "
the source file or header is identified by a source file search for the sequence of characters of the q-char-sequence.
If a header search fails, or if a source file search or header search identifies a header or source file that cannot be processed by the implementation, the program is ill-formed.
[Note 1:
If the header or source file cannot be processed, the program is ill-formed even when evaluating __has_include.
â end note]
A preprocessing directive of the form
include pp-tokens new-line
(that does not match the previous form) is permitted.
The preprocessing tokens afterinclude in the directive are processed just as in normal text (i.e., each identifier currently defined as a macro name is replaced by its replacement list of preprocessing tokens).
Then, an attempt is made to form a header-name preprocessing token ([lex.header]) from the whitespace and the characters of the spellings of the resulting sequence of preprocessing tokens; the treatment of whitespace is implementation-defined.
If the attempt succeeds, the directive with the so-formed header-name is processed as specified for the previous form.
Otherwise, the program is ill-formed, no diagnostic required.
[Note 2:
Adjacent string-literals are not concatenated into a single string-literal (see the translation phases in [lex.phases]); thus, an expansion that results in two string-literals is an invalid directive.
â end note]
The implementation shall provide unique mappings for sequences consisting of one or morenondigits or digits ([lex.name]) followed by a period (.) and a singlenondigit.
The first character shall not be a digit.
The implementation may ignore distinctions of alphabetical case.
A#include preprocessing directive may appear in a source file that has been read because of a#include directive in another file, up to an implementation-defined nesting limit.
If the header identified by the header-name denotes an importable header ([module.import]), it isimplementation-defined whether the #include preprocessing directive is instead replaced by an import directive ([cpp.import]) of the form
import header-name ; new-line
[Note 3:
An implementation can provide a mechanism for making arbitrary source files available to the < > search.
However, using the < > form for headers provided with the implementation and the " " form for sources outside the control of the implementation achieves wider portability.
For instance:#include <stdio.h>#include <unistd.h>#include "usefullib.h"#include "myprog.h"
â end note]
[Example 1:
This illustrates macro-replaced#include directives:#if VERSION == 1#define INCFILE "vers1.h"#elif VERSION == 2#define INCFILE "vers2.h" // and so on#else#define INCFILE "versN.h"#endif#include INCFILE
â end example]