[cpp.include]

15 Preprocessing directives [cpp]

15.3 Source file inclusion [cpp.include]

A 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

causes the replacement of that directive by the entire contents of the header or source file identified by .

If the is of the form

a header is identified by a header search for the sequence of characters of the h-char-sequence.

If the is of the form

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

(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).

The resulting sequence of preprocessing tokens shall be of the form

An attempt is then made to form a preprocessing token ([lex.header]) from the whitespace and the characters of the spellings of the ; the treatment of whitespace is implementation-defined.

If the attempt succeeds, the directive with the so-formed is processed as specified for the previous form.

Otherwise, the program is ill-formed, no diagnostic required.

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.

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 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

[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" #else #define INCFILE "versN.h" #endif #include INCFILE

— end example]