diff options
Diffstat (limited to 'devdocs/c/preprocessor%2Finclude.html')
| -rw-r--r-- | devdocs/c/preprocessor%2Finclude.html | 72 |
1 files changed, 72 insertions, 0 deletions
diff --git a/devdocs/c/preprocessor%2Finclude.html b/devdocs/c/preprocessor%2Finclude.html new file mode 100644 index 00000000..b4bf7c7b --- /dev/null +++ b/devdocs/c/preprocessor%2Finclude.html @@ -0,0 +1,72 @@ + <h1 id="firstHeading" class="firstHeading">Source file inclusion</h1> <p>Includes another source file into the current source file at the line immediately after the directive.</p> +<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin"> <tr class="t-sdsc"> <td> <code>#include <</code> <span class="t-spar">h-char-sequence</span> <code>></code> <span class="t-spar">new-line</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>#include "</code> <span class="t-spar">q-char-sequence</span> <code>"</code> <span class="t-spar">new-line</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>#include</code> <span class="t-spar">pp-tokens</span> <span class="t-spar">new-line</span> </td> <td> (3) </td> <td class="t-sdsc-nopad"> </td> +</tr> <tr class="t-sdsc"> <td> <code>__has_include</code> <code>(</code> <code>"</code> <span class="t-spar">q-char-sequence</span> <code>"</code> <code>)</code><br><code>__has_include</code> <code>(</code> <code><</code> <span class="t-spar">h-char-sequence</span> <code>></code> <code>)</code> </td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> <tr class="t-sdsc"> <td> <code>__has_include</code> <code>(</code> <span class="t-spar">string-literal</span> <code>)</code><br><code>__has_include</code> <code>(</code> <code><</code> <span class="t-spar">h-pp-tokens</span> <code>></code> <code>)</code> </td> <td> (5) </td> <td> <span class="t-mark-rev t-since-c23">(since C23)</span> </td> +</tr> +</table> <div class="t-li1"> +<span class="t-li">1)</span> Searches for a header identified uniquely by <span class="t-spar">h-char-sequence</span> and replaces the directive by the entire contents of the header.</div> <div class="t-li1"> +<span class="t-li">2)</span> Searches for a source file identified by <span class="t-spar">q-char-sequence</span> and replaces the directive by the entire contents of the source file. It may fallback to <span class="t-v">(1)</span> and treat <span class="t-spar">q-char-sequence</span> as a header identifier.</div> <div class="t-li1"> +<span class="t-li">3)</span> If neither <span class="t-v">(1)</span> nor <span class="t-v">(2)</span> is matched, <span class="t-spar">pp-tokens</span> will undergo macro replacement. The directive after replacement will be tried to match with <span class="t-v">(1)</span> or <span class="t-v">(2)</span> again.</div> <div class="t-li1"> +<span class="t-li">4)</span> Checks whether a header or source file is available for inclusion.</div> <div class="t-li1"> +<span class="t-li">5)</span> If <span class="t-v">(4)</span> is not matched, <span class="t-spar">h-pp-tokens</span> will undergo macro replacement. The directive after replacement will be tried to match with <span class="t-v">(4)</span> again.</div> <table class="t-par-begin"> <tr class="t-par"> <td> <span class="t-spar">new-line</span> </td> <td> - </td> <td> The new-line character </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">h-char-sequence</span> </td> <td> - </td> <td> A sequence of one or more <span class="t-spar">h-char</span>s, where the appearance of any of the following causes undefined behavior: <ul> +<li> the character <code>'</code> </li> +<li> the character <code>"</code> </li> +<li> the character <code>\</code> </li> +<li> the character sequence <code>//</code> </li> +<li> the character sequence <code>/*</code> </li> +</ul> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">h-char</span> </td> <td> - </td> <td> Any member of the <a href="../language/translation_phases#Phase_5" title="c/language/translation phases">source character set</a> except new-line and <code>></code> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">q-char-sequence</span> </td> <td> - </td> <td> A sequence of one or more <span class="t-spar">q-char</span>s, where the appearance of any of the following causes undefined behavior: <ul> +<li> the character <code>'</code> </li> +<li> the character <code>\</code> </li> +<li> the character sequence <code>//</code> </li> +<li> the character sequence <code>/*</code> </li> +</ul> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">q-char</span> </td> <td> - </td> <td> Any member of the <a href="../language/translation_phases#Phase_5" title="c/language/translation phases">source character set</a> except new-line and <code>"</code> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">pp-tokens</span> </td> <td> - </td> <td> A sequence of one or more <a href="../language/translation_phases#Phase_3" title="c/language/translation phases">preprocessing tokens</a> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">string-literal</span> </td> <td> - </td> <td> A <a href="../language/string_literal" title="c/language/string literal">string literal</a> </td> +</tr> <tr class="t-par"> <td> <span class="t-spar">h-pp-tokens</span> </td> <td> - </td> <td> A sequence of one or more <a href="../language/translation_phases#Phase_3" title="c/language/translation phases">preprocessing tokens</a> except <code>></code> </td> +</tr> +</table> <h3 id="Explanation"> Explanation</h3> <div class="t-li1"> +<span class="t-li">1)</span> Searches for the file identified by <span class="t-spar">h-char-sequence</span> in implementation-defined manner. The intent of this syntax is to search for the files under control of the implementation. Typical implementations search only standard include directories. The standard C library is implicitly included in these standard include directories. The standard include directories usually can be controlled by the user through compiler options.</div> <div class="t-li1"> +<span class="t-li">2)</span> Searches for the file identified by <span class="t-spar">q-char-sequence</span> in implementation-defined manner. The intent of this syntax is to search for the files that are not controlled by the implementation. Typical implementations first search the directory where the current file resides and, only if the file is not found, search the standard include directories as with <span class="t-v">(1)</span>.</div> <div class="t-li1"> +<span class="t-li">3)</span> The preprocessing tokens after <code>include</code> 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 directive resulting after all replacements shall match one of the two previous forms. The method by which a sequence of preprocessing tokens between <code><</code> and <code>></code> preprocessing token pair or a pair of <code>"</code> characters is combined into a single header name preprocessing token is implementation-defined.</div> <div class="t-li1"> +<span class="t-li">4)</span> The header or source file identified by <span class="t-spar">h-char-sequence</span> or <span class="t-spar">q-char-sequence</span> is searched for as if that preprocessing token sequence were the <span class="t-spar">pp-tokens</span> in syntax <span class="t-v">(3)</span>, except that no further macro expansion is performed. If such a directive would not satisfy the syntactic requirements of an <span class="co2">#include</span> directive, the program is ill-formed. The <code>__has_include</code> expression evaluates to <code>1</code> if the search for the source file succeeds, and to <code>0</code> if the search fails.</div> <div class="t-li1"> +<span class="t-li">5)</span> This form is considered only if syntax <span class="t-v">(4)</span> does not match, in which case the preprocessing tokens are processed just as in normal text.</div> <p>In the case the file is not found, the program is ill-formed.</p> +<table class="t-rev-begin"> <tr class="t-rev t-since-c23"> +<td> <p><code>__has_include</code> can be expanded in the expression of <a href="conditional" title="c/preprocessor/conditional"><code> #if</code></a> and <a href="conditional" title="c/preprocessor/conditional"><code> #elif</code></a>. It is treated as a defined macro by <a href="conditional" title="c/preprocessor/conditional"><code> #ifdef</code></a>, <a href="conditional" title="c/preprocessor/conditional"><code> #ifndef</code></a>, <a href="conditional" title="c/preprocessor/conditional"><code> #elifdef</code></a>, <a href="conditional" title="c/preprocessor/conditional"><code> #elifndef</code></a> and <a href="conditional" title="c/preprocessor/conditional"><code>defined</code></a> but cannot be used anywhere else.</p> +</td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td> +</tr> </table> <h3 id="Notes"> Notes</h3> <p>Typical implementations search only standard include directories for syntax (1). The standard C library is implicitly included in these standard include directories. The standard include directories usually can be controlled by the user through compiler options.</p> +<p>The intent of syntax <span class="t-v">(2)</span> is to search for the files that are not controlled by the implementation. Typical implementations first search the directory where the current file resides then falls back to <span class="t-v">(1)</span>.</p> +<p>When a file is included, it is processed by <a href="../language/translation_phases" title="c/language/translation phases">translation phases</a> 1-4, which may include, recursively, expansion of the nested <code>#include</code> directives, up to an implementation-defined nesting limit. To avoid repeated inclusion of the same file and endless recursion when a file includes itself, perhaps transitively, <i>header guards</i> are commonly used: the entire header is wrapped in</p> +<div class="c source-c"><pre data-language="c">#ifndef FOO_H_INCLUDED /* any name uniquely mapped to file name */ +#define FOO_H_INCLUDED +// contents of the file are here +#endif</pre></div> <p>Many compilers also implement the non-standard <a href="impl" title="c/preprocessor/impl"><code>pragma</code></a> <code>#pragma once</code> with similar effects: it disables processing of a file if the same file (where file identity is determined in OS-specific way) has already been included.</p> +<p>A <code>__has_include</code> result of <code>1</code> only means that a header or source file with the specified name exists. It does not mean that the header or source file, when included, would not cause an error or would contain anything useful.</p> +<h3 id="Example"> Example</h3> <h3 id="References"> References</h3> <ul> +<li> C23 standard (ISO/IEC 9899:2023): </li> +<ul> +<li> 6.4.7 Header names (p: 69) </li> +<li> 6.10.1 Conditional inclusion (p: 165-169) </li> +<li> 6.10.2 Source file inclusion (p: 169-170) </li> +</ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 6.10.2 Source file inclusion (p: 119-120) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 6.10.2 Source file inclusion (p: 164-166) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 6.10.2 Source file inclusion (p: 149-151) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 3.8.2 Source file inclusion </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <a href="../index" title="c/header">A list of C Standard Library header files</a> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/preprocessor/include" title="cpp/preprocessor/include">C++ documentation</a></span> for <span class=""><span>Source file inclusion</span></span> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/preprocessor/include" class="_attribution-link">https://en.cppreference.com/w/c/preprocessor/include</a> + </p> +</div> |