Включение исходного файла

Включает другой исходный файл в текущий исходный файл в строке сразу после директивы.

Синтаксис

`#include <` h-char-sequence `>` new-line	(1)
`#include "` q-char-sequence `"` new-line	(2)
`#include` pp-tokens new-line	(3)
`__has_include` `(` `"` q-char-sequence `"` `)` `__has_include` `(` `<` h-char-sequence `>` `)`	(4)	(с C23)
`__has_include` `(` string-literal `)` `__has_include` `(` `<` h-pp-tokens `>` `)`	(5)	(с C23)

1) Ищет заголовок, однозначно идентифицируемый по h-char-sequence, и заменяет директиву всем содержимым заголовка.

2) Ищет исходный файл, идентифицируемый по q-char-sequence, и заменяет директиву всем содержимым исходного файла. Может перейти к (1) и обработать q-char-sequence как идентификатор заголовка.

3) Если ни (1), ни (2) не совпали, pp-tokens будут подвергнуты замене макросов. Директива после замены будет снова проверена на соответствие (1) или (2).

4) Проверяет, доступен ли заголовок или исходный файл для включения.

5) Если (4) не совпало, h-pp-tokens будут подвергнуты замене макросов. Директива после замены будет снова проверена на соответствие (4).

new-line	-	Символ новой строки
h-char-sequence	-	Последовательность одного или более h-charов, где появление любого из следующих приводит к неопределённому поведению: символ `'` символ `"` символ `\` последовательность символов `//` последовательность символов `/*`
h-char	-	Любой член набора символов исходного текста за исключением новой строки и `>`
q-char-sequence	-	Последовательность одного или более q-charов, где появление любого из следующих приводит к неопределённому поведению: символ `'` символ `\` последовательность символов `//` последовательность символов `/*`
q-char	-	Любой член набора символов исходного текста за исключением новой строки и `"`
pp-tokens	-	Последовательность одного или более предварительных токенов
string-literal	-	Строковая константа
h-pp-tokens	-	Последовательность одного или более предварительных токенов, за исключением `>`

Объяснение

1) Ищет файл, идентифицируемый по h-char-sequence, по определённому способом реализации. Цель этого синтаксиса — поиск файлов, управляемых реализацией. Типичные реализации ищут только стандартные директории включения. Стандартная библиотека C неявно включена в эти стандартные директории включения. Стандартные директории включения обычно могут быть настроены пользователем через параметры компилятора.

2) Ищет файл, идентифицируемый по q-char-sequence, по определённому способом реализации. Цель этого синтаксиса — поиск файлов, не управляемых реализацией. Типичные реализации сначала ищут директорию, в которой находится текущий файл, и только если файл не найден, ищут стандартные директории включения, как в (1).

3) Предварительные токены после include в директиве обрабатываются так же, как и в обычном тексте (то есть каждый идентификатор, в настоящее время определённый как имя макроса, заменяется его списком замещающих предварительных токенов). Результирующая директива после всех замен должна соответствовать одной из двух предыдущих форм. Способ объединения последовательности предварительных токенов между < и > предварительным токеном, или парой " символов в один предварительный токен имени заголовка определяется реализацией.

4) Заголовок или исходный файл, идентифицируемый по h-char-sequence или q-char-sequence, ищется так, как будто эта последовательность предварительных токенов была pp-tokens в синтаксисе (3), за исключением того, что дальнейшее расширение макросов не выполняется. Если такая директива не удовлетворяет синтаксическим требованиям директивы #include, программа является ошибочной. Выражение __has_include равно 1 если поиск исходного файла успешен, и 0 если поиск не удался.

5) Эта форма рассматривается только в том случае, если синтаксис (4) не совпадает, в этом случае предварительные токены обрабатываются так же, как и в обычном тексте.

В случае, если файл не найден, программа является ошибочной.

__has_include может быть расширен в выражении #if и #elif. Он обрабатывается как определённый макрос #ifdef, #ifndef, #elifdef, #elifndef и defined, но не может быть использован нигде в другом месте.

(с C23)

Примечания

Типичные реализации ищут только стандартные директории включения для синтаксиса (1). Стандартная библиотека C неявно включена в эти стандартные директории включения. Стандартные директории включения обычно могут быть настроены пользователем через параметры компилятора.

Цель синтаксиса (2) — поиск файлов, не управляемых реализацией. Типичные реализации сначала ищут директорию, в которой находится текущий файл, затем переходят к (1).

Когда файл включён, он обрабатывается фазами трансляции 1-4, которые могут включать, рекурсивно, расширение вложенных #include директив, до определённого реализацией лимита вложения. Чтобы избежать повторного включения одного и того же файла и бесконечной рекурсии, когда файл включает сам себя, возможно, транзитивно, обычно используются защиты заголовков: весь заголовок заключён в

#ifndef FOO_H_INCLUDED /* any name uniquely mapped to file name */
#define FOO_H_INCLUDED
// contents of the file are here
#endif

Многие компиляторы также реализуют нестандартный pragma #pragma once с аналогичным эффектом: он отключает обработку файла, если тот же файл (где идентификация файла определяется способом, специфичным для ОС) уже был включен.

Результат __has_include 1 только означает, что заголовок или исходный файл с указанным именем существует. Это не означает, что заголовок или исходный файл, при включении, не вызовут ошибку или будут содержать что-либо полезное.

Пример

Ссылки

Стандарт C23 (ISO/IEC 9899:2023):

6.4.7 Имена заголовков (с. 69)
6.10.1 Условное включение (с. 165-169)
6.10.2 Включение исходного файла (с. 169-170)

Стандарт C17 (ISO/IEC 9899:2018):

6.10.2 Включение исходного файла (с. 119-120)

Стандарт C11 (ISO/IEC 9899:2011):

6.10.2 Включение исходного файла (с. 164-166)

Стандарт C99 (ISO/IEC 9899:1999):

6.10.2 Включение исходного файла (с. 149-151)

Стандарт C89/C90 (ISO/IEC 9899:1990):

3.8.2 Включение исходного файла

См. также

Список заголовков стандартной библиотеки C
Документация C++ для Включения исходного файла

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/c/preprocessor/include