173 lines
7.5 KiB
Markdown
173 lines
7.5 KiB
Markdown
[cpp.include]
|
||
|
||
# 15 Preprocessing directives [[cpp]](./#cpp)
|
||
|
||
## 15.3 Source file inclusion [cpp.include]
|
||
|
||
[1](#1)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L697)
|
||
|
||
A [*header search*](#def:search,header "15.3 Source file inclusion [cpp.include]") for a sequence of characters
|
||
searches a sequence of places for a header
|
||
identified uniquely by that sequence of characters[.](#1.sentence-1)
|
||
|
||
How the places are determined or the header identified
|
||
is implementation-defined[.](#1.sentence-2)
|
||
|
||
[2](#2)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L704)
|
||
|
||
A [*source file search*](#def:search,source_file "15.3 Source file inclusion [cpp.include]") for a sequence of characters
|
||
attempts to identify a source file that is named by the sequence of characters[.](#2.sentence-1)
|
||
|
||
The named source file is searched for
|
||
in an implementation-defined manner[.](#2.sentence-2)
|
||
|
||
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[.](#2.sentence-3)
|
||
|
||
[3](#3)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L714)
|
||
|
||
A preprocessing directive of the form
|
||
|
||
# include [*header-name*](lex.header#nt:header-name "5.6 Header names [lex.header]") [*new-line*](cpp.pre#nt:new-line "15.1 Preamble [cpp.pre]")
|
||
|
||
causes the replacement of that directive by the entire contents
|
||
of the header or source file identified by [*header-name*](lex.header#nt:header-name "5.6 Header names [lex.header]")[.](#3.sentence-1)
|
||
|
||
[4](#4)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L722)
|
||
|
||
If the [*header-name*](lex.header#nt:header-name "5.6 Header names [lex.header]") is of the form
|
||
|
||
< [*h-char-sequence*](lex.header#nt:h-char-sequence "5.6 Header names [lex.header]") >
|
||
|
||
a header is identified by a header search for the sequence of characters
|
||
of the [*h-char-sequence*](lex.header#nt:h-char-sequence "5.6 Header names [lex.header]")[.](#4.sentence-1)
|
||
|
||
[5](#5)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L730)
|
||
|
||
If the [*header-name*](lex.header#nt:header-name "5.6 Header names [lex.header]") is of the form
|
||
|
||
" [*q-char-sequence*](lex.header#nt:q-char-sequence "5.6 Header names [lex.header]") "
|
||
|
||
the source file or header is identified by a source file search
|
||
for the sequence of characters of the [*q-char-sequence*](lex.header#nt:q-char-sequence "5.6 Header names [lex.header]")[.](#5.sentence-1)
|
||
|
||
[6](#6)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L738)
|
||
|
||
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[.](#6.sentence-1)
|
||
|
||
[*Note [1](#note-1)*:
|
||
|
||
If the header or source file cannot be processed,
|
||
the program is ill-formed even when evaluating __has_include[.](#6.sentence-2)
|
||
|
||
â *end note*]
|
||
|
||
[7](#7)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L747)
|
||
|
||
A preprocessing directive of the form
|
||
|
||
# include [*pp-tokens*](cpp.pre#nt:pp-tokens "15.1 Preamble [cpp.pre]") [*new-line*](cpp.pre#nt:new-line "15.1 Preamble [cpp.pre]")
|
||
|
||
(that does not match the previous form) is permitted[.](#7.sentence-1)
|
||
|
||
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)[.](#7.sentence-2)
|
||
|
||
Then, an attempt is made to form a [*header-name*](lex.header#nt:header-name "5.6 Header names [lex.header]") preprocessing token ([[lex.header]](lex.header "5.6 Header names")) from the whitespace and the characters
|
||
of the spellings of the resulting sequence of preprocessing tokens;
|
||
the treatment of whitespace
|
||
is implementation-defined[.](#7.sentence-3)
|
||
|
||
If the attempt succeeds, the directive with the so-formed [*header-name*](lex.header#nt:header-name "5.6 Header names [lex.header]") is processed as specified for the previous form[.](#7.sentence-4)
|
||
|
||
Otherwise, the program is ill-formed, no diagnostic required[.](#7.sentence-5)
|
||
|
||
[*Note [2](#note-2)*:
|
||
|
||
Adjacent [*string-literal*](lex.string#nt:string-literal "5.13.5 String literals [lex.string]")*s* are not concatenated into
|
||
a single [*string-literal*](lex.string#nt:string-literal "5.13.5 String literals [lex.string]") (see the translation phases in [[lex.phases]](lex.phases "5.2 Phases of translation"));
|
||
thus, an expansion that results in two [*string-literal*](lex.string#nt:string-literal "5.13.5 String literals [lex.string]")*s* is an
|
||
invalid directive[.](#7.sentence-6)
|
||
|
||
â *end note*]
|
||
|
||
[8](#8)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L774)
|
||
|
||
The implementation shall provide unique mappings for
|
||
sequences consisting of one or more[*nondigit*](lex.name#nt:nondigit "5.11 Identifiers [lex.name]")*s* or [*digit*](lex.name#nt:digit "5.11 Identifiers [lex.name]")*s* ([[lex.name]](lex.name "5.11 Identifiers"))
|
||
followed by a period
|
||
(.)
|
||
and a single[*nondigit*](lex.name#nt:nondigit "5.11 Identifiers [lex.name]")[.](#8.sentence-1)
|
||
|
||
The first character shall not be a [*digit*](lex.name#nt:digit "5.11 Identifiers [lex.name]")[.](#8.sentence-2)
|
||
|
||
The implementation may ignore distinctions of alphabetical case[.](#8.sentence-3)
|
||
|
||
[9](#9)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L785)
|
||
|
||
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[.](#9.sentence-1)
|
||
|
||
[10](#10)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L794)
|
||
|
||
If the header identified by the [*header-name*](lex.header#nt:header-name "5.6 Header names [lex.header]") denotes an importable header ([[module.import]](module.import "10.3 Import declaration")),
|
||
it isimplementation-defined
|
||
whether the #include preprocessing directive
|
||
is instead replaced by an import directive ([[cpp.import]](cpp.import "15.6 Header unit importation")) of the form
|
||
|
||
import [*header-name*](lex.header#nt:header-name "5.6 Header names [lex.header]") ; [*new-line*](cpp.pre#nt:new-line "15.1 Preamble [cpp.pre]")
|
||
|
||
[11](#11)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L806)
|
||
|
||
[*Note [3](#note-3)*:
|
||
|
||
An implementation can provide a mechanism for making arbitrary
|
||
source files available to the < > search[.](#11.sentence-1)
|
||
|
||
However, using the < > form for headers provided
|
||
with the implementation and the " " form for sources
|
||
outside the control of the implementation
|
||
achieves wider portability[.](#11.sentence-2)
|
||
|
||
For instance:#include <stdio.h>#include <unistd.h>#include "usefullib.h"#include "myprog.h"
|
||
|
||
â *end note*]
|
||
|
||
[12](#12)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L822)
|
||
|
||
[*Example [1](#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*]
|