15 Preprocessing directives [cpp]

15.3 Source file inclusion [cpp.include]

1
#
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.
2
#
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.
3
#
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.
4
#
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.
5
#
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.
6
#
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]
7
#
A preprocessing directive of the form
# include pp-tokens new-line
(that does not match the previous form) is permitted.
The preprocessing tokens after include 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 behavior is undefined.
[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]
8
#
The implementation shall provide unique mappings for sequences consisting of one or more nondigits or digits ([lex.name]) followed by a period (.) and a single nondigit.
The first character shall not be a digit.
The implementation may ignore distinctions of alphabetical case.
9
#
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.
10
#
If the header identified by the header-name denotes an importable header ([module.import]), it is implementation-defined whether the #include preprocessing directive is instead replaced by an import directive ([cpp.import]) of the form
import header-name ; new-line
11
#
[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]
12
#
[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]