[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*]