diff options
| author | alk3pInjection <webmaster@raspii.tech> | 2024-02-04 16:16:35 +0800 |
|---|---|---|
| committer | alk3pInjection <webmaster@raspii.tech> | 2024-02-04 16:16:35 +0800 |
| commit | abdaadbcae30fe0c9a66c7516798279fdfd97750 (patch) | |
| tree | 00a54a6e25601e43876d03c1a4a12a749d4a914c /share/doc/cpp | |
https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads
Change-Id: I7303388733328cd98ab9aa3c30236db67f2e9e9c
Diffstat (limited to 'share/doc/cpp')
76 files changed, 12867 insertions, 0 deletions
diff --git a/share/doc/cpp/Alternatives-to-Wrapper-_0023ifndef.html b/share/doc/cpp/Alternatives-to-Wrapper-_0023ifndef.html new file mode 100644 index 0000000..a379cb1 --- /dev/null +++ b/share/doc/cpp/Alternatives-to-Wrapper-_0023ifndef.html @@ -0,0 +1,115 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Alternatives to Wrapper #ifndef</title> + +<meta name="description" content="The C Preprocessor: Alternatives to Wrapper #ifndef"> +<meta name="keywords" content="The C Preprocessor: Alternatives to Wrapper #ifndef"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Header-Files.html#Header-Files" rel="up" title="Header Files"> +<link href="Computed-Includes.html#Computed-Includes" rel="next" title="Computed Includes"> +<link href="Once_002dOnly-Headers.html#Once_002dOnly-Headers" rel="previous" title="Once-Only Headers"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Alternatives-to-Wrapper-_0023ifndef"></a> +<div class="header"> +<p> +Next: <a href="Computed-Includes.html#Computed-Includes" accesskey="n" rel="next">Computed Includes</a>, Previous: <a href="Once_002dOnly-Headers.html#Once_002dOnly-Headers" accesskey="p" rel="previous">Once-Only Headers</a>, Up: <a href="Header-Files.html#Header-Files" accesskey="u" rel="up">Header Files</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Alternatives-to-Wrapper-_0023ifndef-1"></a> +<h3 class="section">2.5 Alternatives to Wrapper #ifndef</h3> + +<p>CPP supports two more ways of indicating that a header file should be +read only once. Neither one is as portable as a wrapper ‘<samp>#ifndef</samp>’ +and we recommend you do not use them in new programs, with the caveat +that ‘<samp>#import</samp>’ is standard practice in Objective-C. +</p> +<a name="index-_0023import"></a> +<p>CPP supports a variant of ‘<samp>#include</samp>’ called ‘<samp>#import</samp>’ which +includes a file, but does so at most once. If you use ‘<samp>#import</samp>’ +instead of ‘<samp>#include</samp>’, then you don’t need the conditionals +inside the header file to prevent multiple inclusion of the contents. +‘<samp>#import</samp>’ is standard in Objective-C, but is considered a +deprecated extension in C and C++. +</p> +<p>‘<samp>#import</samp>’ is not a well designed feature. It requires the users of +a header file to know that it should only be included once. It is much +better for the header file’s implementor to write the file so that users +don’t need to know this. Using a wrapper ‘<samp>#ifndef</samp>’ accomplishes +this goal. +</p> +<p>In the present implementation, a single use of ‘<samp>#import</samp>’ will +prevent the file from ever being read again, by either ‘<samp>#import</samp>’ or +‘<samp>#include</samp>’. You should not rely on this; do not use both +‘<samp>#import</samp>’ and ‘<samp>#include</samp>’ to refer to the same header file. +</p> +<p>Another way to prevent a header file from being included more than once +is with the ‘<samp>#pragma once</samp>’ directive (see <a href="Pragmas.html#Pragmas">Pragmas</a>). +‘<samp>#pragma once</samp>’ does not have the problems that ‘<samp>#import</samp>’ does, +but it is not recognized by all preprocessors, so you cannot rely on it +in a portable program. +</p> + + + +</body> +</html> diff --git a/share/doc/cpp/Argument-Prescan.html b/share/doc/cpp/Argument-Prescan.html new file mode 100644 index 0000000..9e99905 --- /dev/null +++ b/share/doc/cpp/Argument-Prescan.html @@ -0,0 +1,180 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Argument Prescan</title> + +<meta name="description" content="The C Preprocessor: Argument Prescan"> +<meta name="keywords" content="The C Preprocessor: Argument Prescan"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Macro-Pitfalls.html#Macro-Pitfalls" rel="up" title="Macro Pitfalls"> +<link href="Newlines-in-Arguments.html#Newlines-in-Arguments" rel="next" title="Newlines in Arguments"> +<link href="Self_002dReferential-Macros.html#Self_002dReferential-Macros" rel="previous" title="Self-Referential Macros"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Argument-Prescan"></a> +<div class="header"> +<p> +Next: <a href="Newlines-in-Arguments.html#Newlines-in-Arguments" accesskey="n" rel="next">Newlines in Arguments</a>, Previous: <a href="Self_002dReferential-Macros.html#Self_002dReferential-Macros" accesskey="p" rel="previous">Self-Referential Macros</a>, Up: <a href="Macro-Pitfalls.html#Macro-Pitfalls" accesskey="u" rel="up">Macro Pitfalls</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Argument-Prescan-1"></a> +<h4 class="subsection">3.10.6 Argument Prescan</h4> +<a name="index-expansion-of-arguments"></a> +<a name="index-macro-argument-expansion"></a> +<a name="index-prescan-of-macro-arguments"></a> + +<p>Macro arguments are completely macro-expanded before they are +substituted into a macro body, unless they are stringized or pasted +with other tokens. After substitution, the entire macro body, including +the substituted arguments, is scanned again for macros to be expanded. +The result is that the arguments are scanned <em>twice</em> to expand +macro calls in them. +</p> +<p>Most of the time, this has no effect. If the argument contained any +macro calls, they are expanded during the first scan. The result +therefore contains no macro calls, so the second scan does not change +it. If the argument were substituted as given, with no prescan, the +single remaining scan would find the same macro calls and produce the +same results. +</p> +<p>You might expect the double scan to change the results when a +self-referential macro is used in an argument of another macro +(see <a href="Self_002dReferential-Macros.html#Self_002dReferential-Macros">Self-Referential Macros</a>): the self-referential macro would be +expanded once in the first scan, and a second time in the second scan. +However, this is not what happens. The self-references that do not +expand in the first scan are marked so that they will not expand in the +second scan either. +</p> +<p>You might wonder, “Why mention the prescan, if it makes no difference? +And why not skip it and make the preprocessor faster?” The answer is +that the prescan does make a difference in three special cases: +</p> +<ul> +<li> Nested calls to a macro. + +<p>We say that <em>nested</em> calls to a macro occur when a macro’s argument +contains a call to that very macro. For example, if <code>f</code> is a macro +that expects one argument, <code>f (f (1))</code> is a nested pair of calls to +<code>f</code>. The desired expansion is made by expanding <code>f (1)</code> and +substituting that into the definition of <code>f</code>. The prescan causes +the expected result to happen. Without the prescan, <code>f (1)</code> itself +would be substituted as an argument, and the inner use of <code>f</code> would +appear during the main scan as an indirect self-reference and would not +be expanded. +</p> +</li><li> Macros that call other macros that stringize or concatenate. + +<p>If an argument is stringized or concatenated, the prescan does not +occur. If you <em>want</em> to expand a macro, then stringize or +concatenate its expansion, you can do that by causing one macro to call +another macro that does the stringizing or concatenation. For +instance, if you have +</p> +<div class="smallexample"> +<pre class="smallexample">#define AFTERX(x) X_ ## x +#define XAFTERX(x) AFTERX(x) +#define TABLESIZE 1024 +#define BUFSIZE TABLESIZE +</pre></div> + +<p>then <code>AFTERX(BUFSIZE)</code> expands to <code>X_BUFSIZE</code>, and +<code>XAFTERX(BUFSIZE)</code> expands to <code>X_1024</code>. (Not to +<code>X_TABLESIZE</code>. Prescan always does a complete expansion.) +</p> +</li><li> Macros used in arguments, whose expansions contain unshielded commas. + +<p>This can cause a macro expanded on the second scan to be called with the +wrong number of arguments. Here is an example: +</p> +<div class="smallexample"> +<pre class="smallexample">#define foo a,b +#define bar(x) lose(x) +#define lose(x) (1 + (x)) +</pre></div> + +<p>We would like <code>bar(foo)</code> to turn into <code>(1 + (foo))</code>, which +would then turn into <code>(1 + (a,b))</code>. Instead, <code>bar(foo)</code> +expands into <code>lose(a,b)</code>, and you get an error because <code>lose</code> +requires a single argument. In this case, the problem is easily solved +by the same parentheses that ought to be used to prevent misnesting of +arithmetic operations: +</p> +<div class="smallexample"> +<pre class="smallexample">#define foo (a,b) +</pre><pre class="smallexample">or +</pre><pre class="smallexample">#define bar(x) lose((x)) +</pre></div> + +<p>The extra pair of parentheses prevents the comma in <code>foo</code>’s +definition from being interpreted as an argument separator. +</p> +</li></ul> + +<hr> +<div class="header"> +<p> +Next: <a href="Newlines-in-Arguments.html#Newlines-in-Arguments" accesskey="n" rel="next">Newlines in Arguments</a>, Previous: <a href="Self_002dReferential-Macros.html#Self_002dReferential-Macros" accesskey="p" rel="previous">Self-Referential Macros</a>, Up: <a href="Macro-Pitfalls.html#Macro-Pitfalls" accesskey="u" rel="up">Macro Pitfalls</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/C_002b_002b-Named-Operators.html b/share/doc/cpp/C_002b_002b-Named-Operators.html new file mode 100644 index 0000000..24fcb70 --- /dev/null +++ b/share/doc/cpp/C_002b_002b-Named-Operators.html @@ -0,0 +1,113 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: C++ Named Operators</title> + +<meta name="description" content="The C Preprocessor: C++ Named Operators"> +<meta name="keywords" content="The C Preprocessor: C++ Named Operators"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Predefined-Macros.html#Predefined-Macros" rel="up" title="Predefined Macros"> +<link href="Undefining-and-Redefining-Macros.html#Undefining-and-Redefining-Macros" rel="next" title="Undefining and Redefining Macros"> +<link href="System_002dspecific-Predefined-Macros.html#System_002dspecific-Predefined-Macros" rel="previous" title="System-specific Predefined Macros"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="C_002b_002b-Named-Operators"></a> +<div class="header"> +<p> +Previous: <a href="System_002dspecific-Predefined-Macros.html#System_002dspecific-Predefined-Macros" accesskey="p" rel="previous">System-specific Predefined Macros</a>, Up: <a href="Predefined-Macros.html#Predefined-Macros" accesskey="u" rel="up">Predefined Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="C_002b_002b-Named-Operators-1"></a> +<h4 class="subsection">3.7.4 C++ Named Operators</h4> +<a name="index-named-operators"></a> +<a name="index-C_002b_002b-named-operators"></a> +<a name="index-iso646_002eh"></a> + +<p>In C++, there are eleven keywords which are simply alternate spellings +of operators normally written with punctuation. These keywords are +treated as such even in the preprocessor. They function as operators in +‘<samp>#if</samp>’, and they cannot be defined as macros or poisoned. In C, you +can request that those keywords take their C++ meaning by including +<samp>iso646.h</samp>. That header defines each one as a normal object-like +macro expanding to the appropriate punctuator. +</p> +<p>These are the named operators and their corresponding punctuators: +</p> +<table> +<tr><td>Named Operator</td><td>Punctuator</td></tr> +<tr><td><code>and</code></td><td><code>&&</code></td></tr> +<tr><td><code>and_eq</code></td><td><code>&=</code></td></tr> +<tr><td><code>bitand</code></td><td><code>&</code></td></tr> +<tr><td><code>bitor</code></td><td><code>|</code></td></tr> +<tr><td><code>compl</code></td><td><code>~</code></td></tr> +<tr><td><code>not</code></td><td><code>!</code></td></tr> +<tr><td><code>not_eq</code></td><td><code>!=</code></td></tr> +<tr><td><code>or</code></td><td><code>||</code></td></tr> +<tr><td><code>or_eq</code></td><td><code>|=</code></td></tr> +<tr><td><code>xor</code></td><td><code>^</code></td></tr> +<tr><td><code>xor_eq</code></td><td><code>^=</code></td></tr> +</table> + + + + +</body> +</html> diff --git a/share/doc/cpp/Character-sets.html b/share/doc/cpp/Character-sets.html new file mode 100644 index 0000000..495469c --- /dev/null +++ b/share/doc/cpp/Character-sets.html @@ -0,0 +1,140 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Character sets</title> + +<meta name="description" content="The C Preprocessor: Character sets"> +<meta name="keywords" content="The C Preprocessor: Character sets"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Overview.html#Overview" rel="up" title="Overview"> +<link href="Initial-processing.html#Initial-processing" rel="next" title="Initial processing"> +<link href="Overview.html#Overview" rel="previous" title="Overview"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Character-sets"></a> +<div class="header"> +<p> +Next: <a href="Initial-processing.html#Initial-processing" accesskey="n" rel="next">Initial processing</a>, Up: <a href="Overview.html#Overview" accesskey="u" rel="up">Overview</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Character-sets-1"></a> +<h3 class="section">1.1 Character sets</h3> + +<p>Source code character set processing in C and related languages is +rather complicated. The C standard discusses two character sets, but +there are really at least four. +</p> +<p>The files input to CPP might be in any character set at all. CPP’s +very first action, before it even looks for line boundaries, is to +convert the file into the character set it uses for internal +processing. That set is what the C standard calls the <em>source</em> +character set. It must be isomorphic with ISO 10646, also known as +Unicode. CPP uses the UTF-8 encoding of Unicode. +</p> +<p>The character sets of the input files are specified using the +<samp>-finput-charset=</samp> option. +</p> +<p>All preprocessing work (the subject of the rest of this manual) is +carried out in the source character set. If you request textual +output from the preprocessor with the <samp>-E</samp> option, it will be +in UTF-8. +</p> +<p>After preprocessing is complete, string and character constants are +converted again, into the <em>execution</em> character set. This +character set is under control of the user; the default is UTF-8, +matching the source character set. Wide string and character +constants have their own character set, which is not called out +specifically in the standard. Again, it is under control of the user. +The default is UTF-16 or UTF-32, whichever fits in the target’s +<code>wchar_t</code> type, in the target machine’s byte +order.<a name="DOCF1" href="#FOOT1"><sup>1</sup></a> Octal and hexadecimal escape sequences do not undergo +conversion; <tt>'\x12'</tt> has the value 0x12 regardless of the currently +selected execution character set. All other escapes are replaced by +the character in the source character set that they represent, then +converted to the execution character set, just like unescaped +characters. +</p> +<p>In identifiers, characters outside the ASCII range can be specified +with the ‘<samp>\u</samp>’ and ‘<samp>\U</samp>’ escapes or used directly in the input +encoding. If strict ISO C90 conformance is specified with an option +such as <samp>-std=c90</samp>, or <samp>-fno-extended-identifiers</samp> is +used, then those constructs are not permitted in identifiers. +</p> +<div class="footnote"> +<hr> +<h4 class="footnotes-heading">Footnotes</h4> + +<h3><a name="FOOT1" href="#DOCF1">(1)</a></h3> +<p>UTF-16 does not meet the requirements of the C +standard for a wide character set, but the choice of 16-bit +<code>wchar_t</code> is enshrined in some system ABIs so we cannot fix +this.</p> +</div> +<hr> +<div class="header"> +<p> +Next: <a href="Initial-processing.html#Initial-processing" accesskey="n" rel="next">Initial processing</a>, Up: <a href="Overview.html#Overview" accesskey="u" rel="up">Overview</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Common-Predefined-Macros.html b/share/doc/cpp/Common-Predefined-Macros.html new file mode 100644 index 0000000..c87b66a --- /dev/null +++ b/share/doc/cpp/Common-Predefined-Macros.html @@ -0,0 +1,705 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Common Predefined Macros</title> + +<meta name="description" content="The C Preprocessor: Common Predefined Macros"> +<meta name="keywords" content="The C Preprocessor: Common Predefined Macros"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Predefined-Macros.html#Predefined-Macros" rel="up" title="Predefined Macros"> +<link href="System_002dspecific-Predefined-Macros.html#System_002dspecific-Predefined-Macros" rel="next" title="System-specific Predefined Macros"> +<link href="Standard-Predefined-Macros.html#Standard-Predefined-Macros" rel="previous" title="Standard Predefined Macros"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Common-Predefined-Macros"></a> +<div class="header"> +<p> +Next: <a href="System_002dspecific-Predefined-Macros.html#System_002dspecific-Predefined-Macros" accesskey="n" rel="next">System-specific Predefined Macros</a>, Previous: <a href="Standard-Predefined-Macros.html#Standard-Predefined-Macros" accesskey="p" rel="previous">Standard Predefined Macros</a>, Up: <a href="Predefined-Macros.html#Predefined-Macros" accesskey="u" rel="up">Predefined Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Common-Predefined-Macros-1"></a> +<h4 class="subsection">3.7.2 Common Predefined Macros</h4> +<a name="index-common-predefined-macros"></a> + +<p>The common predefined macros are GNU C extensions. They are available +with the same meanings regardless of the machine or operating system on +which you are using GNU C or GNU Fortran. Their names all start with +double underscores. +</p> +<dl compact="compact"> +<dt><code>__COUNTER__</code></dt> +<dd><p>This macro expands to sequential integral values starting from 0. In +conjunction with the <code>##</code> operator, this provides a convenient means to +generate unique identifiers. Care must be taken to ensure that +<code>__COUNTER__</code> is not expanded prior to inclusion of precompiled headers +which use it. Otherwise, the precompiled headers will not be used. +</p> +</dd> +<dt><code>__GFORTRAN__</code></dt> +<dd><p>The GNU Fortran compiler defines this. +</p> +</dd> +<dt><code>__GNUC__</code></dt> +<dt><code>__GNUC_MINOR__</code></dt> +<dt><code>__GNUC_PATCHLEVEL__</code></dt> +<dd><p>These macros are defined by all GNU compilers that use the C +preprocessor: C, C++, Objective-C and Fortran. Their values are the major +version, minor version, and patch level of the compiler, as integer +constants. For example, GCC version <var>x</var>.<var>y</var>.<var>z</var> +defines <code>__GNUC__</code> to <var>x</var>, <code>__GNUC_MINOR__</code> to <var>y</var>, +and <code>__GNUC_PATCHLEVEL__</code> to <var>z</var>. These +macros are also defined if you invoke the preprocessor directly. +</p> +<p>If all you need to know is whether or not your program is being compiled +by GCC, or a non-GCC compiler that claims to accept the GNU C dialects, +you can simply test <code>__GNUC__</code>. If you need to write code +which depends on a specific version, you must be more careful. Each +time the minor version is increased, the patch level is reset to zero; +each time the major version is increased, the +minor version and patch level are reset. If you wish to use the +predefined macros directly in the conditional, you will need to write it +like this: +</p> +<div class="smallexample"> +<pre class="smallexample">/* <span class="roman">Test for GCC > 3.2.0</span> */ +#if __GNUC__ > 3 || \ + (__GNUC__ == 3 && (__GNUC_MINOR__ > 2 || \ + (__GNUC_MINOR__ == 2 && \ + __GNUC_PATCHLEVEL__ > 0)) +</pre></div> + +<p>Another approach is to use the predefined macros to +calculate a single number, then compare that against a threshold: +</p> +<div class="smallexample"> +<pre class="smallexample">#define GCC_VERSION (__GNUC__ * 10000 \ + + __GNUC_MINOR__ * 100 \ + + __GNUC_PATCHLEVEL__) +… +/* <span class="roman">Test for GCC > 3.2.0</span> */ +#if GCC_VERSION > 30200 +</pre></div> + +<p>Many people find this form easier to understand. +</p> +</dd> +<dt><code>__GNUG__</code></dt> +<dd><p>The GNU C++ compiler defines this. Testing it is equivalent to +testing <code><span class="nolinebreak">(__GNUC__</span> && <span class="nolinebreak">__cplusplus)</span><!-- /@w --></code>. +</p> +</dd> +<dt><code>__STRICT_ANSI__</code></dt> +<dd><p>GCC defines this macro if and only if the <samp>-ansi</samp> switch, or a +<samp>-std</samp> switch specifying strict conformance to some version of ISO C +or ISO C++, was specified when GCC was invoked. It is defined to ‘<samp>1</samp>’. +This macro exists primarily to direct GNU libc’s header files to use only +definitions found in standard C. +</p> +</dd> +<dt><code>__BASE_FILE__</code></dt> +<dd><p>This macro expands to the name of the main input file, in the form +of a C string constant. This is the source file that was specified +on the command line of the preprocessor or C compiler. +</p> +</dd> +<dt><code>__FILE_NAME__</code></dt> +<dd><p>This macro expands to the basename of the current input file, in the +form of a C string constant. This is the last path component by which +the preprocessor opened the file. For example, processing +<code>"/usr/local/include/myheader.h"</code> would set this +macro to <code>"myheader.h"</code>. +</p> +</dd> +<dt><code>__INCLUDE_LEVEL__</code></dt> +<dd><p>This macro expands to a decimal integer constant that represents the +depth of nesting in include files. The value of this macro is +incremented on every ‘<samp>#include</samp>’ directive and decremented at the +end of every included file. It starts out at 0, its value within the +base file specified on the command line. +</p> +</dd> +<dt><code>__ELF__</code></dt> +<dd><p>This macro is defined if the target uses the ELF object format. +</p> +</dd> +<dt><code>__VERSION__</code></dt> +<dd><p>This macro expands to a string constant which describes the version of +the compiler in use. You should not rely on its contents having any +particular form, but it can be counted on to contain at least the +release number. +</p> +</dd> +<dt><code>__OPTIMIZE__</code></dt> +<dt><code>__OPTIMIZE_SIZE__</code></dt> +<dt><code>__NO_INLINE__</code></dt> +<dd><p>These macros describe the compilation mode. <code>__OPTIMIZE__</code> is +defined in all optimizing compilations. <code>__OPTIMIZE_SIZE__</code> is +defined if the compiler is optimizing for size, not speed. +<code>__NO_INLINE__</code> is defined if no functions will be inlined into +their callers (when not optimizing, or when inlining has been +specifically disabled by <samp>-fno-inline</samp>). +</p> +<p>These macros cause certain GNU header files to provide optimized +definitions, using macros or inline functions, of system library +functions. You should not use these macros in any way unless you make +sure that programs will execute with the same effect whether or not they +are defined. If they are defined, their value is 1. +</p> +</dd> +<dt><code>__GNUC_GNU_INLINE__</code></dt> +<dd><p>GCC defines this macro if functions declared <code>inline</code> will be +handled in GCC’s traditional gnu90 mode. Object files will contain +externally visible definitions of all functions declared <code>inline</code> +without <code>extern</code> or <code>static</code>. They will not contain any +definitions of any functions declared <code>extern inline</code>. +</p> +</dd> +<dt><code>__GNUC_STDC_INLINE__</code></dt> +<dd><p>GCC defines this macro if functions declared <code>inline</code> will be +handled according to the ISO C99 or later standards. Object files will contain +externally visible definitions of all functions declared <code>extern +inline</code>. They will not contain definitions of any functions declared +<code>inline</code> without <code>extern</code>. +</p> +<p>If this macro is defined, GCC supports the <code>gnu_inline</code> function +attribute as a way to always get the gnu90 behavior. +</p> +</dd> +<dt><code>__CHAR_UNSIGNED__</code></dt> +<dd><p>GCC defines this macro if and only if the data type <code>char</code> is +unsigned on the target machine. It exists to cause the standard header +file <samp>limits.h</samp> to work correctly. You should not use this macro +yourself; instead, refer to the standard macros defined in <samp>limits.h</samp>. +</p> +</dd> +<dt><code>__WCHAR_UNSIGNED__</code></dt> +<dd><p>Like <code>__CHAR_UNSIGNED__</code>, this macro is defined if and only if the +data type <code>wchar_t</code> is unsigned and the front-end is in C++ mode. +</p> +</dd> +<dt><code>__REGISTER_PREFIX__</code></dt> +<dd><p>This macro expands to a single token (not a string constant) which is +the prefix applied to CPU register names in assembly language for this +target. You can use it to write assembly that is usable in multiple +environments. For example, in the <code>m68k-aout</code> environment it +expands to nothing, but in the <code>m68k-coff</code> environment it expands +to a single ‘<samp>%</samp>’. +</p> +</dd> +<dt><code>__USER_LABEL_PREFIX__</code></dt> +<dd><p>This macro expands to a single token which is the prefix applied to +user labels (symbols visible to C code) in assembly. For example, in +the <code>m68k-aout</code> environment it expands to an ‘<samp>_</samp>’, but in the +<code>m68k-coff</code> environment it expands to nothing. +</p> +<p>This macro will have the correct definition even if +<samp>-f(no-)underscores</samp> is in use, but it will not be correct if +target-specific options that adjust this prefix are used (e.g. the +OSF/rose <samp>-mno-underscores</samp> option). +</p> +</dd> +<dt><code>__SIZE_TYPE__</code></dt> +<dt><code>__PTRDIFF_TYPE__</code></dt> +<dt><code>__WCHAR_TYPE__</code></dt> +<dt><code>__WINT_TYPE__</code></dt> +<dt><code>__INTMAX_TYPE__</code></dt> +<dt><code>__UINTMAX_TYPE__</code></dt> +<dt><code>__SIG_ATOMIC_TYPE__</code></dt> +<dt><code>__INT8_TYPE__</code></dt> +<dt><code>__INT16_TYPE__</code></dt> +<dt><code>__INT32_TYPE__</code></dt> +<dt><code>__INT64_TYPE__</code></dt> +<dt><code>__UINT8_TYPE__</code></dt> +<dt><code>__UINT16_TYPE__</code></dt> +<dt><code>__UINT32_TYPE__</code></dt> +<dt><code>__UINT64_TYPE__</code></dt> +<dt><code>__INT_LEAST8_TYPE__</code></dt> +<dt><code>__INT_LEAST16_TYPE__</code></dt> +<dt><code>__INT_LEAST32_TYPE__</code></dt> +<dt><code>__INT_LEAST64_TYPE__</code></dt> +<dt><code>__UINT_LEAST8_TYPE__</code></dt> +<dt><code>__UINT_LEAST16_TYPE__</code></dt> +<dt><code>__UINT_LEAST32_TYPE__</code></dt> +<dt><code>__UINT_LEAST64_TYPE__</code></dt> +<dt><code>__INT_FAST8_TYPE__</code></dt> +<dt><code>__INT_FAST16_TYPE__</code></dt> +<dt><code>__INT_FAST32_TYPE__</code></dt> +<dt><code>__INT_FAST64_TYPE__</code></dt> +<dt><code>__UINT_FAST8_TYPE__</code></dt> +<dt><code>__UINT_FAST16_TYPE__</code></dt> +<dt><code>__UINT_FAST32_TYPE__</code></dt> +<dt><code>__UINT_FAST64_TYPE__</code></dt> +<dt><code>__INTPTR_TYPE__</code></dt> +<dt><code>__UINTPTR_TYPE__</code></dt> +<dd><p>These macros are defined to the correct underlying types for the +<code>size_t</code>, <code>ptrdiff_t</code>, <code>wchar_t</code>, <code>wint_t</code>, +<code>intmax_t</code>, <code>uintmax_t</code>, <code>sig_atomic_t</code>, <code>int8_t</code>, +<code>int16_t</code>, <code>int32_t</code>, <code>int64_t</code>, <code>uint8_t</code>, +<code>uint16_t</code>, <code>uint32_t</code>, <code>uint64_t</code>, +<code>int_least8_t</code>, <code>int_least16_t</code>, <code>int_least32_t</code>, +<code>int_least64_t</code>, <code>uint_least8_t</code>, <code>uint_least16_t</code>, +<code>uint_least32_t</code>, <code>uint_least64_t</code>, <code>int_fast8_t</code>, +<code>int_fast16_t</code>, <code>int_fast32_t</code>, <code>int_fast64_t</code>, +<code>uint_fast8_t</code>, <code>uint_fast16_t</code>, <code>uint_fast32_t</code>, +<code>uint_fast64_t</code>, <code>intptr_t</code>, and <code>uintptr_t</code> typedefs, +respectively. They exist to make the standard header files +<samp>stddef.h</samp>, <samp>stdint.h</samp>, and <samp>wchar.h</samp> work correctly. +You should not use these macros directly; instead, include the +appropriate headers and use the typedefs. Some of these macros may +not be defined on particular systems if GCC does not provide a +<samp>stdint.h</samp> header on those systems. +</p> +</dd> +<dt><code>__CHAR_BIT__</code></dt> +<dd><p>Defined to the number of bits used in the representation of the +<code>char</code> data type. It exists to make the standard header given +numerical limits work correctly. You should not use +this macro directly; instead, include the appropriate headers. +</p> +</dd> +<dt><code>__SCHAR_MAX__</code></dt> +<dt><code>__WCHAR_MAX__</code></dt> +<dt><code>__SHRT_MAX__</code></dt> +<dt><code>__INT_MAX__</code></dt> +<dt><code>__LONG_MAX__</code></dt> +<dt><code>__LONG_LONG_MAX__</code></dt> +<dt><code>__WINT_MAX__</code></dt> +<dt><code>__SIZE_MAX__</code></dt> +<dt><code>__PTRDIFF_MAX__</code></dt> +<dt><code>__INTMAX_MAX__</code></dt> +<dt><code>__UINTMAX_MAX__</code></dt> +<dt><code>__SIG_ATOMIC_MAX__</code></dt> +<dt><code>__INT8_MAX__</code></dt> +<dt><code>__INT16_MAX__</code></dt> +<dt><code>__INT32_MAX__</code></dt> +<dt><code>__INT64_MAX__</code></dt> +<dt><code>__UINT8_MAX__</code></dt> +<dt><code>__UINT16_MAX__</code></dt> +<dt><code>__UINT32_MAX__</code></dt> +<dt><code>__UINT64_MAX__</code></dt> +<dt><code>__INT_LEAST8_MAX__</code></dt> +<dt><code>__INT_LEAST16_MAX__</code></dt> +<dt><code>__INT_LEAST32_MAX__</code></dt> +<dt><code>__INT_LEAST64_MAX__</code></dt> +<dt><code>__UINT_LEAST8_MAX__</code></dt> +<dt><code>__UINT_LEAST16_MAX__</code></dt> +<dt><code>__UINT_LEAST32_MAX__</code></dt> +<dt><code>__UINT_LEAST64_MAX__</code></dt> +<dt><code>__INT_FAST8_MAX__</code></dt> +<dt><code>__INT_FAST16_MAX__</code></dt> +<dt><code>__INT_FAST32_MAX__</code></dt> +<dt><code>__INT_FAST64_MAX__</code></dt> +<dt><code>__UINT_FAST8_MAX__</code></dt> +<dt><code>__UINT_FAST16_MAX__</code></dt> +<dt><code>__UINT_FAST32_MAX__</code></dt> +<dt><code>__UINT_FAST64_MAX__</code></dt> +<dt><code>__INTPTR_MAX__</code></dt> +<dt><code>__UINTPTR_MAX__</code></dt> +<dt><code>__WCHAR_MIN__</code></dt> +<dt><code>__WINT_MIN__</code></dt> +<dt><code>__SIG_ATOMIC_MIN__</code></dt> +<dd><p>Defined to the maximum value of the <code>signed char</code>, <code>wchar_t</code>, +<code>signed short</code>, +<code>signed int</code>, <code>signed long</code>, <code>signed long long</code>, +<code>wint_t</code>, <code>size_t</code>, <code>ptrdiff_t</code>, +<code>intmax_t</code>, <code>uintmax_t</code>, <code>sig_atomic_t</code>, <code>int8_t</code>, +<code>int16_t</code>, <code>int32_t</code>, <code>int64_t</code>, <code>uint8_t</code>, +<code>uint16_t</code>, <code>uint32_t</code>, <code>uint64_t</code>, +<code>int_least8_t</code>, <code>int_least16_t</code>, <code>int_least32_t</code>, +<code>int_least64_t</code>, <code>uint_least8_t</code>, <code>uint_least16_t</code>, +<code>uint_least32_t</code>, <code>uint_least64_t</code>, <code>int_fast8_t</code>, +<code>int_fast16_t</code>, <code>int_fast32_t</code>, <code>int_fast64_t</code>, +<code>uint_fast8_t</code>, <code>uint_fast16_t</code>, <code>uint_fast32_t</code>, +<code>uint_fast64_t</code>, <code>intptr_t</code>, and <code>uintptr_t</code> types and +to the minimum value of the <code>wchar_t</code>, <code>wint_t</code>, and +<code>sig_atomic_t</code> types respectively. They exist to make the +standard header given numerical limits work correctly. You should not +use these macros directly; instead, include the appropriate headers. +Some of these macros may not be defined on particular systems if GCC +does not provide a <samp>stdint.h</samp> header on those systems. +</p> +</dd> +<dt><code>__INT8_C</code></dt> +<dt><code>__INT16_C</code></dt> +<dt><code>__INT32_C</code></dt> +<dt><code>__INT64_C</code></dt> +<dt><code>__UINT8_C</code></dt> +<dt><code>__UINT16_C</code></dt> +<dt><code>__UINT32_C</code></dt> +<dt><code>__UINT64_C</code></dt> +<dt><code>__INTMAX_C</code></dt> +<dt><code>__UINTMAX_C</code></dt> +<dd><p>Defined to implementations of the standard <samp>stdint.h</samp> macros with +the same names without the leading <code>__</code>. They exist the make the +implementation of that header work correctly. You should not use +these macros directly; instead, include the appropriate headers. Some +of these macros may not be defined on particular systems if GCC does +not provide a <samp>stdint.h</samp> header on those systems. +</p> +</dd> +<dt><code>__SCHAR_WIDTH__</code></dt> +<dt><code>__SHRT_WIDTH__</code></dt> +<dt><code>__INT_WIDTH__</code></dt> +<dt><code>__LONG_WIDTH__</code></dt> +<dt><code>__LONG_LONG_WIDTH__</code></dt> +<dt><code>__PTRDIFF_WIDTH__</code></dt> +<dt><code>__SIG_ATOMIC_WIDTH__</code></dt> +<dt><code>__SIZE_WIDTH__</code></dt> +<dt><code>__WCHAR_WIDTH__</code></dt> +<dt><code>__WINT_WIDTH__</code></dt> +<dt><code>__INT_LEAST8_WIDTH__</code></dt> +<dt><code>__INT_LEAST16_WIDTH__</code></dt> +<dt><code>__INT_LEAST32_WIDTH__</code></dt> +<dt><code>__INT_LEAST64_WIDTH__</code></dt> +<dt><code>__INT_FAST8_WIDTH__</code></dt> +<dt><code>__INT_FAST16_WIDTH__</code></dt> +<dt><code>__INT_FAST32_WIDTH__</code></dt> +<dt><code>__INT_FAST64_WIDTH__</code></dt> +<dt><code>__INTPTR_WIDTH__</code></dt> +<dt><code>__INTMAX_WIDTH__</code></dt> +<dd><p>Defined to the bit widths of the corresponding types. They exist to +make the implementations of <samp>limits.h</samp> and <samp>stdint.h</samp> behave +correctly. You should not use these macros directly; instead, include +the appropriate headers. Some of these macros may not be defined on +particular systems if GCC does not provide a <samp>stdint.h</samp> header on +those systems. +</p> +</dd> +<dt><code>__SIZEOF_INT__</code></dt> +<dt><code>__SIZEOF_LONG__</code></dt> +<dt><code>__SIZEOF_LONG_LONG__</code></dt> +<dt><code>__SIZEOF_SHORT__</code></dt> +<dt><code>__SIZEOF_POINTER__</code></dt> +<dt><code>__SIZEOF_FLOAT__</code></dt> +<dt><code>__SIZEOF_DOUBLE__</code></dt> +<dt><code>__SIZEOF_LONG_DOUBLE__</code></dt> +<dt><code>__SIZEOF_SIZE_T__</code></dt> +<dt><code>__SIZEOF_WCHAR_T__</code></dt> +<dt><code>__SIZEOF_WINT_T__</code></dt> +<dt><code>__SIZEOF_PTRDIFF_T__</code></dt> +<dd><p>Defined to the number of bytes of the C standard data types: <code>int</code>, +<code>long</code>, <code>long long</code>, <code>short</code>, <code>void *</code>, <code>float</code>, +<code>double</code>, <code>long double</code>, <code>size_t</code>, <code>wchar_t</code>, <code>wint_t</code> +and <code>ptrdiff_t</code>. +</p> +</dd> +<dt><code>__BYTE_ORDER__</code></dt> +<dt><code>__ORDER_LITTLE_ENDIAN__</code></dt> +<dt><code>__ORDER_BIG_ENDIAN__</code></dt> +<dt><code>__ORDER_PDP_ENDIAN__</code></dt> +<dd><p><code>__BYTE_ORDER__</code> is defined to one of the values +<code>__ORDER_LITTLE_ENDIAN__</code>, <code>__ORDER_BIG_ENDIAN__</code>, or +<code>__ORDER_PDP_ENDIAN__</code> to reflect the layout of multi-byte and +multi-word quantities in memory. If <code>__BYTE_ORDER__</code> is equal to +<code>__ORDER_LITTLE_ENDIAN__</code> or <code>__ORDER_BIG_ENDIAN__</code>, then +multi-byte and multi-word quantities are laid out identically: the +byte (word) at the lowest address is the least significant or most +significant byte (word) of the quantity, respectively. If +<code>__BYTE_ORDER__</code> is equal to <code>__ORDER_PDP_ENDIAN__</code>, then +bytes in 16-bit words are laid out in a little-endian fashion, whereas +the 16-bit subwords of a 32-bit quantity are laid out in big-endian +fashion. +</p> +<p>You should use these macros for testing like this: +</p> +<div class="smallexample"> +<pre class="smallexample">/* <span class="roman">Test for a little-endian machine</span> */ +#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__ +</pre></div> + +</dd> +<dt><code>__FLOAT_WORD_ORDER__</code></dt> +<dd><p><code>__FLOAT_WORD_ORDER__</code> is defined to one of the values +<code>__ORDER_LITTLE_ENDIAN__</code> or <code>__ORDER_BIG_ENDIAN__</code> to reflect +the layout of the words of multi-word floating-point quantities. +</p> +</dd> +<dt><code>__DEPRECATED</code></dt> +<dd><p>This macro is defined, with value 1, when compiling a C++ source file +with warnings about deprecated constructs enabled. These warnings are +enabled by default, but can be disabled with <samp>-Wno-deprecated</samp>. +</p> +</dd> +<dt><code>__EXCEPTIONS</code></dt> +<dd><p>This macro is defined, with value 1, when compiling a C++ source file +with exceptions enabled. If <samp>-fno-exceptions</samp> is used when +compiling the file, then this macro is not defined. +</p> +</dd> +<dt><code>__GXX_RTTI</code></dt> +<dd><p>This macro is defined, with value 1, when compiling a C++ source file +with runtime type identification enabled. If <samp>-fno-rtti</samp> is +used when compiling the file, then this macro is not defined. +</p> +</dd> +<dt><code>__USING_SJLJ_EXCEPTIONS__</code></dt> +<dd><p>This macro is defined, with value 1, if the compiler uses the old +mechanism based on <code>setjmp</code> and <code>longjmp</code> for exception +handling. +</p> +</dd> +<dt><code>__GXX_EXPERIMENTAL_CXX0X__</code></dt> +<dd><p>This macro is defined when compiling a C++ source file with C++11 features +enabled, i.e., for all C++ language dialects except <samp>-std=c++98</samp> +and <samp>-std=gnu++98</samp>. This macro is obsolete, but can be used to +detect experimental C++0x features in very old versions of GCC. Since +GCC 4.7.0 the <code>__cplusplus</code> macro is defined correctly, so most +code should test <code>__cplusplus >= 201103L</code> instead of using this +macro. +</p> +</dd> +<dt><code>__GXX_WEAK__</code></dt> +<dd><p>This macro is defined when compiling a C++ source file. It has the +value 1 if the compiler will use weak symbols, COMDAT sections, or +other similar techniques to collapse symbols with “vague linkage” +that are defined in multiple translation units. If the compiler will +not collapse such symbols, this macro is defined with value 0. In +general, user code should not need to make use of this macro; the +purpose of this macro is to ease implementation of the C++ runtime +library provided with G++. +</p> +</dd> +<dt><code>__NEXT_RUNTIME__</code></dt> +<dd><p>This macro is defined, with value 1, if (and only if) the NeXT runtime +(as in <samp>-fnext-runtime</samp>) is in use for Objective-C. If the GNU +runtime is used, this macro is not defined, so that you can use this +macro to determine which runtime (NeXT or GNU) is being used. +</p> +</dd> +<dt><code>__LP64__</code></dt> +<dt><code>_LP64</code></dt> +<dd><p>These macros are defined, with value 1, if (and only if) the compilation +is for a target where <code>long int</code> and pointer both use 64-bits and +<code>int</code> uses 32-bit. +</p> +</dd> +<dt><code>__SSP__</code></dt> +<dd><p>This macro is defined, with value 1, when <samp>-fstack-protector</samp> is in +use. +</p> +</dd> +<dt><code>__SSP_ALL__</code></dt> +<dd><p>This macro is defined, with value 2, when <samp>-fstack-protector-all</samp> is +in use. +</p> +</dd> +<dt><code>__SSP_STRONG__</code></dt> +<dd><p>This macro is defined, with value 3, when <samp>-fstack-protector-strong</samp> is +in use. +</p> +</dd> +<dt><code>__SSP_EXPLICIT__</code></dt> +<dd><p>This macro is defined, with value 4, when <samp>-fstack-protector-explicit</samp> is +in use. +</p> +</dd> +<dt><code>__SANITIZE_ADDRESS__</code></dt> +<dd><p>This macro is defined, with value 1, when <samp>-fsanitize=address</samp> +or <samp>-fsanitize=kernel-address</samp> are in use. +</p> +</dd> +<dt><code>__SANITIZE_THREAD__</code></dt> +<dd><p>This macro is defined, with value 1, when <samp>-fsanitize=thread</samp> is in use. +</p> +</dd> +<dt><code>__TIMESTAMP__</code></dt> +<dd><p>This macro expands to a string constant that describes the date and time +of the last modification of the current source file. The string constant +contains abbreviated day of the week, month, day of the month, time in +hh:mm:ss form, year and looks like <code>"Sun Sep 16 01:03:52 1973"<!-- /@w --></code>. +If the day of the month is less than 10, it is padded with a space on the left. +</p> +<p>If GCC cannot determine the current date, it will emit a warning message +(once per compilation) and <code>__TIMESTAMP__</code> will expand to +<code>"??? ??? ?? ??:??:?? ????"<!-- /@w --></code>. +</p> +</dd> +<dt><code>__GCC_HAVE_SYNC_COMPARE_AND_SWAP_1</code></dt> +<dt><code>__GCC_HAVE_SYNC_COMPARE_AND_SWAP_2</code></dt> +<dt><code>__GCC_HAVE_SYNC_COMPARE_AND_SWAP_4</code></dt> +<dt><code>__GCC_HAVE_SYNC_COMPARE_AND_SWAP_8</code></dt> +<dt><code>__GCC_HAVE_SYNC_COMPARE_AND_SWAP_16</code></dt> +<dd><p>These macros are defined when the target processor supports atomic compare +and swap operations on operands 1, 2, 4, 8 or 16 bytes in length, respectively. +</p> +</dd> +<dt><code>__HAVE_SPECULATION_SAFE_VALUE</code></dt> +<dd><p>This macro is defined with the value 1 to show that this version of GCC +supports <code>__builtin_speculation_safe_value</code>. +</p> +</dd> +<dt><code>__GCC_HAVE_DWARF2_CFI_ASM</code></dt> +<dd><p>This macro is defined when the compiler is emitting DWARF CFI directives +to the assembler. When this is defined, it is possible to emit those same +directives in inline assembly. +</p> +</dd> +<dt><code>__FP_FAST_FMA</code></dt> +<dt><code>__FP_FAST_FMAF</code></dt> +<dt><code>__FP_FAST_FMAL</code></dt> +<dd><p>These macros are defined with value 1 if the backend supports the +<code>fma</code>, <code>fmaf</code>, and <code>fmal</code> builtin functions, so that +the include file <samp>math.h</samp> can define the macros +<code>FP_FAST_FMA</code>, <code>FP_FAST_FMAF</code>, and <code>FP_FAST_FMAL</code> +for compatibility with the 1999 C standard. +</p> +</dd> +<dt><code>__FP_FAST_FMAF16</code></dt> +<dt><code>__FP_FAST_FMAF32</code></dt> +<dt><code>__FP_FAST_FMAF64</code></dt> +<dt><code>__FP_FAST_FMAF128</code></dt> +<dt><code>__FP_FAST_FMAF32X</code></dt> +<dt><code>__FP_FAST_FMAF64X</code></dt> +<dt><code>__FP_FAST_FMAF128X</code></dt> +<dd><p>These macros are defined with the value 1 if the backend supports the +<code>fma</code> functions using the additional <code>_Float<var>n</var></code> and +<code>_Float<var>n</var>x</code> types that are defined in ISO/IEC TS +18661-3:2015. The include file <samp>math.h</samp> can define the +<code>FP_FAST_FMAF<var>n</var></code> and <code>FP_FAST_FMAF<var>n</var>x</code> macros if +the user defined <code>__STDC_WANT_IEC_60559_TYPES_EXT__</code> before +including <samp>math.h</samp>. +</p> +</dd> +<dt><code>__GCC_IEC_559</code></dt> +<dd><p>This macro is defined to indicate the intended level of support for +IEEE 754 (IEC 60559) floating-point arithmetic. It expands to a +nonnegative integer value. If 0, it indicates that the combination of +the compiler configuration and the command-line options is not +intended to support IEEE 754 arithmetic for <code>float</code> and +<code>double</code> as defined in C99 and C11 Annex F (for example, that the +standard rounding modes and exceptions are not supported, or that +optimizations are enabled that conflict with IEEE 754 semantics). If +1, it indicates that IEEE 754 arithmetic is intended to be supported; +this does not mean that all relevant language features are supported +by GCC. If 2 or more, it additionally indicates support for IEEE +754-2008 (in particular, that the binary encodings for quiet and +signaling NaNs are as specified in IEEE 754-2008). +</p> +<p>This macro does not indicate the default state of command-line options +that control optimizations that C99 and C11 permit to be controlled by +standard pragmas, where those standards do not require a particular +default state. It does not indicate whether optimizations respect +signaling NaN semantics (the macro for that is +<code>__SUPPORT_SNAN__</code>). It does not indicate support for decimal +floating point or the IEEE 754 binary16 and binary128 types. +</p> +</dd> +<dt><code>__GCC_IEC_559_COMPLEX</code></dt> +<dd><p>This macro is defined to indicate the intended level of support for +IEEE 754 (IEC 60559) floating-point arithmetic for complex numbers, as +defined in C99 and C11 Annex G. It expands to a nonnegative integer +value. If 0, it indicates that the combination of the compiler +configuration and the command-line options is not intended to support +Annex G requirements (for example, because <samp>-fcx-limited-range</samp> +was used). If 1 or more, it indicates that it is intended to support +those requirements; this does not mean that all relevant language +features are supported by GCC. +</p> +</dd> +<dt><code>__NO_MATH_ERRNO__</code></dt> +<dd><p>This macro is defined if <samp>-fno-math-errno</samp> is used, or enabled +by another option such as <samp>-ffast-math</samp> or by default. +</p> +</dd> +<dt><code>__RECIPROCAL_MATH__</code></dt> +<dd><p>This macro is defined if <samp>-freciprocal-math</samp> is used, or enabled +by another option such as <samp>-ffast-math</samp> or by default. +</p> +</dd> +<dt><code>__NO_SIGNED_ZEROS__</code></dt> +<dd><p>This macro is defined if <samp>-fno-signed-zeros</samp> is used, or enabled +by another option such as <samp>-ffast-math</samp> or by default. +</p> +</dd> +<dt><code>__NO_TRAPPING_MATH__</code></dt> +<dd><p>This macro is defined if <samp>-fno-trapping-math</samp> is used. +</p> +</dd> +<dt><code>__ASSOCIATIVE_MATH__</code></dt> +<dd><p>This macro is defined if <samp>-fassociative-math</samp> is used, or enabled +by another option such as <samp>-ffast-math</samp> or by default. +</p> +</dd> +<dt><code>__ROUNDING_MATH__</code></dt> +<dd><p>This macro is defined if <samp>-frounding-math</samp> is used. +</p> +</dd> +<dt><code>__GNUC_EXECUTION_CHARSET_NAME</code></dt> +<dt><code>__GNUC_WIDE_EXECUTION_CHARSET_NAME</code></dt> +<dd><p>These macros are defined to expand to a narrow string literal of +the name of the narrow and wide compile-time execution character +set used. It directly reflects the name passed to the options +<samp>-fexec-charset</samp> and <samp>-fwide-exec-charset</samp>, or the defaults +documented for those options (that is, it can expand to something like +<code>"UTF-8"</code>). See <a href="Invocation.html#Invocation">Invocation</a>. +</p></dd> +</dl> + +<hr> +<div class="header"> +<p> +Next: <a href="System_002dspecific-Predefined-Macros.html#System_002dspecific-Predefined-Macros" accesskey="n" rel="next">System-specific Predefined Macros</a>, Previous: <a href="Standard-Predefined-Macros.html#Standard-Predefined-Macros" accesskey="p" rel="previous">Standard Predefined Macros</a>, Up: <a href="Predefined-Macros.html#Predefined-Macros" accesskey="u" rel="up">Predefined Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Computed-Includes.html b/share/doc/cpp/Computed-Includes.html new file mode 100644 index 0000000..970169d --- /dev/null +++ b/share/doc/cpp/Computed-Includes.html @@ -0,0 +1,167 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Computed Includes</title> + +<meta name="description" content="The C Preprocessor: Computed Includes"> +<meta name="keywords" content="The C Preprocessor: Computed Includes"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Header-Files.html#Header-Files" rel="up" title="Header Files"> +<link href="Wrapper-Headers.html#Wrapper-Headers" rel="next" title="Wrapper Headers"> +<link href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef" rel="previous" title="Alternatives to Wrapper #ifndef"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Computed-Includes"></a> +<div class="header"> +<p> +Next: <a href="Wrapper-Headers.html#Wrapper-Headers" accesskey="n" rel="next">Wrapper Headers</a>, Previous: <a href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef" accesskey="p" rel="previous">Alternatives to Wrapper #ifndef</a>, Up: <a href="Header-Files.html#Header-Files" accesskey="u" rel="up">Header Files</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Computed-Includes-1"></a> +<h3 class="section">2.6 Computed Includes</h3> +<a name="index-computed-includes"></a> +<a name="index-macros-in-include"></a> + +<p>Sometimes it is necessary to select one of several different header +files to be included into your program. They might specify +configuration parameters to be used on different sorts of operating +systems, for instance. You could do this with a series of conditionals, +</p> +<div class="smallexample"> +<pre class="smallexample">#if SYSTEM_1 +# include "system_1.h" +#elif SYSTEM_2 +# include "system_2.h" +#elif SYSTEM_3 +… +#endif +</pre></div> + +<p>That rapidly becomes tedious. Instead, the preprocessor offers the +ability to use a macro for the header name. This is called a +<em>computed include</em>. Instead of writing a header name as the direct +argument of ‘<samp>#include</samp>’, you simply put a macro name there instead: +</p> +<div class="smallexample"> +<pre class="smallexample">#define SYSTEM_H "system_1.h" +… +#include SYSTEM_H +</pre></div> + +<p><code>SYSTEM_H</code> will be expanded, and the preprocessor will look for +<samp>system_1.h</samp> as if the ‘<samp>#include</samp>’ had been written that way +originally. <code>SYSTEM_H</code> could be defined by your Makefile with a +<samp>-D</samp> option. +</p> +<p>You must be careful when you define the macro. ‘<samp>#define</samp>’ saves +tokens, not text. The preprocessor has no way of knowing that the macro +will be used as the argument of ‘<samp>#include</samp>’, so it generates +ordinary tokens, not a header name. This is unlikely to cause problems +if you use double-quote includes, which are close enough to string +constants. If you use angle brackets, however, you may have trouble. +</p> +<p>The syntax of a computed include is actually a bit more general than the +above. If the first non-whitespace character after ‘<samp>#include</samp>’ is +not ‘<samp>"</samp>’ or ‘<samp><</samp>’, then the entire line is macro-expanded +like running text would be. +</p> +<p>If the line expands to a single string constant, the contents of that +string constant are the file to be included. CPP does not re-examine the +string for embedded quotes, but neither does it process backslash +escapes in the string. Therefore +</p> +<div class="smallexample"> +<pre class="smallexample">#define HEADER "a\"b" +#include HEADER +</pre></div> + +<p>looks for a file named <samp>a\"b</samp>. CPP searches for the file according +to the rules for double-quoted includes. +</p> +<p>If the line expands to a token stream beginning with a ‘<samp><</samp>’ token +and including a ‘<samp>></samp>’ token, then the tokens between the ‘<samp><</samp>’ and +the first ‘<samp>></samp>’ are combined to form the filename to be included. +Any whitespace between tokens is reduced to a single space; then any +space after the initial ‘<samp><</samp>’ is retained, but a trailing space +before the closing ‘<samp>></samp>’ is ignored. CPP searches for the file +according to the rules for angle-bracket includes. +</p> +<p>In either case, if there are any tokens on the line after the file name, +an error occurs and the directive is not processed. It is also an error +if the result of expansion does not match either of the two expected +forms. +</p> +<p>These rules are implementation-defined behavior according to the C +standard. To minimize the risk of different compilers interpreting your +computed includes differently, we recommend you use only a single +object-like macro which expands to a string constant. This will also +minimize confusion for people reading your program. +</p> +<hr> +<div class="header"> +<p> +Next: <a href="Wrapper-Headers.html#Wrapper-Headers" accesskey="n" rel="next">Wrapper Headers</a>, Previous: <a href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef" accesskey="p" rel="previous">Alternatives to Wrapper #ifndef</a>, Up: <a href="Header-Files.html#Header-Files" accesskey="u" rel="up">Header Files</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Concatenation.html b/share/doc/cpp/Concatenation.html new file mode 100644 index 0000000..625aff7 --- /dev/null +++ b/share/doc/cpp/Concatenation.html @@ -0,0 +1,168 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Concatenation</title> + +<meta name="description" content="The C Preprocessor: Concatenation"> +<meta name="keywords" content="The C Preprocessor: Concatenation"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Macros.html#Macros" rel="up" title="Macros"> +<link href="Variadic-Macros.html#Variadic-Macros" rel="next" title="Variadic Macros"> +<link href="Stringizing.html#Stringizing" rel="previous" title="Stringizing"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Concatenation"></a> +<div class="header"> +<p> +Next: <a href="Variadic-Macros.html#Variadic-Macros" accesskey="n" rel="next">Variadic Macros</a>, Previous: <a href="Stringizing.html#Stringizing" accesskey="p" rel="previous">Stringizing</a>, Up: <a href="Macros.html#Macros" accesskey="u" rel="up">Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Concatenation-1"></a> +<h3 class="section">3.5 Concatenation</h3> +<a name="index-concatenation"></a> +<a name="index-token-pasting"></a> +<a name="index-token-concatenation"></a> +<a name="index-_0023_0023-operator"></a> + +<p>It is often useful to merge two tokens into one while expanding macros. +This is called <em>token pasting</em> or <em>token concatenation</em>. The +‘<samp>##</samp>’ preprocessing operator performs token pasting. When a macro +is expanded, the two tokens on either side of each ‘<samp>##</samp>’ operator +are combined into a single token, which then replaces the ‘<samp>##</samp>’ and +the two original tokens in the macro expansion. Usually both will be +identifiers, or one will be an identifier and the other a preprocessing +number. When pasted, they make a longer identifier. This isn’t the +only valid case. It is also possible to concatenate two numbers (or a +number and a name, such as <code>1.5</code> and <code>e3</code>) into a number. +Also, multi-character operators such as <code>+=</code> can be formed by +token pasting. +</p> +<p>However, two tokens that don’t together form a valid token cannot be +pasted together. For example, you cannot concatenate <code>x</code> with +<code>+</code> in either order. If you try, the preprocessor issues a warning +and emits the two tokens. Whether it puts white space between the +tokens is undefined. It is common to find unnecessary uses of ‘<samp>##</samp>’ +in complex macros. If you get this warning, it is likely that you can +simply remove the ‘<samp>##</samp>’. +</p> +<p>Both the tokens combined by ‘<samp>##</samp>’ could come from the macro body, +but you could just as well write them as one token in the first place. +Token pasting is most useful when one or both of the tokens comes from a +macro argument. If either of the tokens next to an ‘<samp>##</samp>’ is a +parameter name, it is replaced by its actual argument before ‘<samp>##</samp>’ +executes. As with stringizing, the actual argument is not +macro-expanded first. If the argument is empty, that ‘<samp>##</samp>’ has no +effect. +</p> +<p>Keep in mind that the C preprocessor converts comments to whitespace +before macros are even considered. Therefore, you cannot create a +comment by concatenating ‘<samp>/</samp>’ and ‘<samp>*</samp>’. You can put as much +whitespace between ‘<samp>##</samp>’ and its operands as you like, including +comments, and you can put comments in arguments that will be +concatenated. However, it is an error if ‘<samp>##</samp>’ appears at either +end of a macro body. +</p> +<p>Consider a C program that interprets named commands. There probably +needs to be a table of commands, perhaps an array of structures declared +as follows: +</p> +<div class="smallexample"> +<pre class="smallexample">struct command +{ + char *name; + void (*function) (void); +}; +</pre><pre class="smallexample"> +</pre><pre class="smallexample">struct command commands[] = +{ + { "quit", quit_command }, + { "help", help_command }, + … +}; +</pre></div> + +<p>It would be cleaner not to have to give each command name twice, once in +the string constant and once in the function name. A macro which takes the +name of a command as an argument can make this unnecessary. The string +constant can be created with stringizing, and the function name by +concatenating the argument with ‘<samp>_command</samp>’. Here is how it is done: +</p> +<div class="smallexample"> +<pre class="smallexample">#define COMMAND(NAME) { #NAME, NAME ## _command } + +struct command commands[] = +{ + COMMAND (quit), + COMMAND (help), + … +}; +</pre></div> + +<hr> +<div class="header"> +<p> +Next: <a href="Variadic-Macros.html#Variadic-Macros" accesskey="n" rel="next">Variadic Macros</a>, Previous: <a href="Stringizing.html#Stringizing" accesskey="p" rel="previous">Stringizing</a>, Up: <a href="Macros.html#Macros" accesskey="u" rel="up">Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Concept-Index.html b/share/doc/cpp/Concept-Index.html new file mode 100644 index 0000000..e8a9c93 --- /dev/null +++ b/share/doc/cpp/Concept-Index.html @@ -0,0 +1,345 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Concept Index</title> + +<meta name="description" content="The C Preprocessor: Concept Index"> +<meta name="keywords" content="The C Preprocessor: Concept Index"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html#Top" rel="up" title="Top"> +<link href="Option-Index.html#Option-Index" rel="previous" title="Option Index"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Concept-Index"></a> +<div class="header"> +<p> +Previous: <a href="Option-Index.html#Option-Index" accesskey="p" rel="previous">Option Index</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Concept-Index-1"></a> +<h2 class="unnumbered">Concept Index</h2> +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Concept-Index_cp_symbol-1"><b>#</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_symbol-2"><b>_</b></a> + +<br> +<a class="summary-letter" href="#Concept-Index_cp_letter-A"><b>A</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-B"><b>B</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-C"><b>C</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-D"><b>D</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-E"><b>E</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-F"><b>F</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-G"><b>G</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-H"><b>H</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-I"><b>I</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-L"><b>L</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-M"><b>M</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-N"><b>N</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-O"><b>O</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-P"><b>P</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-R"><b>R</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-S"><b>S</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-T"><b>T</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-U"><b>U</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-V"><b>V</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-W"><b>W</b></a> + +</td></tr></table> +<table class="index-cp" border="0"> +<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_symbol-1">#</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Stringizing.html#index-_0023-operator">‘<samp>#</samp>’ operator</a>:</td><td> </td><td valign="top"><a href="Stringizing.html#Stringizing">Stringizing</a></td></tr> +<tr><td></td><td valign="top"><a href="Concatenation.html#index-_0023_0023-operator">‘<samp>##</samp>’ operator</a>:</td><td> </td><td valign="top"><a href="Concatenation.html#Concatenation">Concatenation</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_symbol-2">_</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Pragmas.html#index-_005fPragma"><code>_Pragma</code></a>:</td><td> </td><td valign="top"><a href="Pragmas.html#Pragmas">Pragmas</a></td></tr> +<tr><td></td><td valign="top"><a href="_005f_005fhas_005fattribute.html#index-_005f_005fhas_005fattribute"><code>__has_attribute</code></a>:</td><td> </td><td valign="top"><a href="_005f_005fhas_005fattribute.html#g_t_005f_005fhas_005fattribute"><code>__has_attribute</code></a></td></tr> +<tr><td></td><td valign="top"><a href="_005f_005fhas_005fbuiltin.html#index-_005f_005fhas_005fbuiltin"><code>__has_builtin</code></a>:</td><td> </td><td valign="top"><a href="_005f_005fhas_005fbuiltin.html#g_t_005f_005fhas_005fbuiltin"><code>__has_builtin</code></a></td></tr> +<tr><td></td><td valign="top"><a href="_005f_005fhas_005fcpp_005fattribute.html#index-_005f_005fhas_005fcpp_005fattribute"><code>__has_cpp_attribute</code></a>:</td><td> </td><td valign="top"><a href="_005f_005fhas_005fcpp_005fattribute.html#g_t_005f_005fhas_005fcpp_005fattribute"><code>__has_cpp_attribute</code></a></td></tr> +<tr><td></td><td valign="top"><a href="_005f_005fhas_005fc_005fattribute.html#index-_005f_005fhas_005fc_005fattribute"><code>__has_c_attribute</code></a>:</td><td> </td><td valign="top"><a href="_005f_005fhas_005fc_005fattribute.html#g_t_005f_005fhas_005fc_005fattribute"><code>__has_c_attribute</code></a></td></tr> +<tr><td></td><td valign="top"><a href="_005f_005fhas_005finclude.html#index-_005f_005fhas_005finclude"><code>__has_include</code></a>:</td><td> </td><td valign="top"><a href="_005f_005fhas_005finclude.html#g_t_005f_005fhas_005finclude"><code>__has_include</code></a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-A">A</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Tokenization.html#index-alternative-tokens">alternative tokens</a>:</td><td> </td><td valign="top"><a href="Tokenization.html#Tokenization">Tokenization</a></td></tr> +<tr><td></td><td valign="top"><a href="Macro-Arguments.html#index-arguments">arguments</a>:</td><td> </td><td valign="top"><a href="Macro-Arguments.html#Macro-Arguments">Macro Arguments</a></td></tr> +<tr><td></td><td valign="top"><a href="Macro-Arguments.html#index-arguments-in-macro-definitions">arguments in macro definitions</a>:</td><td> </td><td valign="top"><a href="Macro-Arguments.html#Macro-Arguments">Macro Arguments</a></td></tr> +<tr><td></td><td valign="top"><a href="Obsolete-Features.html#index-assertions">assertions</a>:</td><td> </td><td valign="top"><a href="Obsolete-Features.html#Obsolete-Features">Obsolete Features</a></td></tr> +<tr><td></td><td valign="top"><a href="Obsolete-Features.html#index-assertions_002c-canceling">assertions, canceling</a>:</td><td> </td><td valign="top"><a href="Obsolete-Features.html#Obsolete-Features">Obsolete Features</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-B">B</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Initial-processing.html#index-backslash_002dnewline">backslash-newline</a>:</td><td> </td><td valign="top"><a href="Initial-processing.html#Initial-processing">Initial processing</a></td></tr> +<tr><td></td><td valign="top"><a href="Initial-processing.html#index-block-comments">block comments</a>:</td><td> </td><td valign="top"><a href="Initial-processing.html#Initial-processing">Initial processing</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-C">C</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-C-language_002c-traditional">C language, traditional</a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="C_002b_002b-Named-Operators.html#index-C_002b_002b-named-operators">C++ named operators</a>:</td><td> </td><td valign="top"><a href="C_002b_002b-Named-Operators.html#C_002b_002b-Named-Operators">C++ Named Operators</a></td></tr> +<tr><td></td><td valign="top"><a href="Tokenization.html#index-character-constants">character constants</a>:</td><td> </td><td valign="top"><a href="Tokenization.html#Tokenization">Tokenization</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-character-set_002c-execution">character set, execution</a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-character-set_002c-input">character set, input</a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-character-set_002c-wide-execution">character set, wide execution</a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-command-line">command line</a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Deleted-Code.html#index-commenting-out-code">commenting out code</a>:</td><td> </td><td valign="top"><a href="Deleted-Code.html#Deleted-Code">Deleted Code</a></td></tr> +<tr><td></td><td valign="top"><a href="Initial-processing.html#index-comments">comments</a>:</td><td> </td><td valign="top"><a href="Initial-processing.html#Initial-processing">Initial processing</a></td></tr> +<tr><td></td><td valign="top"><a href="Common-Predefined-Macros.html#index-common-predefined-macros">common predefined macros</a>:</td><td> </td><td valign="top"><a href="Common-Predefined-Macros.html#Common-Predefined-Macros">Common Predefined Macros</a></td></tr> +<tr><td></td><td valign="top"><a href="Computed-Includes.html#index-computed-includes">computed includes</a>:</td><td> </td><td valign="top"><a href="Computed-Includes.html#Computed-Includes">Computed Includes</a></td></tr> +<tr><td></td><td valign="top"><a href="Concatenation.html#index-concatenation">concatenation</a>:</td><td> </td><td valign="top"><a href="Concatenation.html#Concatenation">Concatenation</a></td></tr> +<tr><td></td><td valign="top"><a href="Ifdef.html#index-conditional-group">conditional group</a>:</td><td> </td><td valign="top"><a href="Ifdef.html#Ifdef">Ifdef</a></td></tr> +<tr><td></td><td valign="top"><a href="Conditionals.html#index-conditionals">conditionals</a>:</td><td> </td><td valign="top"><a href="Conditionals.html#Conditionals">Conditionals</a></td></tr> +<tr><td></td><td valign="top"><a href="Initial-processing.html#index-continued-lines">continued lines</a>:</td><td> </td><td valign="top"><a href="Initial-processing.html#Initial-processing">Initial processing</a></td></tr> +<tr><td></td><td valign="top"><a href="Once_002dOnly-Headers.html#index-controlling-macro">controlling macro</a>:</td><td> </td><td valign="top"><a href="Once_002dOnly-Headers.html#Once_002dOnly-Headers">Once-Only Headers</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-D">D</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Defined.html#index-defined"><code>defined</code></a>:</td><td> </td><td valign="top"><a href="Defined.html#Defined">Defined</a></td></tr> +<tr><td></td><td valign="top"><a href="Environment-Variables.html#index-dependencies-for-make-as-output">dependencies for make as output</a>:</td><td> </td><td valign="top"><a href="Environment-Variables.html#Environment-Variables">Environment Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="Environment-Variables.html#index-dependencies-for-make-as-output-1">dependencies for make as output</a>:</td><td> </td><td valign="top"><a href="Environment-Variables.html#Environment-Variables">Environment Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-dependencies_002c-make">dependencies, <code>make</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Diagnostics.html#index-diagnostic">diagnostic</a>:</td><td> </td><td valign="top"><a href="Diagnostics.html#Diagnostics">Diagnostics</a></td></tr> +<tr><td></td><td valign="top"><a href="Tokenization.html#index-digraphs">digraphs</a>:</td><td> </td><td valign="top"><a href="Tokenization.html#Tokenization">Tokenization</a></td></tr> +<tr><td></td><td valign="top"><a href="The-preprocessing-language.html#index-directive-line">directive line</a>:</td><td> </td><td valign="top"><a href="The-preprocessing-language.html#The-preprocessing-language">The preprocessing language</a></td></tr> +<tr><td></td><td valign="top"><a href="The-preprocessing-language.html#index-directive-name">directive name</a>:</td><td> </td><td valign="top"><a href="The-preprocessing-language.html#The-preprocessing-language">The preprocessing language</a></td></tr> +<tr><td></td><td valign="top"><a href="The-preprocessing-language.html#index-directives">directives</a>:</td><td> </td><td valign="top"><a href="The-preprocessing-language.html#The-preprocessing-language">The preprocessing language</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-E">E</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Macro-Arguments.html#index-empty-macro-arguments">empty macro arguments</a>:</td><td> </td><td valign="top"><a href="Macro-Arguments.html#Macro-Arguments">Macro Arguments</a></td></tr> +<tr><td></td><td valign="top"><a href="Environment-Variables.html#index-environment-variables">environment variables</a>:</td><td> </td><td valign="top"><a href="Environment-Variables.html#Environment-Variables">Environment Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="Argument-Prescan.html#index-expansion-of-arguments">expansion of arguments</a>:</td><td> </td><td valign="top"><a href="Argument-Prescan.html#Argument-Prescan">Argument Prescan</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-F">F</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="GNU-Free-Documentation-License.html#index-FDL_002c-GNU-Free-Documentation-License">FDL, GNU Free Documentation License</a>:</td><td> </td><td valign="top"><a href="GNU-Free-Documentation-License.html#GNU-Free-Documentation-License">GNU Free Documentation License</a></td></tr> +<tr><td></td><td valign="top"><a href="Function_002dlike-Macros.html#index-function_002dlike-macros">function-like macros</a>:</td><td> </td><td valign="top"><a href="Function_002dlike-Macros.html#Function_002dlike-Macros">Function-like Macros</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-G">G</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-grouping-options">grouping options</a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Once_002dOnly-Headers.html#index-guard-macro">guard macro</a>:</td><td> </td><td valign="top"><a href="Once_002dOnly-Headers.html#Once_002dOnly-Headers">Once-Only Headers</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-H">H</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Header-Files.html#index-header-file">header file</a>:</td><td> </td><td valign="top"><a href="Header-Files.html#Header-Files">Header Files</a></td></tr> +<tr><td></td><td valign="top"><a href="Tokenization.html#index-header-file-names">header file names</a>:</td><td> </td><td valign="top"><a href="Tokenization.html#Tokenization">Tokenization</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-I">I</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Tokenization.html#index-identifiers">identifiers</a>:</td><td> </td><td valign="top"><a href="Tokenization.html#Tokenization">Tokenization</a></td></tr> +<tr><td></td><td valign="top"><a href="Implementation-limits.html#index-implementation-limits">implementation limits</a>:</td><td> </td><td valign="top"><a href="Implementation-limits.html#Implementation-limits">Implementation limits</a></td></tr> +<tr><td></td><td valign="top"><a href="Implementation_002ddefined-behavior.html#index-implementation_002ddefined-behavior">implementation-defined behavior</a>:</td><td> </td><td valign="top"><a href="Implementation_002ddefined-behavior.html#Implementation_002ddefined-behavior">Implementation-defined behavior</a></td></tr> +<tr><td></td><td valign="top"><a href="Once_002dOnly-Headers.html#index-including-just-once">including just once</a>:</td><td> </td><td valign="top"><a href="Once_002dOnly-Headers.html#Once_002dOnly-Headers">Once-Only Headers</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-invocation">invocation</a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="C_002b_002b-Named-Operators.html#index-iso646_002eh"><samp>iso646.h</samp></a>:</td><td> </td><td valign="top"><a href="C_002b_002b-Named-Operators.html#C_002b_002b-Named-Operators">C++ Named Operators</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-L">L</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Initial-processing.html#index-line-comments">line comments</a>:</td><td> </td><td valign="top"><a href="Initial-processing.html#Initial-processing">Initial processing</a></td></tr> +<tr><td></td><td valign="top"><a href="Line-Control.html#index-line-control">line control</a>:</td><td> </td><td valign="top"><a href="Line-Control.html#Line-Control">Line Control</a></td></tr> +<tr><td></td><td valign="top"><a href="Initial-processing.html#index-line-endings">line endings</a>:</td><td> </td><td valign="top"><a href="Initial-processing.html#Initial-processing">Initial processing</a></td></tr> +<tr><td></td><td valign="top"><a href="Preprocessor-Output.html#index-linemarkers">linemarkers</a>:</td><td> </td><td valign="top"><a href="Preprocessor-Output.html#Preprocessor-Output">Preprocessor Output</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-M">M</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Argument-Prescan.html#index-macro-argument-expansion">macro argument expansion</a>:</td><td> </td><td valign="top"><a href="Argument-Prescan.html#Argument-Prescan">Argument Prescan</a></td></tr> +<tr><td></td><td valign="top"><a href="Directives-Within-Macro-Arguments.html#index-macro-arguments-and-directives">macro arguments and directives</a>:</td><td> </td><td valign="top"><a href="Directives-Within-Macro-Arguments.html#Directives-Within-Macro-Arguments">Directives Within Macro Arguments</a></td></tr> +<tr><td></td><td valign="top"><a href="Computed-Includes.html#index-macros-in-include">macros in include</a>:</td><td> </td><td valign="top"><a href="Computed-Includes.html#Computed-Includes">Computed Includes</a></td></tr> +<tr><td></td><td valign="top"><a href="Macro-Arguments.html#index-macros-with-arguments">macros with arguments</a>:</td><td> </td><td valign="top"><a href="Macro-Arguments.html#Macro-Arguments">Macro Arguments</a></td></tr> +<tr><td></td><td valign="top"><a href="Variadic-Macros.html#index-macros-with-variable-arguments">macros with variable arguments</a>:</td><td> </td><td valign="top"><a href="Variadic-Macros.html#Variadic-Macros">Variadic Macros</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-make"><code>make</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Object_002dlike-Macros.html#index-manifest-constants">manifest constants</a>:</td><td> </td><td valign="top"><a href="Object_002dlike-Macros.html#Object_002dlike-Macros">Object-like Macros</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-N">N</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="C_002b_002b-Named-Operators.html#index-named-operators">named operators</a>:</td><td> </td><td valign="top"><a href="C_002b_002b-Named-Operators.html#C_002b_002b-Named-Operators">C++ Named Operators</a></td></tr> +<tr><td></td><td valign="top"><a href="Newlines-in-Arguments.html#index-newlines-in-macro-arguments">newlines in macro arguments</a>:</td><td> </td><td valign="top"><a href="Newlines-in-Arguments.html#Newlines-in-Arguments">Newlines in Arguments</a></td></tr> +<tr><td></td><td valign="top"><a href="Other-Directives.html#index-null-directive">null directive</a>:</td><td> </td><td valign="top"><a href="Other-Directives.html#Other-Directives">Other Directives</a></td></tr> +<tr><td></td><td valign="top"><a href="Tokenization.html#index-numbers">numbers</a>:</td><td> </td><td valign="top"><a href="Tokenization.html#Tokenization">Tokenization</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-O">O</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Object_002dlike-Macros.html#index-object_002dlike-macro">object-like macro</a>:</td><td> </td><td valign="top"><a href="Object_002dlike-Macros.html#Object_002dlike-Macros">Object-like Macros</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-options">options</a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-options_002c-grouping">options, grouping</a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Tokenization.html#index-other-tokens">other tokens</a>:</td><td> </td><td valign="top"><a href="Tokenization.html#Tokenization">Tokenization</a></td></tr> +<tr><td></td><td valign="top"><a href="Preprocessor-Output.html#index-output-format">output format</a>:</td><td> </td><td valign="top"><a href="Preprocessor-Output.html#Preprocessor-Output">Preprocessor Output</a></td></tr> +<tr><td></td><td valign="top"><a href="Wrapper-Headers.html#index-overriding-a-header-file">overriding a header file</a>:</td><td> </td><td valign="top"><a href="Wrapper-Headers.html#Wrapper-Headers">Wrapper Headers</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-P">P</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Operator-Precedence-Problems.html#index-parentheses-in-macro-bodies">parentheses in macro bodies</a>:</td><td> </td><td valign="top"><a href="Operator-Precedence-Problems.html#Operator-Precedence-Problems">Operator Precedence Problems</a></td></tr> +<tr><td></td><td valign="top"><a href="Macro-Pitfalls.html#index-pitfalls-of-macros">pitfalls of macros</a>:</td><td> </td><td valign="top"><a href="Macro-Pitfalls.html#Macro-Pitfalls">Macro Pitfalls</a></td></tr> +<tr><td></td><td valign="top"><a href="Pragmas.html#index-pragma-directive">pragma directive</a>:</td><td> </td><td valign="top"><a href="Pragmas.html#Pragmas">Pragmas</a></td></tr> +<tr><td></td><td valign="top"><a href="Predefined-Macros.html#index-predefined-macros">predefined macros</a>:</td><td> </td><td valign="top"><a href="Predefined-Macros.html#Predefined-Macros">Predefined Macros</a></td></tr> +<tr><td></td><td valign="top"><a href="System_002dspecific-Predefined-Macros.html#index-predefined-macros_002c-system_002dspecific">predefined macros, system-specific</a>:</td><td> </td><td valign="top"><a href="System_002dspecific-Predefined-Macros.html#System_002dspecific-Predefined-Macros">System-specific Predefined Macros</a></td></tr> +<tr><td></td><td valign="top"><a href="Obsolete-Features.html#index-predicates">predicates</a>:</td><td> </td><td valign="top"><a href="Obsolete-Features.html#Obsolete-Features">Obsolete Features</a></td></tr> +<tr><td></td><td valign="top"><a href="The-preprocessing-language.html#index-preprocessing-directives">preprocessing directives</a>:</td><td> </td><td valign="top"><a href="The-preprocessing-language.html#The-preprocessing-language">The preprocessing language</a></td></tr> +<tr><td></td><td valign="top"><a href="Tokenization.html#index-preprocessing-numbers">preprocessing numbers</a>:</td><td> </td><td valign="top"><a href="Tokenization.html#Tokenization">Tokenization</a></td></tr> +<tr><td></td><td valign="top"><a href="Tokenization.html#index-preprocessing-tokens">preprocessing tokens</a>:</td><td> </td><td valign="top"><a href="Tokenization.html#Tokenization">Tokenization</a></td></tr> +<tr><td></td><td valign="top"><a href="Argument-Prescan.html#index-prescan-of-macro-arguments">prescan of macro arguments</a>:</td><td> </td><td valign="top"><a href="Argument-Prescan.html#Argument-Prescan">Argument Prescan</a></td></tr> +<tr><td></td><td valign="top"><a href="Macro-Pitfalls.html#index-problems-with-macros">problems with macros</a>:</td><td> </td><td valign="top"><a href="Macro-Pitfalls.html#Macro-Pitfalls">Macro Pitfalls</a></td></tr> +<tr><td></td><td valign="top"><a href="Tokenization.html#index-punctuators">punctuators</a>:</td><td> </td><td valign="top"><a href="Tokenization.html#Tokenization">Tokenization</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-R">R</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Undefining-and-Redefining-Macros.html#index-redefining-macros">redefining macros</a>:</td><td> </td><td valign="top"><a href="Undefining-and-Redefining-Macros.html#Undefining-and-Redefining-Macros">Undefining and Redefining Macros</a></td></tr> +<tr><td></td><td valign="top"><a href="Once_002dOnly-Headers.html#index-repeated-inclusion">repeated inclusion</a>:</td><td> </td><td valign="top"><a href="Once_002dOnly-Headers.html#Once_002dOnly-Headers">Once-Only Headers</a></td></tr> +<tr><td></td><td valign="top"><a href="Diagnostics.html#index-reporting-errors">reporting errors</a>:</td><td> </td><td valign="top"><a href="Diagnostics.html#Diagnostics">Diagnostics</a></td></tr> +<tr><td></td><td valign="top"><a href="Diagnostics.html#index-reporting-warnings">reporting warnings</a>:</td><td> </td><td valign="top"><a href="Diagnostics.html#Diagnostics">Diagnostics</a></td></tr> +<tr><td></td><td valign="top"><a href="System_002dspecific-Predefined-Macros.html#index-reserved-namespace">reserved namespace</a>:</td><td> </td><td valign="top"><a href="System_002dspecific-Predefined-Macros.html#System_002dspecific-Predefined-Macros">System-specific Predefined Macros</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-S">S</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Self_002dReferential-Macros.html#index-self_002dreference">self-reference</a>:</td><td> </td><td valign="top"><a href="Self_002dReferential-Macros.html#Self_002dReferential-Macros">Self-Referential Macros</a></td></tr> +<tr><td></td><td valign="top"><a href="Swallowing-the-Semicolon.html#index-semicolons-_0028after-macro-calls_0029">semicolons (after macro calls)</a>:</td><td> </td><td valign="top"><a href="Swallowing-the-Semicolon.html#Swallowing-the-Semicolon">Swallowing the Semicolon</a></td></tr> +<tr><td></td><td valign="top"><a href="Duplication-of-Side-Effects.html#index-side-effects-_0028in-macro-arguments_0029">side effects (in macro arguments)</a>:</td><td> </td><td valign="top"><a href="Duplication-of-Side-Effects.html#Duplication-of-Side-Effects">Duplication of Side Effects</a></td></tr> +<tr><td></td><td valign="top"><a href="Standard-Predefined-Macros.html#index-standard-predefined-macros_002e">standard predefined macros.</a>:</td><td> </td><td valign="top"><a href="Standard-Predefined-Macros.html#Standard-Predefined-Macros">Standard Predefined Macros</a></td></tr> +<tr><td></td><td valign="top"><a href="Tokenization.html#index-string-constants">string constants</a>:</td><td> </td><td valign="top"><a href="Tokenization.html#Tokenization">Tokenization</a></td></tr> +<tr><td></td><td valign="top"><a href="Tokenization.html#index-string-literals">string literals</a>:</td><td> </td><td valign="top"><a href="Tokenization.html#Tokenization">Tokenization</a></td></tr> +<tr><td></td><td valign="top"><a href="Stringizing.html#index-stringizing">stringizing</a>:</td><td> </td><td valign="top"><a href="Stringizing.html#Stringizing">Stringizing</a></td></tr> +<tr><td></td><td valign="top"><a href="Object_002dlike-Macros.html#index-symbolic-constants">symbolic constants</a>:</td><td> </td><td valign="top"><a href="Object_002dlike-Macros.html#Object_002dlike-Macros">Object-like Macros</a></td></tr> +<tr><td></td><td valign="top"><a href="Header-Files.html#index-system-header-files">system header files</a>:</td><td> </td><td valign="top"><a href="Header-Files.html#Header-Files">Header Files</a></td></tr> +<tr><td></td><td valign="top"><a href="System-Headers.html#index-system-header-files-1">system header files</a>:</td><td> </td><td valign="top"><a href="System-Headers.html#System-Headers">System Headers</a></td></tr> +<tr><td></td><td valign="top"><a href="System_002dspecific-Predefined-Macros.html#index-system_002dspecific-predefined-macros">system-specific predefined macros</a>:</td><td> </td><td valign="top"><a href="System_002dspecific-Predefined-Macros.html#System_002dspecific-Predefined-Macros">System-specific Predefined Macros</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-T">T</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Obsolete-Features.html#index-testing-predicates">testing predicates</a>:</td><td> </td><td valign="top"><a href="Obsolete-Features.html#Obsolete-Features">Obsolete Features</a></td></tr> +<tr><td></td><td valign="top"><a href="Concatenation.html#index-token-concatenation">token concatenation</a>:</td><td> </td><td valign="top"><a href="Concatenation.html#Concatenation">Concatenation</a></td></tr> +<tr><td></td><td valign="top"><a href="Concatenation.html#index-token-pasting">token pasting</a>:</td><td> </td><td valign="top"><a href="Concatenation.html#Concatenation">Concatenation</a></td></tr> +<tr><td></td><td valign="top"><a href="Tokenization.html#index-tokens">tokens</a>:</td><td> </td><td valign="top"><a href="Tokenization.html#Tokenization">Tokenization</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-traditional-C-language">traditional C language</a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Initial-processing.html#index-trigraphs">trigraphs</a>:</td><td> </td><td valign="top"><a href="Initial-processing.html#Initial-processing">Initial processing</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-U">U</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Undefining-and-Redefining-Macros.html#index-undefining-macros">undefining macros</a>:</td><td> </td><td valign="top"><a href="Undefining-and-Redefining-Macros.html#Undefining-and-Redefining-Macros">Undefining and Redefining Macros</a></td></tr> +<tr><td></td><td valign="top"><a href="Duplication-of-Side-Effects.html#index-unsafe-macros">unsafe macros</a>:</td><td> </td><td valign="top"><a href="Duplication-of-Side-Effects.html#Duplication-of-Side-Effects">Duplication of Side Effects</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-V">V</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Variadic-Macros.html#index-variable-number-of-arguments">variable number of arguments</a>:</td><td> </td><td valign="top"><a href="Variadic-Macros.html#Variadic-Macros">Variadic Macros</a></td></tr> +<tr><td></td><td valign="top"><a href="Variadic-Macros.html#index-variadic-macros">variadic macros</a>:</td><td> </td><td valign="top"><a href="Variadic-Macros.html#Variadic-Macros">Variadic Macros</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-W">W</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Once_002dOnly-Headers.html#index-wrapper-_0023ifndef">wrapper <code>#ifndef</code></a>:</td><td> </td><td valign="top"><a href="Once_002dOnly-Headers.html#Once_002dOnly-Headers">Once-Only Headers</a></td></tr> +<tr><td></td><td valign="top"><a href="Wrapper-Headers.html#index-wrapper-headers">wrapper headers</a>:</td><td> </td><td valign="top"><a href="Wrapper-Headers.html#Wrapper-Headers">Wrapper Headers</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +</table> +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Concept-Index_cp_symbol-1"><b>#</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_symbol-2"><b>_</b></a> + +<br> +<a class="summary-letter" href="#Concept-Index_cp_letter-A"><b>A</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-B"><b>B</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-C"><b>C</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-D"><b>D</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-E"><b>E</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-F"><b>F</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-G"><b>G</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-H"><b>H</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-I"><b>I</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-L"><b>L</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-M"><b>M</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-N"><b>N</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-O"><b>O</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-P"><b>P</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-R"><b>R</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-S"><b>S</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-T"><b>T</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-U"><b>U</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-V"><b>V</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-W"><b>W</b></a> + +</td></tr></table> + +<hr> +<div class="header"> +<p> +Previous: <a href="Option-Index.html#Option-Index" accesskey="p" rel="previous">Option Index</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Conditional-Syntax.html b/share/doc/cpp/Conditional-Syntax.html new file mode 100644 index 0000000..794acd6 --- /dev/null +++ b/share/doc/cpp/Conditional-Syntax.html @@ -0,0 +1,112 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Conditional Syntax</title> + +<meta name="description" content="The C Preprocessor: Conditional Syntax"> +<meta name="keywords" content="The C Preprocessor: Conditional Syntax"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Conditionals.html#Conditionals" rel="up" title="Conditionals"> +<link href="Ifdef.html#Ifdef" rel="next" title="Ifdef"> +<link href="Conditional-Uses.html#Conditional-Uses" rel="previous" title="Conditional Uses"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Conditional-Syntax"></a> +<div class="header"> +<p> +Next: <a href="Deleted-Code.html#Deleted-Code" accesskey="n" rel="next">Deleted Code</a>, Previous: <a href="Conditional-Uses.html#Conditional-Uses" accesskey="p" rel="previous">Conditional Uses</a>, Up: <a href="Conditionals.html#Conditionals" accesskey="u" rel="up">Conditionals</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Conditional-Syntax-1"></a> +<h3 class="section">4.2 Conditional Syntax</h3> + +<a name="index-_0023if"></a> +<p>A conditional in the C preprocessor begins with a <em>conditional +directive</em>: ‘<samp>#if</samp>’, ‘<samp>#ifdef</samp>’ or ‘<samp>#ifndef</samp>’. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="Ifdef.html#Ifdef" accesskey="1">Ifdef</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="If.html#If" accesskey="2">If</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Defined.html#Defined" accesskey="3">Defined</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Else.html#Else" accesskey="4">Else</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Elif.html#Elif" accesskey="5">Elif</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="_005f_005fhas_005fattribute.html#g_t_005f_005fhas_005fattribute" accesskey="6"><code>__has_attribute</code></a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="_005f_005fhas_005fcpp_005fattribute.html#g_t_005f_005fhas_005fcpp_005fattribute" accesskey="7"><code>__has_cpp_attribute</code></a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="_005f_005fhas_005fc_005fattribute.html#g_t_005f_005fhas_005fc_005fattribute" accesskey="8"><code>__has_c_attribute</code></a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="_005f_005fhas_005fbuiltin.html#g_t_005f_005fhas_005fbuiltin" accesskey="9"><code>__has_builtin</code></a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="_005f_005fhas_005finclude.html#g_t_005f_005fhas_005finclude"><code>__has_include</code></a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +</table> + + + + +</body> +</html> diff --git a/share/doc/cpp/Conditional-Uses.html b/share/doc/cpp/Conditional-Uses.html new file mode 100644 index 0000000..2d54537 --- /dev/null +++ b/share/doc/cpp/Conditional-Uses.html @@ -0,0 +1,110 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Conditional Uses</title> + +<meta name="description" content="The C Preprocessor: Conditional Uses"> +<meta name="keywords" content="The C Preprocessor: Conditional Uses"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Conditionals.html#Conditionals" rel="up" title="Conditionals"> +<link href="Conditional-Syntax.html#Conditional-Syntax" rel="next" title="Conditional Syntax"> +<link href="Conditionals.html#Conditionals" rel="previous" title="Conditionals"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Conditional-Uses"></a> +<div class="header"> +<p> +Next: <a href="Conditional-Syntax.html#Conditional-Syntax" accesskey="n" rel="next">Conditional Syntax</a>, Up: <a href="Conditionals.html#Conditionals" accesskey="u" rel="up">Conditionals</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Conditional-Uses-1"></a> +<h3 class="section">4.1 Conditional Uses</h3> + +<p>There are three general reasons to use a conditional. +</p> +<ul> +<li> A program may need to use different code depending on the machine or +operating system it is to run on. In some cases the code for one +operating system may be erroneous on another operating system; for +example, it might refer to data types or constants that do not exist on +the other system. When this happens, it is not enough to avoid +executing the invalid code. Its mere presence will cause the compiler +to reject the program. With a preprocessing conditional, the offending +code can be effectively excised from the program when it is not valid. + +</li><li> You may want to be able to compile the same source file into two +different programs. One version might make frequent time-consuming +consistency checks on its intermediate data, or print the values of +those data for debugging, and the other not. + +</li><li> A conditional whose condition is always false is one way to exclude code +from the program but keep it as a sort of comment for future reference. +</li></ul> + +<p>Simple programs that do not need system-specific logic or complex +debugging hooks generally will not need to use preprocessing +conditionals. +</p> + + + +</body> +</html> diff --git a/share/doc/cpp/Conditionals.html b/share/doc/cpp/Conditionals.html new file mode 100644 index 0000000..d07835a --- /dev/null +++ b/share/doc/cpp/Conditionals.html @@ -0,0 +1,126 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Conditionals</title> + +<meta name="description" content="The C Preprocessor: Conditionals"> +<meta name="keywords" content="The C Preprocessor: Conditionals"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html#Top" rel="up" title="Top"> +<link href="Conditional-Uses.html#Conditional-Uses" rel="next" title="Conditional Uses"> +<link href="Newlines-in-Arguments.html#Newlines-in-Arguments" rel="previous" title="Newlines in Arguments"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Conditionals"></a> +<div class="header"> +<p> +Next: <a href="Diagnostics.html#Diagnostics" accesskey="n" rel="next">Diagnostics</a>, Previous: <a href="Macros.html#Macros" accesskey="p" rel="previous">Macros</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Conditionals-1"></a> +<h2 class="chapter">4 Conditionals</h2> +<a name="index-conditionals"></a> + +<p>A <em>conditional</em> is a directive that instructs the preprocessor to +select whether or not to include a chunk of code in the final token +stream passed to the compiler. Preprocessor conditionals can test +arithmetic expressions, or whether a name is defined as a macro, or both +simultaneously using the special <code>defined</code> operator. +</p> +<p>A conditional in the C preprocessor resembles in some ways an <code>if</code> +statement in C, but it is important to understand the difference between +them. The condition in an <code>if</code> statement is tested during the +execution of your program. Its purpose is to allow your program to +behave differently from run to run, depending on the data it is +operating on. The condition in a preprocessing conditional directive is +tested when your program is compiled. Its purpose is to allow different +code to be included in the program depending on the situation at the +time of compilation. +</p> +<p>However, the distinction is becoming less clear. Modern compilers often +do test <code>if</code> statements when a program is compiled, if their +conditions are known not to vary at run time, and eliminate code which +can never be executed. If you can count on your compiler to do this, +you may find that your program is more readable if you use <code>if</code> +statements with constant conditions (perhaps determined by macros). Of +course, you can only use this to exclude code, not type definitions or +other preprocessing directives, and you can only do it if the code +remains syntactically valid when it is not to be used. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="Conditional-Uses.html#Conditional-Uses" accesskey="1">Conditional Uses</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Conditional-Syntax.html#Conditional-Syntax" accesskey="2">Conditional Syntax</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Deleted-Code.html#Deleted-Code" accesskey="3">Deleted Code</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +</table> + +<hr> +<div class="header"> +<p> +Next: <a href="Diagnostics.html#Diagnostics" accesskey="n" rel="next">Diagnostics</a>, Previous: <a href="Macros.html#Macros" accesskey="p" rel="previous">Macros</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Defined.html b/share/doc/cpp/Defined.html new file mode 100644 index 0000000..d79832f --- /dev/null +++ b/share/doc/cpp/Defined.html @@ -0,0 +1,120 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Defined</title> + +<meta name="description" content="The C Preprocessor: Defined"> +<meta name="keywords" content="The C Preprocessor: Defined"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Conditional-Syntax.html#Conditional-Syntax" rel="up" title="Conditional Syntax"> +<link href="Else.html#Else" rel="next" title="Else"> +<link href="If.html#If" rel="previous" title="If"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Defined"></a> +<div class="header"> +<p> +Next: <a href="Else.html#Else" accesskey="n" rel="next">Else</a>, Previous: <a href="If.html#If" accesskey="p" rel="previous">If</a>, Up: <a href="Conditional-Syntax.html#Conditional-Syntax" accesskey="u" rel="up">Conditional Syntax</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Defined-1"></a> +<h4 class="subsection">4.2.3 Defined</h4> + +<a name="index-defined"></a> +<p>The special operator <code>defined</code> is used in ‘<samp>#if</samp>’ and +‘<samp>#elif</samp>’ expressions to test whether a certain name is defined as a +macro. <code>defined <var>name</var></code> and <code>defined (<var>name</var>)</code> are +both expressions whose value is 1 if <var>name</var> is defined as a macro at +the current point in the program, and 0 otherwise. Thus, <code>#if defined MACRO<!-- /@w --></code> is precisely equivalent to <code>#ifdef MACRO<!-- /@w --></code>. +</p> +<p><code>defined</code> is useful when you wish to test more than one macro for +existence at once. For example, +</p> +<div class="smallexample"> +<pre class="smallexample">#if defined (__vax__) || defined (__ns16000__) +</pre></div> + +<p>would succeed if either of the names <code>__vax__</code> or +<code>__ns16000__</code> is defined as a macro. +</p> +<p>Conditionals written like this: +</p> +<div class="smallexample"> +<pre class="smallexample">#if defined BUFSIZE && BUFSIZE >= 1024 +</pre></div> + +<p>can generally be simplified to just <code>#if BUFSIZE >= 1024<!-- /@w --></code>, +since if <code>BUFSIZE</code> is not defined, it will be interpreted as having +the value zero. +</p> +<p>If the <code>defined</code> operator appears as a result of a macro expansion, +the C standard says the behavior is undefined. GNU cpp treats it as a +genuine <code>defined</code> operator and evaluates it normally. It will warn +wherever your code uses this feature if you use the command-line option +<samp>-Wpedantic</samp>, since other compilers may handle it differently. The +warning is also enabled by <samp>-Wextra</samp>, and can also be enabled +individually with <samp>-Wexpansion-to-defined</samp>. +</p> + + + +</body> +</html> diff --git a/share/doc/cpp/Deleted-Code.html b/share/doc/cpp/Deleted-Code.html new file mode 100644 index 0000000..ad8a19f --- /dev/null +++ b/share/doc/cpp/Deleted-Code.html @@ -0,0 +1,109 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Deleted Code</title> + +<meta name="description" content="The C Preprocessor: Deleted Code"> +<meta name="keywords" content="The C Preprocessor: Deleted Code"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Conditionals.html#Conditionals" rel="up" title="Conditionals"> +<link href="Diagnostics.html#Diagnostics" rel="next" title="Diagnostics"> +<link href="_005f_005fhas_005finclude.html#g_t_005f_005fhas_005finclude" rel="previous" title="__has_include"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Deleted-Code"></a> +<div class="header"> +<p> +Previous: <a href="Conditional-Syntax.html#Conditional-Syntax" accesskey="p" rel="previous">Conditional Syntax</a>, Up: <a href="Conditionals.html#Conditionals" accesskey="u" rel="up">Conditionals</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Deleted-Code-1"></a> +<h3 class="section">4.3 Deleted Code</h3> +<a name="index-commenting-out-code"></a> + +<p>If you replace or delete a part of the program but want to keep the old +code around for future reference, you often cannot simply comment it +out. Block comments do not nest, so the first comment inside the old +code will end the commenting-out. The probable result is a flood of +syntax errors. +</p> +<p>One way to avoid this problem is to use an always-false conditional +instead. For instance, put <code>#if 0</code> before the deleted code and +<code>#endif</code> after it. This works even if the code being turned +off contains conditionals, but they must be entire conditionals +(balanced ‘<samp>#if</samp>’ and ‘<samp>#endif</samp>’). +</p> +<p>Some people use <code>#ifdef notdef</code> instead. This is risky, because +<code>notdef</code> might be accidentally defined as a macro, and then the +conditional would succeed. <code>#if 0</code> can be counted on to fail. +</p> +<p>Do not use <code>#if 0</code> for comments which are not C code. Use a real +comment, instead. The interior of <code>#if 0</code> must consist of complete +tokens; in particular, single-quote characters must balance. Comments +often contain unbalanced single-quote characters (known in English as +apostrophes). These confuse <code>#if 0</code>. They don’t confuse +‘<samp>/*</samp>’. +</p> + + + +</body> +</html> diff --git a/share/doc/cpp/Diagnostics.html b/share/doc/cpp/Diagnostics.html new file mode 100644 index 0000000..6a4d09b --- /dev/null +++ b/share/doc/cpp/Diagnostics.html @@ -0,0 +1,128 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Diagnostics</title> + +<meta name="description" content="The C Preprocessor: Diagnostics"> +<meta name="keywords" content="The C Preprocessor: Diagnostics"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html#Top" rel="up" title="Top"> +<link href="Line-Control.html#Line-Control" rel="next" title="Line Control"> +<link href="Deleted-Code.html#Deleted-Code" rel="previous" title="Deleted Code"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Diagnostics"></a> +<div class="header"> +<p> +Next: <a href="Line-Control.html#Line-Control" accesskey="n" rel="next">Line Control</a>, Previous: <a href="Conditionals.html#Conditionals" accesskey="p" rel="previous">Conditionals</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Diagnostics-1"></a> +<h2 class="chapter">5 Diagnostics</h2> +<a name="index-diagnostic"></a> +<a name="index-reporting-errors"></a> +<a name="index-reporting-warnings"></a> + +<a name="index-_0023error"></a> +<p>The directive ‘<samp>#error</samp>’ causes the preprocessor to report a fatal +error. The tokens forming the rest of the line following ‘<samp>#error</samp>’ +are used as the error message. +</p> +<p>You would use ‘<samp>#error</samp>’ inside of a conditional that detects a +combination of parameters which you know the program does not properly +support. For example, if you know that the program will not run +properly on a VAX, you might write +</p> +<div class="smallexample"> +<pre class="smallexample">#ifdef __vax__ +#error "Won't work on VAXen. See comments at get_last_object." +#endif +</pre></div> + +<p>If you have several configuration parameters that must be set up by +the installation in a consistent way, you can use conditionals to detect +an inconsistency and report it with ‘<samp>#error</samp>’. For example, +</p> +<div class="smallexample"> +<pre class="smallexample">#if !defined(FOO) && defined(BAR) +#error "BAR requires FOO." +#endif +</pre></div> + +<a name="index-_0023warning"></a> +<p>The directive ‘<samp>#warning</samp>’ is like ‘<samp>#error</samp>’, but causes the +preprocessor to issue a warning and continue preprocessing. The tokens +following ‘<samp>#warning</samp>’ are used as the warning message. +</p> +<p>You might use ‘<samp>#warning</samp>’ in obsolete header files, with a message +directing the user to the header file which should be used instead. +</p> +<p>Neither ‘<samp>#error</samp>’ nor ‘<samp>#warning</samp>’ macro-expands its argument. +Internal whitespace sequences are each replaced with a single space. +The line must consist of complete tokens. It is wisest to make the +argument of these directives be a single string constant; this avoids +problems with apostrophes and the like. +</p> + + + +</body> +</html> diff --git a/share/doc/cpp/Directives-Within-Macro-Arguments.html b/share/doc/cpp/Directives-Within-Macro-Arguments.html new file mode 100644 index 0000000..0034cd8 --- /dev/null +++ b/share/doc/cpp/Directives-Within-Macro-Arguments.html @@ -0,0 +1,114 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Directives Within Macro Arguments</title> + +<meta name="description" content="The C Preprocessor: Directives Within Macro Arguments"> +<meta name="keywords" content="The C Preprocessor: Directives Within Macro Arguments"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Macros.html#Macros" rel="up" title="Macros"> +<link href="Macro-Pitfalls.html#Macro-Pitfalls" rel="next" title="Macro Pitfalls"> +<link href="Undefining-and-Redefining-Macros.html#Undefining-and-Redefining-Macros" rel="previous" title="Undefining and Redefining Macros"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Directives-Within-Macro-Arguments"></a> +<div class="header"> +<p> +Next: <a href="Macro-Pitfalls.html#Macro-Pitfalls" accesskey="n" rel="next">Macro Pitfalls</a>, Previous: <a href="Undefining-and-Redefining-Macros.html#Undefining-and-Redefining-Macros" accesskey="p" rel="previous">Undefining and Redefining Macros</a>, Up: <a href="Macros.html#Macros" accesskey="u" rel="up">Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Directives-Within-Macro-Arguments-1"></a> +<h3 class="section">3.9 Directives Within Macro Arguments</h3> +<a name="index-macro-arguments-and-directives"></a> + +<p>Occasionally it is convenient to use preprocessor directives within +the arguments of a macro. The C and C++ standards declare that +behavior in these cases is undefined. GNU CPP +processes arbitrary directives within macro arguments in +exactly the same way as it would have processed the directive were the +function-like macro invocation not present. +</p> +<p>If, within a macro invocation, that macro is redefined, then the new +definition takes effect in time for argument pre-expansion, but the +original definition is still used for argument replacement. Here is a +pathological example: +</p> +<div class="smallexample"> +<pre class="smallexample">#define f(x) x x +f (1 +#undef f +#define f 2 +f) +</pre></div> + +<p>which expands to +</p> +<div class="smallexample"> +<pre class="smallexample">1 2 1 2 +</pre></div> + +<p>with the semantics described above. +</p> + + + +</body> +</html> diff --git a/share/doc/cpp/Duplication-of-Side-Effects.html b/share/doc/cpp/Duplication-of-Side-Effects.html new file mode 100644 index 0000000..3486ba5 --- /dev/null +++ b/share/doc/cpp/Duplication-of-Side-Effects.html @@ -0,0 +1,156 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Duplication of Side Effects</title> + +<meta name="description" content="The C Preprocessor: Duplication of Side Effects"> +<meta name="keywords" content="The C Preprocessor: Duplication of Side Effects"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Macro-Pitfalls.html#Macro-Pitfalls" rel="up" title="Macro Pitfalls"> +<link href="Self_002dReferential-Macros.html#Self_002dReferential-Macros" rel="next" title="Self-Referential Macros"> +<link href="Swallowing-the-Semicolon.html#Swallowing-the-Semicolon" rel="previous" title="Swallowing the Semicolon"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Duplication-of-Side-Effects"></a> +<div class="header"> +<p> +Next: <a href="Self_002dReferential-Macros.html#Self_002dReferential-Macros" accesskey="n" rel="next">Self-Referential Macros</a>, Previous: <a href="Swallowing-the-Semicolon.html#Swallowing-the-Semicolon" accesskey="p" rel="previous">Swallowing the Semicolon</a>, Up: <a href="Macro-Pitfalls.html#Macro-Pitfalls" accesskey="u" rel="up">Macro Pitfalls</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Duplication-of-Side-Effects-1"></a> +<h4 class="subsection">3.10.4 Duplication of Side Effects</h4> + +<a name="index-side-effects-_0028in-macro-arguments_0029"></a> +<a name="index-unsafe-macros"></a> +<p>Many C programs define a macro <code>min</code>, for “minimum”, like this: +</p> +<div class="smallexample"> +<pre class="smallexample">#define min(X, Y) ((X) < (Y) ? (X) : (Y)) +</pre></div> + +<p>When you use this macro with an argument containing a side effect, +as shown here, +</p> +<div class="smallexample"> +<pre class="smallexample">next = min (x + y, foo (z)); +</pre></div> + +<p>it expands as follows: +</p> +<div class="smallexample"> +<pre class="smallexample">next = ((x + y) < (foo (z)) ? (x + y) : (foo (z))); +</pre></div> + +<p>where <code>x + y</code> has been substituted for <code>X</code> and <code>foo (z)</code> +for <code>Y</code>. +</p> +<p>The function <code>foo</code> is used only once in the statement as it appears +in the program, but the expression <code>foo (z)</code> has been substituted +twice into the macro expansion. As a result, <code>foo</code> might be called +two times when the statement is executed. If it has side effects or if +it takes a long time to compute, the results might not be what you +intended. We say that <code>min</code> is an <em>unsafe</em> macro. +</p> +<p>The best solution to this problem is to define <code>min</code> in a way that +computes the value of <code>foo (z)</code> only once. The C language offers +no standard way to do this, but it can be done with GNU extensions as +follows: +</p> +<div class="smallexample"> +<pre class="smallexample">#define min(X, Y) \ +({ typeof (X) x_ = (X); \ + typeof (Y) y_ = (Y); \ + (x_ < y_) ? x_ : y_; }) +</pre></div> + +<p>The ‘<samp>({ … })</samp>’ notation produces a compound statement that +acts as an expression. Its value is the value of its last statement. +This permits us to define local variables and assign each argument to +one. The local variables have underscores after their names to reduce +the risk of conflict with an identifier of wider scope (it is impossible +to avoid this entirely). Now each argument is evaluated exactly once. +</p> +<p>If you do not wish to use GNU C extensions, the only solution is to be +careful when <em>using</em> the macro <code>min</code>. For example, you can +calculate the value of <code>foo (z)</code>, save it in a variable, and use +that variable in <code>min</code>: +</p> +<div class="smallexample"> +<pre class="smallexample">#define min(X, Y) ((X) < (Y) ? (X) : (Y)) +… +{ + int tem = foo (z); + next = min (x + y, tem); +} +</pre></div> + +<p>(where we assume that <code>foo</code> returns type <code>int</code>). +</p> +<hr> +<div class="header"> +<p> +Next: <a href="Self_002dReferential-Macros.html#Self_002dReferential-Macros" accesskey="n" rel="next">Self-Referential Macros</a>, Previous: <a href="Swallowing-the-Semicolon.html#Swallowing-the-Semicolon" accesskey="p" rel="previous">Swallowing the Semicolon</a>, Up: <a href="Macro-Pitfalls.html#Macro-Pitfalls" accesskey="u" rel="up">Macro Pitfalls</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Elif.html b/share/doc/cpp/Elif.html new file mode 100644 index 0000000..d346f5f --- /dev/null +++ b/share/doc/cpp/Elif.html @@ -0,0 +1,129 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Elif</title> + +<meta name="description" content="The C Preprocessor: Elif"> +<meta name="keywords" content="The C Preprocessor: Elif"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Conditional-Syntax.html#Conditional-Syntax" rel="up" title="Conditional Syntax"> +<link href="_005f_005fhas_005fattribute.html#g_t_005f_005fhas_005fattribute" rel="next" title="__has_attribute"> +<link href="Else.html#Else" rel="previous" title="Else"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Elif"></a> +<div class="header"> +<p> +Next: <a href="_005f_005fhas_005fattribute.html#g_t_005f_005fhas_005fattribute" accesskey="n" rel="next"><code>__has_attribute</code></a>, Previous: <a href="Else.html#Else" accesskey="p" rel="previous">Else</a>, Up: <a href="Conditional-Syntax.html#Conditional-Syntax" accesskey="u" rel="up">Conditional Syntax</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Elif-1"></a> +<h4 class="subsection">4.2.5 Elif</h4> + +<a name="index-_0023elif"></a> +<p>One common case of nested conditionals is used to check for more than two +possible alternatives. For example, you might have +</p> +<div class="smallexample"> +<pre class="smallexample">#if X == 1 +… +#else /* X != 1 */ +#if X == 2 +… +#else /* X != 2 */ +… +#endif /* X != 2 */ +#endif /* X != 1 */ +</pre></div> + +<p>Another conditional directive, ‘<samp>#elif</samp>’, allows this to be +abbreviated as follows: +</p> +<div class="smallexample"> +<pre class="smallexample">#if X == 1 +… +#elif X == 2 +… +#else /* X != 2 and X != 1*/ +… +#endif /* X != 2 and X != 1*/ +</pre></div> + +<p>‘<samp>#elif</samp>’ stands for “else if”. Like ‘<samp>#else</samp>’, it goes in the +middle of a conditional group and subdivides it; it does not require a +matching ‘<samp>#endif</samp>’ of its own. Like ‘<samp>#if</samp>’, the ‘<samp>#elif</samp>’ +directive includes an expression to be tested. The text following the +‘<samp>#elif</samp>’ is processed only if the original ‘<samp>#if</samp>’-condition +failed and the ‘<samp>#elif</samp>’ condition succeeds. +</p> +<p>More than one ‘<samp>#elif</samp>’ can go in the same conditional group. Then +the text after each ‘<samp>#elif</samp>’ is processed only if the ‘<samp>#elif</samp>’ +condition succeeds after the original ‘<samp>#if</samp>’ and all previous +‘<samp>#elif</samp>’ directives within it have failed. +</p> +<p>‘<samp>#else</samp>’ is allowed after any number of ‘<samp>#elif</samp>’ directives, but +‘<samp>#elif</samp>’ may not follow ‘<samp>#else</samp>’. +</p> + + + +</body> +</html> diff --git a/share/doc/cpp/Else.html b/share/doc/cpp/Else.html new file mode 100644 index 0000000..a02b3d4 --- /dev/null +++ b/share/doc/cpp/Else.html @@ -0,0 +1,104 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Else</title> + +<meta name="description" content="The C Preprocessor: Else"> +<meta name="keywords" content="The C Preprocessor: Else"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Conditional-Syntax.html#Conditional-Syntax" rel="up" title="Conditional Syntax"> +<link href="Elif.html#Elif" rel="next" title="Elif"> +<link href="Defined.html#Defined" rel="previous" title="Defined"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Else"></a> +<div class="header"> +<p> +Next: <a href="Elif.html#Elif" accesskey="n" rel="next">Elif</a>, Previous: <a href="Defined.html#Defined" accesskey="p" rel="previous">Defined</a>, Up: <a href="Conditional-Syntax.html#Conditional-Syntax" accesskey="u" rel="up">Conditional Syntax</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Else-1"></a> +<h4 class="subsection">4.2.4 Else</h4> + +<a name="index-_0023else"></a> +<p>The ‘<samp>#else</samp>’ directive can be added to a conditional to provide +alternative text to be used if the condition fails. This is what it +looks like: +</p> +<div class="smallexample"> +<pre class="smallexample">#if <var>expression</var> +<var>text-if-true</var> +#else /* Not <var>expression</var> */ +<var>text-if-false</var> +#endif /* Not <var>expression</var> */ +</pre></div> + +<p>If <var>expression</var> is nonzero, the <var>text-if-true</var> is included and +the <var>text-if-false</var> is skipped. If <var>expression</var> is zero, the +opposite happens. +</p> +<p>You can use ‘<samp>#else</samp>’ with ‘<samp>#ifdef</samp>’ and ‘<samp>#ifndef</samp>’, too. +</p> + + + +</body> +</html> diff --git a/share/doc/cpp/Environment-Variables.html b/share/doc/cpp/Environment-Variables.html new file mode 100644 index 0000000..5848c40 --- /dev/null +++ b/share/doc/cpp/Environment-Variables.html @@ -0,0 +1,195 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Environment Variables</title> + +<meta name="description" content="The C Preprocessor: Environment Variables"> +<meta name="keywords" content="The C Preprocessor: Environment Variables"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html#Top" rel="up" title="Top"> +<link href="GNU-Free-Documentation-License.html#GNU-Free-Documentation-License" rel="next" title="GNU Free Documentation License"> +<link href="Invocation.html#Invocation" rel="previous" title="Invocation"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Environment-Variables"></a> +<div class="header"> +<p> +Next: <a href="GNU-Free-Documentation-License.html#GNU-Free-Documentation-License" accesskey="n" rel="next">GNU Free Documentation License</a>, Previous: <a href="Invocation.html#Invocation" accesskey="p" rel="previous">Invocation</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Environment-Variables-1"></a> +<h2 class="chapter">13 Environment Variables</h2> +<a name="index-environment-variables"></a> + +<p>This section describes the environment variables that affect how CPP +operates. You can use them to specify directories or prefixes to use +when searching for include files, or to control dependency output. +</p> +<p>Note that you can also specify places to search using options such as +<samp>-I</samp>, and control dependency output with options like +<samp>-M</samp> (see <a href="Invocation.html#Invocation">Invocation</a>). These take precedence over +environment variables, which in turn take precedence over the +configuration of GCC. +</p> + + + +<dl compact="compact"> +<dt><code>CPATH</code> +<a name="index-CPATH"></a> +</dt> +<dt><code>C_INCLUDE_PATH</code> +<a name="index-C_005fINCLUDE_005fPATH"></a> +</dt> +<dt><code>CPLUS_INCLUDE_PATH</code> +<a name="index-CPLUS_005fINCLUDE_005fPATH"></a> +</dt> +<dt><code>OBJC_INCLUDE_PATH</code> +<a name="index-OBJC_005fINCLUDE_005fPATH"></a> +</dt> +<dd><p>Each variable’s value is a list of directories separated by a special +character, much like <code>PATH</code>, in which to look for header files. +The special character, <code>PATH_SEPARATOR</code>, is target-dependent and +determined at GCC build time. For Microsoft Windows-based targets it is a +semicolon, and for almost all other targets it is a colon. +</p> +<p><code>CPATH</code> specifies a list of directories to be searched as if +specified with <samp>-I</samp>, but after any paths given with <samp>-I</samp> +options on the command line. This environment variable is used +regardless of which language is being preprocessed. +</p> +<p>The remaining environment variables apply only when preprocessing the +particular language indicated. Each specifies a list of directories +to be searched as if specified with <samp>-isystem</samp>, but after any +paths given with <samp>-isystem</samp> options on the command line. +</p> +<p>In all these variables, an empty element instructs the compiler to +search its current working directory. Empty elements can appear at the +beginning or end of a path. For instance, if the value of +<code>CPATH</code> is <code>:/special/include</code>, that has the same +effect as ‘<samp><span class="nolinebreak">-I.</span> <span class="nolinebreak">-I/special/include</span><!-- /@w --></samp>’. +</p> +<p>See also <a href="Search-Path.html#Search-Path">Search Path</a>. +</p> +<a name="index-dependencies-for-make-as-output"></a> +</dd> +<dt><code>DEPENDENCIES_OUTPUT</code> +<a name="index-DEPENDENCIES_005fOUTPUT"></a> +</dt> +<dd><p>If this variable is set, its value specifies how to output +dependencies for Make based on the non-system header files processed +by the compiler. System header files are ignored in the dependency +output. +</p> +<p>The value of <code>DEPENDENCIES_OUTPUT</code> can be just a file name, in +which case the Make rules are written to that file, guessing the target +name from the source file name. Or the value can have the form +‘<samp><var>file</var> <var>target</var></samp>’, in which case the rules are written to +file <var>file</var> using <var>target</var> as the target name. +</p> +<p>In other words, this environment variable is equivalent to combining +the options <samp>-MM</samp> and <samp>-MF</samp> +(see <a href="Invocation.html#Invocation">Invocation</a>), +with an optional <samp>-MT</samp> switch too. +</p> +<a name="index-dependencies-for-make-as-output-1"></a> +</dd> +<dt><code>SUNPRO_DEPENDENCIES</code> +<a name="index-SUNPRO_005fDEPENDENCIES"></a> +</dt> +<dd><p>This variable is the same as <code>DEPENDENCIES_OUTPUT</code> (see above), +except that system header files are not ignored, so it implies +<samp>-M</samp> rather than <samp>-MM</samp>. However, the dependence on the +main input file is omitted. +See <a href="Invocation.html#Invocation">Invocation</a>. +</p> +</dd> +<dt><code>SOURCE_DATE_EPOCH</code> +<a name="index-SOURCE_005fDATE_005fEPOCH"></a> +</dt> +<dd><p>If this variable is set, its value specifies a UNIX timestamp to be +used in replacement of the current date and time in the <code>__DATE__</code> +and <code>__TIME__</code> macros, so that the embedded timestamps become +reproducible. +</p> +<p>The value of <code>SOURCE_DATE_EPOCH</code> must be a UNIX timestamp, +defined as the number of seconds (excluding leap seconds) since +01 Jan 1970 00:00:00 represented in ASCII; identical to the output of +<code>date +%s</code> on GNU/Linux and other systems that support the +<code>%s</code> extension in the <code>date</code> command. +</p> +<p>The value should be a known timestamp such as the last modification +time of the source or package and it should be set by the build +process. +</p> +</dd> +</dl> + +<hr> +<div class="header"> +<p> +Next: <a href="GNU-Free-Documentation-License.html#GNU-Free-Documentation-License" accesskey="n" rel="next">GNU Free Documentation License</a>, Previous: <a href="Invocation.html#Invocation" accesskey="p" rel="previous">Invocation</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Function_002dlike-Macros.html b/share/doc/cpp/Function_002dlike-Macros.html new file mode 100644 index 0000000..a0b0786 --- /dev/null +++ b/share/doc/cpp/Function_002dlike-Macros.html @@ -0,0 +1,130 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Function-like Macros</title> + +<meta name="description" content="The C Preprocessor: Function-like Macros"> +<meta name="keywords" content="The C Preprocessor: Function-like Macros"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Macros.html#Macros" rel="up" title="Macros"> +<link href="Macro-Arguments.html#Macro-Arguments" rel="next" title="Macro Arguments"> +<link href="Object_002dlike-Macros.html#Object_002dlike-Macros" rel="previous" title="Object-like Macros"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Function_002dlike-Macros"></a> +<div class="header"> +<p> +Next: <a href="Macro-Arguments.html#Macro-Arguments" accesskey="n" rel="next">Macro Arguments</a>, Previous: <a href="Object_002dlike-Macros.html#Object_002dlike-Macros" accesskey="p" rel="previous">Object-like Macros</a>, Up: <a href="Macros.html#Macros" accesskey="u" rel="up">Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Function_002dlike-Macros-1"></a> +<h3 class="section">3.2 Function-like Macros</h3> +<a name="index-function_002dlike-macros"></a> + +<p>You can also define macros whose use looks like a function call. These +are called <em>function-like macros</em>. To define a function-like macro, +you use the same ‘<samp>#define</samp>’ directive, but you put a pair of +parentheses immediately after the macro name. For example, +</p> +<div class="smallexample"> +<pre class="smallexample">#define lang_init() c_init() +lang_init() + → c_init() +</pre></div> + +<p>A function-like macro is only expanded if its name appears with a pair +of parentheses after it. If you write just the name, it is left alone. +This can be useful when you have a function and a macro of the same +name, and you wish to use the function sometimes. +</p> +<div class="smallexample"> +<pre class="smallexample">extern void foo(void); +#define foo() /* <span class="roman">optimized inline version</span> */ +… + foo(); + funcptr = foo; +</pre></div> + +<p>Here the call to <code>foo()</code> will use the macro, but the function +pointer will get the address of the real function. If the macro were to +be expanded, it would cause a syntax error. +</p> +<p>If you put spaces between the macro name and the parentheses in the +macro definition, that does not define a function-like macro, it defines +an object-like macro whose expansion happens to begin with a pair of +parentheses. +</p> +<div class="smallexample"> +<pre class="smallexample">#define lang_init () c_init() +lang_init() + → () c_init()() +</pre></div> + +<p>The first two pairs of parentheses in this expansion come from the +macro. The third is the pair that was originally after the macro +invocation. Since <code>lang_init</code> is an object-like macro, it does not +consume those parentheses. +</p> + + + +</body> +</html> diff --git a/share/doc/cpp/GNU-Free-Documentation-License.html b/share/doc/cpp/GNU-Free-Documentation-License.html new file mode 100644 index 0000000..297aa7a --- /dev/null +++ b/share/doc/cpp/GNU-Free-Documentation-License.html @@ -0,0 +1,560 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: GNU Free Documentation License</title> + +<meta name="description" content="The C Preprocessor: GNU Free Documentation License"> +<meta name="keywords" content="The C Preprocessor: GNU Free Documentation License"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html#Top" rel="up" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="next" title="Index of Directives"> +<link href="Environment-Variables.html#Environment-Variables" rel="previous" title="Environment Variables"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="GNU-Free-Documentation-License"></a> +<div class="header"> +<p> +Next: <a href="Index-of-Directives.html#Index-of-Directives" accesskey="n" rel="next">Index of Directives</a>, Previous: <a href="Environment-Variables.html#Environment-Variables" accesskey="p" rel="previous">Environment Variables</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="GNU-Free-Documentation-License-1"></a> +<h2 class="unnumbered">GNU Free Documentation License</h2> + +<a name="index-FDL_002c-GNU-Free-Documentation-License"></a> +<div align="center">Version 1.3, 3 November 2008 +</div> +<div class="display"> +<pre class="display">Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. +<a href="https://www.fsf.org">https://www.fsf.org</a> + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +</pre></div> + +<ol> +<li> PREAMBLE + +<p>The purpose of this License is to make a manual, textbook, or other +functional and useful document <em>free</em> in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. +</p> +<p>This License is a kind of “copyleft”, which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. +</p> +<p>We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. +</p> +</li><li> APPLICABILITY AND DEFINITIONS + +<p>This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The “Document”, below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as “you”. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. +</p> +<p>A “Modified Version” of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. +</p> +<p>A “Secondary Section” is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document’s overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. +</p> +<p>The “Invariant Sections” are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. +</p> +<p>The “Cover Texts” are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. +</p> +<p>A “Transparent” copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not “Transparent” is called “Opaque”. +</p> +<p>Examples of suitable formats for Transparent copies include plain +<small>ASCII</small> without markup, Texinfo input format, LaTeX input +format, <acronym>SGML</acronym> or <acronym>XML</acronym> using a publicly available +<acronym>DTD</acronym>, and standard-conforming simple <acronym>HTML</acronym>, +PostScript or <acronym>PDF</acronym> designed for human modification. Examples +of transparent image formats include <acronym>PNG</acronym>, <acronym>XCF</acronym> and +<acronym>JPG</acronym>. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, <acronym>SGML</acronym> or +<acronym>XML</acronym> for which the <acronym>DTD</acronym> and/or processing tools are +not generally available, and the machine-generated <acronym>HTML</acronym>, +PostScript or <acronym>PDF</acronym> produced by some word processors for +output purposes only. +</p> +<p>The “Title Page” means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, “Title Page” means +the text near the most prominent appearance of the work’s title, +preceding the beginning of the body of the text. +</p> +<p>The “publisher” means any person or entity that distributes copies +of the Document to the public. +</p> +<p>A section “Entitled XYZ” means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as “Acknowledgements”, +“Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” +of such a section when you modify the Document means that it remains a +section “Entitled XYZ” according to this definition. +</p> +<p>The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. +</p> +</li><li> VERBATIM COPYING + +<p>You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. +</p> +<p>You may also lend copies, under the same conditions stated above, and +you may publicly display copies. +</p> +</li><li> COPYING IN QUANTITY + +<p>If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document’s license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. +</p> +<p>If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. +</p> +<p>If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. +</p> +<p>It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. +</p> +</li><li> MODIFICATIONS + +<p>You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: +</p> +<ol> +<li> Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +</li><li> List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +</li><li> State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +</li><li> Preserve all the copyright notices of the Document. + +</li><li> Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +</li><li> Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +</li><li> Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document’s license notice. + +</li><li> Include an unaltered copy of this License. + +</li><li> Preserve the section Entitled “History”, Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled “History” in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +</li><li> Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the “History” section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +</li><li> For any section Entitled “Acknowledgements” or “Dedications”, Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +</li><li> Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +</li><li> Delete any section Entitled “Endorsements”. Such a section +may not be included in the Modified Version. + +</li><li> Do not retitle any existing section to be Entitled “Endorsements” or +to conflict in title with any Invariant Section. + +</li><li> Preserve any Warranty Disclaimers. +</li></ol> + +<p>If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version’s license notice. +These titles must be distinct from any other section titles. +</p> +<p>You may add a section Entitled “Endorsements”, provided it contains +nothing but endorsements of your Modified Version by various +parties—for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. +</p> +<p>You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. +</p> +<p>The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. +</p> +</li><li> COMBINING DOCUMENTS + +<p>You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. +</p> +<p>The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. +</p> +<p>In the combination, you must combine any sections Entitled “History” +in the various original documents, forming one section Entitled +“History”; likewise combine any sections Entitled “Acknowledgements”, +and any sections Entitled “Dedications”. You must delete all +sections Entitled “Endorsements.” +</p> +</li><li> COLLECTIONS OF DOCUMENTS + +<p>You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. +</p> +<p>You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. +</p> +</li><li> AGGREGATION WITH INDEPENDENT WORKS + +<p>A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an “aggregate” if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation’s users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. +</p> +<p>If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document’s Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. +</p> +</li><li> TRANSLATION + +<p>Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. +</p> +<p>If a section in the Document is Entitled “Acknowledgements”, +“Dedications”, or “History”, the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. +</p> +</li><li> TERMINATION + +<p>You may not copy, modify, sublicense, or distribute the Document +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, or distribute it is void, and +will automatically terminate your rights under this License. +</p> +<p>However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. +</p> +<p>Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. +</p> +<p>Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, receipt of a copy of some or all of the same material does +not give you any rights to use it. +</p> +</li><li> FUTURE REVISIONS OF THIS LICENSE + +<p>The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +<a href="https://www.gnu.org/copyleft/">https://www.gnu.org/copyleft/</a>. +</p> +<p>Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License “or any later version” applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. If the Document +specifies that a proxy can decide which future versions of this +License can be used, that proxy’s public statement of acceptance of a +version permanently authorizes you to choose that version for the +Document. +</p> +</li><li> RELICENSING + +<p>“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any +World Wide Web server that publishes copyrightable works and also +provides prominent facilities for anybody to edit those works. A +public wiki that anybody can edit is an example of such a server. A +“Massive Multiauthor Collaboration” (or “MMC”) contained in the +site means any set of copyrightable works thus published on the MMC +site. +</p> +<p>“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 +license published by Creative Commons Corporation, a not-for-profit +corporation with a principal place of business in San Francisco, +California, as well as future copyleft versions of that license +published by that same organization. +</p> +<p>“Incorporate” means to publish or republish a Document, in whole or +in part, as part of another Document. +</p> +<p>An MMC is “eligible for relicensing” if it is licensed under this +License, and if all works that were first published under this License +somewhere other than this MMC, and subsequently incorporated in whole +or in part into the MMC, (1) had no cover texts or invariant sections, +and (2) were thus incorporated prior to November 1, 2008. +</p> +<p>The operator of an MMC Site may republish an MMC contained in the site +under CC-BY-SA on the same site at any time before August 1, 2009, +provided the MMC is eligible for relicensing. +</p> +</li></ol> + +<a name="ADDENDUM_003a-How-to-use-this-License-for-your-documents"></a> +<h3 class="unnumberedsec">ADDENDUM: How to use this License for your documents</h3> + +<p>To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: +</p> +<div class="smallexample"> +<pre class="smallexample"> Copyright (C) <var>year</var> <var>your name</var>. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +</pre></div> + +<p>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the “with...Texts.” line with this: +</p> +<div class="smallexample"> +<pre class="smallexample"> with the Invariant Sections being <var>list their titles</var>, with + the Front-Cover Texts being <var>list</var>, and with the Back-Cover Texts + being <var>list</var>. +</pre></div> + +<p>If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. +</p> +<p>If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. +</p> + + +<hr> +<div class="header"> +<p> +Next: <a href="Index-of-Directives.html#Index-of-Directives" accesskey="n" rel="next">Index of Directives</a>, Previous: <a href="Environment-Variables.html#Environment-Variables" accesskey="p" rel="previous">Environment Variables</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Header-Files.html b/share/doc/cpp/Header-Files.html new file mode 100644 index 0000000..4f8c479 --- /dev/null +++ b/share/doc/cpp/Header-Files.html @@ -0,0 +1,144 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Header Files</title> + +<meta name="description" content="The C Preprocessor: Header Files"> +<meta name="keywords" content="The C Preprocessor: Header Files"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html#Top" rel="up" title="Top"> +<link href="Include-Syntax.html#Include-Syntax" rel="next" title="Include Syntax"> +<link href="The-preprocessing-language.html#The-preprocessing-language" rel="previous" title="The preprocessing language"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Header-Files"></a> +<div class="header"> +<p> +Next: <a href="Macros.html#Macros" accesskey="n" rel="next">Macros</a>, Previous: <a href="Overview.html#Overview" accesskey="p" rel="previous">Overview</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Header-Files-1"></a> +<h2 class="chapter">2 Header Files</h2> + +<a name="index-header-file"></a> +<p>A header file is a file containing C declarations and macro definitions +(see <a href="Macros.html#Macros">Macros</a>) to be shared between several source files. You request +the use of a header file in your program by <em>including</em> it, with the +C preprocessing directive ‘<samp>#include</samp>’. +</p> +<p>Header files serve two purposes. +</p> +<ul> +<li> <a name="index-system-header-files"></a> +System header files declare the interfaces to parts of the operating +system. You include them in your program to supply the definitions and +declarations you need to invoke system calls and libraries. + +</li><li> Your own header files contain declarations for interfaces between the +source files of your program. Each time you have a group of related +declarations and macro definitions all or most of which are needed in +several different source files, it is a good idea to create a header +file for them. +</li></ul> + +<p>Including a header file produces the same results as copying the header +file into each source file that needs it. Such copying would be +time-consuming and error-prone. With a header file, the related +declarations appear in only one place. If they need to be changed, they +can be changed in one place, and programs that include the header file +will automatically use the new version when next recompiled. The header +file eliminates the labor of finding and changing all the copies as well +as the risk that a failure to find one copy will result in +inconsistencies within a program. +</p> +<p>In C, the usual convention is to give header files names that end with +<samp>.h</samp>. It is most portable to use only letters, digits, dashes, and +underscores in header file names, and at most one dot. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="Include-Syntax.html#Include-Syntax" accesskey="1">Include Syntax</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Include-Operation.html#Include-Operation" accesskey="2">Include Operation</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Search-Path.html#Search-Path" accesskey="3">Search Path</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Once_002dOnly-Headers.html#Once_002dOnly-Headers" accesskey="4">Once-Only Headers</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef" accesskey="5">Alternatives to Wrapper #ifndef</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Computed-Includes.html#Computed-Includes" accesskey="6">Computed Includes</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Wrapper-Headers.html#Wrapper-Headers" accesskey="7">Wrapper Headers</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="System-Headers.html#System-Headers" accesskey="8">System Headers</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +</table> + +<hr> +<div class="header"> +<p> +Next: <a href="Macros.html#Macros" accesskey="n" rel="next">Macros</a>, Previous: <a href="Overview.html#Overview" accesskey="p" rel="previous">Overview</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Identifier-characters.html b/share/doc/cpp/Identifier-characters.html new file mode 100644 index 0000000..e59a263 --- /dev/null +++ b/share/doc/cpp/Identifier-characters.html @@ -0,0 +1,70 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<!-- This file redirects to the location of a node or anchor --> +<head> +<title>The C Preprocessor: Identifier characters</title> + +<meta name="description" content="The C Preprocessor: Identifier characters"> +<meta name="keywords" content="The C Preprocessor: Identifier characters"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + +<meta http-equiv="Refresh" content="0; url=Implementation_002ddefined-behavior.html#Identifier-characters"> + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> + +<p>The node you are looking for is at <a href="Implementation_002ddefined-behavior.html#Identifier-characters">Identifier characters</a>.</p> +</body> diff --git a/share/doc/cpp/If.html b/share/doc/cpp/If.html new file mode 100644 index 0000000..55b5152 --- /dev/null +++ b/share/doc/cpp/If.html @@ -0,0 +1,146 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: If</title> + +<meta name="description" content="The C Preprocessor: If"> +<meta name="keywords" content="The C Preprocessor: If"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Conditional-Syntax.html#Conditional-Syntax" rel="up" title="Conditional Syntax"> +<link href="Defined.html#Defined" rel="next" title="Defined"> +<link href="Ifdef.html#Ifdef" rel="previous" title="Ifdef"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="If"></a> +<div class="header"> +<p> +Next: <a href="Defined.html#Defined" accesskey="n" rel="next">Defined</a>, Previous: <a href="Ifdef.html#Ifdef" accesskey="p" rel="previous">Ifdef</a>, Up: <a href="Conditional-Syntax.html#Conditional-Syntax" accesskey="u" rel="up">Conditional Syntax</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="If-1"></a> +<h4 class="subsection">4.2.2 If</h4> + +<p>The ‘<samp>#if</samp>’ directive allows you to test the value of an arithmetic +expression, rather than the mere existence of one macro. Its syntax is +</p> +<div class="smallexample"> +<pre class="smallexample">#if <var>expression</var> + +<var>controlled text</var> + +#endif /* <var>expression</var> */ +</pre></div> + +<p><var>expression</var> is a C expression of integer type, subject to stringent +restrictions. It may contain +</p> +<ul> +<li> Integer constants. + +</li><li> Character constants, which are interpreted as they would be in normal +code. + +</li><li> Arithmetic operators for addition, subtraction, multiplication, +division, bitwise operations, shifts, comparisons, and logical +operations (<code>&&</code> and <code>||</code>). The latter two obey the usual +short-circuiting rules of standard C. + +</li><li> Macros. All macros in the expression are expanded before actual +computation of the expression’s value begins. + +</li><li> Uses of the <code>defined</code> operator, which lets you check whether macros +are defined in the middle of an ‘<samp>#if</samp>’. + +</li><li> Identifiers that are not macros, which are all considered to be the +number zero. This allows you to write <code>#if MACRO<!-- /@w --></code> instead of +<code>#ifdef MACRO<!-- /@w --></code>, if you know that MACRO, when defined, will +always have a nonzero value. Function-like macros used without their +function call parentheses are also treated as zero. + +<p>In some contexts this shortcut is undesirable. The <samp>-Wundef</samp> +option causes GCC to warn whenever it encounters an identifier which is +not a macro in an ‘<samp>#if</samp>’. +</p></li></ul> + +<p>The preprocessor does not know anything about types in the language. +Therefore, <code>sizeof</code> operators are not recognized in ‘<samp>#if</samp>’, and +neither are <code>enum</code> constants. They will be taken as identifiers +which are not macros, and replaced by zero. In the case of +<code>sizeof</code>, this is likely to cause the expression to be invalid. +</p> +<p>The preprocessor calculates the value of <var>expression</var>. It carries +out all calculations in the widest integer type known to the compiler; +on most machines supported by GCC this is 64 bits. This is not the same +rule as the compiler uses to calculate the value of a constant +expression, and may give different results in some cases. If the value +comes out to be nonzero, the ‘<samp>#if</samp>’ succeeds and the <var>controlled +text</var> is included; otherwise it is skipped. +</p> +<hr> +<div class="header"> +<p> +Next: <a href="Defined.html#Defined" accesskey="n" rel="next">Defined</a>, Previous: <a href="Ifdef.html#Ifdef" accesskey="p" rel="previous">Ifdef</a>, Up: <a href="Conditional-Syntax.html#Conditional-Syntax" accesskey="u" rel="up">Conditional Syntax</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Ifdef.html b/share/doc/cpp/Ifdef.html new file mode 100644 index 0000000..41b2b5c --- /dev/null +++ b/share/doc/cpp/Ifdef.html @@ -0,0 +1,163 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Ifdef</title> + +<meta name="description" content="The C Preprocessor: Ifdef"> +<meta name="keywords" content="The C Preprocessor: Ifdef"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Conditional-Syntax.html#Conditional-Syntax" rel="up" title="Conditional Syntax"> +<link href="If.html#If" rel="next" title="If"> +<link href="Conditional-Syntax.html#Conditional-Syntax" rel="previous" title="Conditional Syntax"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Ifdef"></a> +<div class="header"> +<p> +Next: <a href="If.html#If" accesskey="n" rel="next">If</a>, Up: <a href="Conditional-Syntax.html#Conditional-Syntax" accesskey="u" rel="up">Conditional Syntax</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Ifdef-1"></a> +<h4 class="subsection">4.2.1 Ifdef</h4> +<a name="index-_0023ifdef"></a> +<a name="index-_0023endif"></a> + +<p>The simplest sort of conditional is +</p> +<div class="smallexample"> +<pre class="smallexample">#ifdef <var>MACRO</var> + +<var>controlled text</var> + +#endif /* <var>MACRO</var> */ +</pre></div> + +<a name="index-conditional-group"></a> +<p>This block is called a <em>conditional group</em>. <var>controlled text</var> +will be included in the output of the preprocessor if and only if +<var>MACRO</var> is defined. We say that the conditional <em>succeeds</em> if +<var>MACRO</var> is defined, <em>fails</em> if it is not. +</p> +<p>The <var>controlled text</var> inside of a conditional can include +preprocessing directives. They are executed only if the conditional +succeeds. You can nest conditional groups inside other conditional +groups, but they must be completely nested. In other words, +‘<samp>#endif</samp>’ always matches the nearest ‘<samp>#ifdef</samp>’ (or +‘<samp>#ifndef</samp>’, or ‘<samp>#if</samp>’). Also, you cannot start a conditional +group in one file and end it in another. +</p> +<p>Even if a conditional fails, the <var>controlled text</var> inside it is +still run through initial transformations and tokenization. Therefore, +it must all be lexically valid C. Normally the only way this matters is +that all comments and string literals inside a failing conditional group +must still be properly ended. +</p> +<p>The comment following the ‘<samp>#endif</samp>’ is not required, but it is a +good practice if there is a lot of <var>controlled text</var>, because it +helps people match the ‘<samp>#endif</samp>’ to the corresponding ‘<samp>#ifdef</samp>’. +Older programs sometimes put <var>MACRO</var> directly after the +‘<samp>#endif</samp>’ without enclosing it in a comment. This is invalid code +according to the C standard. CPP accepts it with a warning. It +never affects which ‘<samp>#ifndef</samp>’ the ‘<samp>#endif</samp>’ matches. +</p> +<a name="index-_0023ifndef"></a> +<p>Sometimes you wish to use some code if a macro is <em>not</em> defined. +You can do this by writing ‘<samp>#ifndef</samp>’ instead of ‘<samp>#ifdef</samp>’. +One common use of ‘<samp>#ifndef</samp>’ is to include code only the first +time a header file is included. See <a href="Once_002dOnly-Headers.html#Once_002dOnly-Headers">Once-Only Headers</a>. +</p> +<p>Macro definitions can vary between compilations for several reasons. +Here are some samples. +</p> +<ul> +<li> Some macros are predefined on each kind of machine +(see <a href="System_002dspecific-Predefined-Macros.html#System_002dspecific-Predefined-Macros">System-specific Predefined Macros</a>). This allows you to provide +code specially tuned for a particular machine. + +</li><li> System header files define more macros, associated with the features +they implement. You can test these macros with conditionals to avoid +using a system feature on a machine where it is not implemented. + +</li><li> Macros can be defined or undefined with the <samp>-D</samp> and <samp>-U</samp> +command-line options when you compile the program. You can arrange to +compile the same source file into two different programs by choosing a +macro name to specify which program you want, writing conditionals to +test whether or how this macro is defined, and then controlling the +state of the macro with command-line options, perhaps set in the +Makefile. See <a href="Invocation.html#Invocation">Invocation</a>. + +</li><li> Your program might have a special header file (often called +<samp>config.h</samp>) that is adjusted when the program is compiled. It can +define or not define macros depending on the features of the system and +the desired capabilities of the program. The adjustment can be +automated by a tool such as <code>autoconf</code>, or done by hand. +</li></ul> + +<hr> +<div class="header"> +<p> +Next: <a href="If.html#If" accesskey="n" rel="next">If</a>, Up: <a href="Conditional-Syntax.html#Conditional-Syntax" accesskey="u" rel="up">Conditional Syntax</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Implementation-Details.html b/share/doc/cpp/Implementation-Details.html new file mode 100644 index 0000000..33b697f --- /dev/null +++ b/share/doc/cpp/Implementation-Details.html @@ -0,0 +1,101 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Implementation Details</title> + +<meta name="description" content="The C Preprocessor: Implementation Details"> +<meta name="keywords" content="The C Preprocessor: Implementation Details"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html#Top" rel="up" title="Top"> +<link href="Implementation_002ddefined-behavior.html#Implementation_002ddefined-behavior" rel="next" title="Implementation-defined behavior"> +<link href="Traditional-warnings.html#Traditional-warnings" rel="previous" title="Traditional warnings"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Implementation-Details"></a> +<div class="header"> +<p> +Next: <a href="Invocation.html#Invocation" accesskey="n" rel="next">Invocation</a>, Previous: <a href="Traditional-Mode.html#Traditional-Mode" accesskey="p" rel="previous">Traditional Mode</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Implementation-Details-1"></a> +<h2 class="chapter">11 Implementation Details</h2> + +<p>Here we document details of how the preprocessor’s implementation +affects its user-visible behavior. You should try to avoid undue +reliance on behavior described here, as it is possible that it will +change subtly in future implementations. +</p> +<p>Also documented here are obsolete features still supported by CPP. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="Implementation_002ddefined-behavior.html#Implementation_002ddefined-behavior" accesskey="1">Implementation-defined behavior</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Implementation-limits.html#Implementation-limits" accesskey="2">Implementation limits</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Obsolete-Features.html#Obsolete-Features" accesskey="3">Obsolete Features</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +</table> + + + + +</body> +</html> diff --git a/share/doc/cpp/Implementation-limits.html b/share/doc/cpp/Implementation-limits.html new file mode 100644 index 0000000..80ba0b4 --- /dev/null +++ b/share/doc/cpp/Implementation-limits.html @@ -0,0 +1,152 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Implementation limits</title> + +<meta name="description" content="The C Preprocessor: Implementation limits"> +<meta name="keywords" content="The C Preprocessor: Implementation limits"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Implementation-Details.html#Implementation-Details" rel="up" title="Implementation Details"> +<link href="Obsolete-Features.html#Obsolete-Features" rel="next" title="Obsolete Features"> +<link href="Implementation_002ddefined-behavior.html#Implementation_002ddefined-behavior" rel="previous" title="Implementation-defined behavior"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Implementation-limits"></a> +<div class="header"> +<p> +Next: <a href="Obsolete-Features.html#Obsolete-Features" accesskey="n" rel="next">Obsolete Features</a>, Previous: <a href="Implementation_002ddefined-behavior.html#Implementation_002ddefined-behavior" accesskey="p" rel="previous">Implementation-defined behavior</a>, Up: <a href="Implementation-Details.html#Implementation-Details" accesskey="u" rel="up">Implementation Details</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Implementation-limits-1"></a> +<h3 class="section">11.2 Implementation limits</h3> +<a name="index-implementation-limits"></a> + +<p>CPP has a small number of internal limits. This section lists the +limits which the C standard requires to be no lower than some minimum, +and all the others known. It is intended that there should be as few limits +as possible. If you encounter an undocumented or inconvenient limit, +please report that as a bug. See <a href="http://gcc.gnu.org/onlinedocs/gcc/Bugs.html#Bugs">Reporting Bugs</a> in <cite>Using +the GNU Compiler Collection (GCC)</cite>. +</p> +<p>Where we say something is limited <em>only by available memory</em>, that +means that internal data structures impose no intrinsic limit, and space +is allocated with <code>malloc</code> or equivalent. The actual limit will +therefore depend on many things, such as the size of other things +allocated by the compiler at the same time, the amount of memory +consumed by other processes on the same computer, etc. +</p> +<ul> +<li> Nesting levels of ‘<samp>#include</samp>’ files. + +<p>We impose an arbitrary limit of 200 levels, to avoid runaway recursion. +The standard requires at least 15 levels. +</p> +</li><li> Nesting levels of conditional inclusion. + +<p>The C standard mandates this be at least 63. CPP is limited only by +available memory. +</p> +</li><li> Levels of parenthesized expressions within a full expression. + +<p>The C standard requires this to be at least 63. In preprocessor +conditional expressions, it is limited only by available memory. +</p> +</li><li> Significant initial characters in an identifier or macro name. + +<p>The preprocessor treats all characters as significant. The C standard +requires only that the first 63 be significant. +</p> +</li><li> Number of macros simultaneously defined in a single translation unit. + +<p>The standard requires at least 4095 be possible. CPP is limited only +by available memory. +</p> +</li><li> Number of parameters in a macro definition and arguments in a macro call. + +<p>We allow <code>USHRT_MAX</code>, which is no smaller than 65,535. The minimum +required by the standard is 127. +</p> +</li><li> Number of characters on a logical source line. + +<p>The C standard requires a minimum of 4096 be permitted. CPP places +no limits on this, but you may get incorrect column numbers reported in +diagnostics for lines longer than 65,535 characters. +</p> +</li><li> Maximum size of a source file. + +<p>The standard does not specify any lower limit on the maximum size of a +source file. GNU cpp maps files into memory, so it is limited by the +available address space. This is generally at least two gigabytes. +Depending on the operating system, the size of physical memory may or +may not be a limitation. +</p> +</li></ul> + +<hr> +<div class="header"> +<p> +Next: <a href="Obsolete-Features.html#Obsolete-Features" accesskey="n" rel="next">Obsolete Features</a>, Previous: <a href="Implementation_002ddefined-behavior.html#Implementation_002ddefined-behavior" accesskey="p" rel="previous">Implementation-defined behavior</a>, Up: <a href="Implementation-Details.html#Implementation-Details" accesskey="u" rel="up">Implementation Details</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Implementation_002ddefined-behavior.html b/share/doc/cpp/Implementation_002ddefined-behavior.html new file mode 100644 index 0000000..1361349 --- /dev/null +++ b/share/doc/cpp/Implementation_002ddefined-behavior.html @@ -0,0 +1,176 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Implementation-defined behavior</title> + +<meta name="description" content="The C Preprocessor: Implementation-defined behavior"> +<meta name="keywords" content="The C Preprocessor: Implementation-defined behavior"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Implementation-Details.html#Implementation-Details" rel="up" title="Implementation Details"> +<link href="Implementation-limits.html#Implementation-limits" rel="next" title="Implementation limits"> +<link href="Implementation-Details.html#Implementation-Details" rel="previous" title="Implementation Details"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Implementation_002ddefined-behavior"></a> +<div class="header"> +<p> +Next: <a href="Implementation-limits.html#Implementation-limits" accesskey="n" rel="next">Implementation limits</a>, Up: <a href="Implementation-Details.html#Implementation-Details" accesskey="u" rel="up">Implementation Details</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Implementation_002ddefined-behavior-1"></a> +<h3 class="section">11.1 Implementation-defined behavior</h3> +<a name="index-implementation_002ddefined-behavior"></a> + +<p>This is how CPP behaves in all the cases which the C standard +describes as <em>implementation-defined</em>. This term means that the +implementation is free to do what it likes, but must document its choice +and stick to it. +</p> +<ul> +<li> The mapping of physical source file multi-byte characters to the +execution character set. + +<p>The input character set can be specified using the +<samp>-finput-charset</samp> option, while the execution character set may +be controlled using the <samp>-fexec-charset</samp> and +<samp>-fwide-exec-charset</samp> options. +</p> +</li><li> Identifier characters. +<a name="Identifier-characters"></a> +<p>The C and C++ standards allow identifiers to be composed of ‘<samp>_</samp>’ +and the alphanumeric characters. C++ also allows universal character +names. C99 and later C standards permit both universal character +names and implementation-defined characters. In both C and C++ modes, +GCC accepts in identifiers exactly those extended characters that +correspond to universal character names permitted by the chosen +standard. +</p> +<p>GCC allows the ‘<samp>$</samp>’ character in identifiers as an extension for +most targets. This is true regardless of the <samp>std=</samp> switch, +since this extension cannot conflict with standards-conforming +programs. When preprocessing assembler, however, dollars are not +identifier characters by default. +</p> +<p>Currently the targets that by default do not permit ‘<samp>$</samp>’ are AVR, +IP2K, MMIX, MIPS Irix 3, ARM aout, and PowerPC targets for the AIX +operating system. +</p> +<p>You can override the default with <samp>-fdollars-in-identifiers</samp> or +<samp>-fno-dollars-in-identifiers</samp>. See <a href="Invocation.html#fdollars_002din_002didentifiers">fdollars-in-identifiers</a>. +</p> +</li><li> Non-empty sequences of whitespace characters. + +<p>In textual output, each whitespace sequence is collapsed to a single +space. For aesthetic reasons, the first token on each non-directive +line of output is preceded with sufficient spaces that it appears in the +same column as it did in the original source file. +</p> +</li><li> The numeric value of character constants in preprocessor expressions. + +<p>The preprocessor and compiler interpret character constants in the +same way; i.e. escape sequences such as ‘<samp>\a</samp>’ are given the +values they would have on the target machine. +</p> +<p>The compiler evaluates a multi-character character constant a character +at a time, shifting the previous value left by the number of bits per +target character, and then or-ing in the bit-pattern of the new +character truncated to the width of a target character. The final +bit-pattern is given type <code>int</code>, and is therefore signed, +regardless of whether single characters are signed or not. +If there are more +characters in the constant than would fit in the target <code>int</code> the +compiler issues a warning, and the excess leading characters are +ignored. +</p> +<p>For example, <code>'ab'</code> for a target with an 8-bit <code>char</code> would be +interpreted as ‘<samp>(int) ((unsigned char) 'a' * 256 + (unsigned char) 'b')</samp>’<!-- /@w -->, and <code>'\234a'</code> as ‘<samp>(int) ((unsigned char) '\234' * 256 + (unsigned char) 'a')</samp>’<!-- /@w -->. +</p> +</li><li> Source file inclusion. + +<p>For a discussion on how the preprocessor locates header files, +<a href="Include-Operation.html#Include-Operation">Include Operation</a>. +</p> +</li><li> Interpretation of the filename resulting from a macro-expanded +‘<samp>#include</samp>’ directive. + +<p>See <a href="Computed-Includes.html#Computed-Includes">Computed Includes</a>. +</p> +</li><li> Treatment of a ‘<samp>#pragma</samp>’ directive that after macro-expansion +results in a standard pragma. + +<p>No macro expansion occurs on any ‘<samp>#pragma</samp>’ directive line, so the +question does not arise. +</p> +<p>Note that GCC does not yet implement any of the standard +pragmas. +</p> +</li></ul> + +<hr> +<div class="header"> +<p> +Next: <a href="Implementation-limits.html#Implementation-limits" accesskey="n" rel="next">Implementation limits</a>, Up: <a href="Implementation-Details.html#Implementation-Details" accesskey="u" rel="up">Implementation Details</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Include-Operation.html b/share/doc/cpp/Include-Operation.html new file mode 100644 index 0000000..28a5897 --- /dev/null +++ b/share/doc/cpp/Include-Operation.html @@ -0,0 +1,148 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Include Operation</title> + +<meta name="description" content="The C Preprocessor: Include Operation"> +<meta name="keywords" content="The C Preprocessor: Include Operation"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Header-Files.html#Header-Files" rel="up" title="Header Files"> +<link href="Search-Path.html#Search-Path" rel="next" title="Search Path"> +<link href="Include-Syntax.html#Include-Syntax" rel="previous" title="Include Syntax"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Include-Operation"></a> +<div class="header"> +<p> +Next: <a href="Search-Path.html#Search-Path" accesskey="n" rel="next">Search Path</a>, Previous: <a href="Include-Syntax.html#Include-Syntax" accesskey="p" rel="previous">Include Syntax</a>, Up: <a href="Header-Files.html#Header-Files" accesskey="u" rel="up">Header Files</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Include-Operation-1"></a> +<h3 class="section">2.2 Include Operation</h3> + +<p>The ‘<samp>#include</samp>’ directive works by directing the C preprocessor to +scan the specified file as input before continuing with the rest of the +current file. The output from the preprocessor contains the output +already generated, followed by the output resulting from the included +file, followed by the output that comes from the text after the +‘<samp>#include</samp>’ directive. For example, if you have a header file +<samp>header.h</samp> as follows, +</p> +<div class="smallexample"> +<pre class="smallexample">char *test (void); +</pre></div> + +<p>and a main program called <samp>program.c</samp> that uses the header file, +like this, +</p> +<div class="smallexample"> +<pre class="smallexample">int x; +#include "header.h" + +int +main (void) +{ + puts (test ()); +} +</pre></div> + +<p>the compiler will see the same token stream as it would if +<samp>program.c</samp> read +</p> +<div class="smallexample"> +<pre class="smallexample">int x; +char *test (void); + +int +main (void) +{ + puts (test ()); +} +</pre></div> + +<p>Included files are not limited to declarations and macro definitions; +those are merely the typical uses. Any fragment of a C program can be +included from another file. The include file could even contain the +beginning of a statement that is concluded in the containing file, or +the end of a statement that was started in the including file. However, +an included file must consist of complete tokens. Comments and string +literals which have not been closed by the end of an included file are +invalid. For error recovery, they are considered to end at the end of +the file. +</p> +<p>To avoid confusion, it is best if header files contain only complete +syntactic units—function declarations or definitions, type +declarations, etc. +</p> +<p>The line following the ‘<samp>#include</samp>’ directive is always treated as a +separate line by the C preprocessor, even if the included file lacks a +final newline. +</p> +<hr> +<div class="header"> +<p> +Next: <a href="Search-Path.html#Search-Path" accesskey="n" rel="next">Search Path</a>, Previous: <a href="Include-Syntax.html#Include-Syntax" accesskey="p" rel="previous">Include Syntax</a>, Up: <a href="Header-Files.html#Header-Files" accesskey="u" rel="up">Header Files</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Include-Syntax.html b/share/doc/cpp/Include-Syntax.html new file mode 100644 index 0000000..43964a2 --- /dev/null +++ b/share/doc/cpp/Include-Syntax.html @@ -0,0 +1,120 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Include Syntax</title> + +<meta name="description" content="The C Preprocessor: Include Syntax"> +<meta name="keywords" content="The C Preprocessor: Include Syntax"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Header-Files.html#Header-Files" rel="up" title="Header Files"> +<link href="Include-Operation.html#Include-Operation" rel="next" title="Include Operation"> +<link href="Header-Files.html#Header-Files" rel="previous" title="Header Files"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Include-Syntax"></a> +<div class="header"> +<p> +Next: <a href="Include-Operation.html#Include-Operation" accesskey="n" rel="next">Include Operation</a>, Up: <a href="Header-Files.html#Header-Files" accesskey="u" rel="up">Header Files</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Include-Syntax-1"></a> +<h3 class="section">2.1 Include Syntax</h3> + +<a name="index-_0023include"></a> +<p>Both user and system header files are included using the preprocessing +directive ‘<samp>#include</samp>’. It has two variants: +</p> +<dl compact="compact"> +<dt><code>#include <<var>file</var>></code></dt> +<dd><p>This variant is used for system header files. It searches for a file +named <var>file</var> in a standard list of system directories. You can prepend +directories to this list with the <samp>-I</samp> option (see <a href="Invocation.html#Invocation">Invocation</a>). +</p> +</dd> +<dt><code>#include "<var>file</var>"</code></dt> +<dd><p>This variant is used for header files of your own program. It +searches for a file named <var>file</var> first in the directory containing +the current file, then in the quote directories and then the same +directories used for <code><<var>file</var>></code>. You can prepend directories +to the list of quote directories with the <samp>-iquote</samp> option. +</p></dd> +</dl> + +<p>The argument of ‘<samp>#include</samp>’, whether delimited with quote marks or +angle brackets, behaves like a string constant in that comments are not +recognized, and macro names are not expanded. Thus, <code>#include <x/*y><!-- /@w --></code> specifies inclusion of a system header file named <samp>x/*y</samp>. +</p> +<p>However, if backslashes occur within <var>file</var>, they are considered +ordinary text characters, not escape characters. None of the character +escape sequences appropriate to string constants in C are processed. +Thus, <code>#include "x\n\\y"<!-- /@w --></code> specifies a filename containing three +backslashes. (Some systems interpret ‘<samp>\</samp>’ as a pathname separator. +All of these also interpret ‘<samp>/</samp>’ the same way. It is most portable +to use only ‘<samp>/</samp>’.) +</p> +<p>It is an error if there is anything (other than comments) on the line +after the file name. +</p> + + + +</body> +</html> diff --git a/share/doc/cpp/Index-of-Directives.html b/share/doc/cpp/Index-of-Directives.html new file mode 100644 index 0000000..f7757aa --- /dev/null +++ b/share/doc/cpp/Index-of-Directives.html @@ -0,0 +1,122 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Index of Directives</title> + +<meta name="description" content="The C Preprocessor: Index of Directives"> +<meta name="keywords" content="The C Preprocessor: Index of Directives"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html#Top" rel="up" title="Top"> +<link href="Option-Index.html#Option-Index" rel="next" title="Option Index"> +<link href="GNU-Free-Documentation-License.html#GNU-Free-Documentation-License" rel="previous" title="GNU Free Documentation License"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Index-of-Directives"></a> +<div class="header"> +<p> +Next: <a href="Option-Index.html#Option-Index" accesskey="n" rel="next">Option Index</a>, Previous: <a href="GNU-Free-Documentation-License.html#GNU-Free-Documentation-License" accesskey="p" rel="previous">GNU Free Documentation License</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Index-of-Directives-1"></a> +<h2 class="unnumbered">Index of Directives</h2> +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Index-of-Directives_fn_symbol-1"><b>#</b></a> +</td></tr></table> +<table class="index-fn" border="0"> +<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Index-of-Directives_fn_symbol-1">#</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Obsolete-Features.html#index-_0023assert"><code>#assert</code></a>:</td><td> </td><td valign="top"><a href="Obsolete-Features.html#Obsolete-Features">Obsolete Features</a></td></tr> +<tr><td></td><td valign="top"><a href="Object_002dlike-Macros.html#index-_0023define"><code>#define</code></a>:</td><td> </td><td valign="top"><a href="Object_002dlike-Macros.html#Object_002dlike-Macros">Object-like Macros</a></td></tr> +<tr><td></td><td valign="top"><a href="Elif.html#index-_0023elif"><code>#elif</code></a>:</td><td> </td><td valign="top"><a href="Elif.html#Elif">Elif</a></td></tr> +<tr><td></td><td valign="top"><a href="Else.html#index-_0023else"><code>#else</code></a>:</td><td> </td><td valign="top"><a href="Else.html#Else">Else</a></td></tr> +<tr><td></td><td valign="top"><a href="Ifdef.html#index-_0023endif"><code>#endif</code></a>:</td><td> </td><td valign="top"><a href="Ifdef.html#Ifdef">Ifdef</a></td></tr> +<tr><td></td><td valign="top"><a href="Diagnostics.html#index-_0023error"><code>#error</code></a>:</td><td> </td><td valign="top"><a href="Diagnostics.html#Diagnostics">Diagnostics</a></td></tr> +<tr><td></td><td valign="top"><a href="Other-Directives.html#index-_0023ident"><code>#ident</code></a>:</td><td> </td><td valign="top"><a href="Other-Directives.html#Other-Directives">Other Directives</a></td></tr> +<tr><td></td><td valign="top"><a href="Conditional-Syntax.html#index-_0023if"><code>#if</code></a>:</td><td> </td><td valign="top"><a href="Conditional-Syntax.html#Conditional-Syntax">Conditional Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="Ifdef.html#index-_0023ifdef"><code>#ifdef</code></a>:</td><td> </td><td valign="top"><a href="Ifdef.html#Ifdef">Ifdef</a></td></tr> +<tr><td></td><td valign="top"><a href="Ifdef.html#index-_0023ifndef"><code>#ifndef</code></a>:</td><td> </td><td valign="top"><a href="Ifdef.html#Ifdef">Ifdef</a></td></tr> +<tr><td></td><td valign="top"><a href="Alternatives-to-Wrapper-_0023ifndef.html#index-_0023import"><code>#import</code></a>:</td><td> </td><td valign="top"><a href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef">Alternatives to Wrapper #ifndef</a></td></tr> +<tr><td></td><td valign="top"><a href="Include-Syntax.html#index-_0023include"><code>#include</code></a>:</td><td> </td><td valign="top"><a href="Include-Syntax.html#Include-Syntax">Include Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="Wrapper-Headers.html#index-_0023include_005fnext"><code>#include_next</code></a>:</td><td> </td><td valign="top"><a href="Wrapper-Headers.html#Wrapper-Headers">Wrapper Headers</a></td></tr> +<tr><td></td><td valign="top"><a href="Line-Control.html#index-_0023line"><code>#line</code></a>:</td><td> </td><td valign="top"><a href="Line-Control.html#Line-Control">Line Control</a></td></tr> +<tr><td></td><td valign="top"><a href="Pragmas.html#index-_0023pragma-endregion-_007btokens_007d_002e_002e_002e"><code>#pragma endregion {tokens}...</code></a>:</td><td> </td><td valign="top"><a href="Pragmas.html#Pragmas">Pragmas</a></td></tr> +<tr><td></td><td valign="top"><a href="Pragmas.html#index-_0023pragma-GCC-dependency"><code>#pragma GCC dependency</code></a>:</td><td> </td><td valign="top"><a href="Pragmas.html#Pragmas">Pragmas</a></td></tr> +<tr><td></td><td valign="top"><a href="Pragmas.html#index-_0023pragma-GCC-error"><code>#pragma GCC error</code></a>:</td><td> </td><td valign="top"><a href="Pragmas.html#Pragmas">Pragmas</a></td></tr> +<tr><td></td><td valign="top"><a href="Pragmas.html#index-_0023pragma-GCC-poison"><code>#pragma GCC poison</code></a>:</td><td> </td><td valign="top"><a href="Pragmas.html#Pragmas">Pragmas</a></td></tr> +<tr><td></td><td valign="top"><a href="System-Headers.html#index-_0023pragma-GCC-system_005fheader"><code>#pragma GCC system_header</code></a>:</td><td> </td><td valign="top"><a href="System-Headers.html#System-Headers">System Headers</a></td></tr> +<tr><td></td><td valign="top"><a href="Pragmas.html#index-_0023pragma-GCC-system_005fheader-1"><code>#pragma GCC system_header</code></a>:</td><td> </td><td valign="top"><a href="Pragmas.html#Pragmas">Pragmas</a></td></tr> +<tr><td></td><td valign="top"><a href="Pragmas.html#index-_0023pragma-GCC-warning"><code>#pragma GCC warning</code></a>:</td><td> </td><td valign="top"><a href="Pragmas.html#Pragmas">Pragmas</a></td></tr> +<tr><td></td><td valign="top"><a href="Pragmas.html#index-_0023pragma-once"><code>#pragma once</code></a>:</td><td> </td><td valign="top"><a href="Pragmas.html#Pragmas">Pragmas</a></td></tr> +<tr><td></td><td valign="top"><a href="Pragmas.html#index-_0023pragma-region-_007btokens_007d_002e_002e_002e"><code>#pragma region {tokens}...</code></a>:</td><td> </td><td valign="top"><a href="Pragmas.html#Pragmas">Pragmas</a></td></tr> +<tr><td></td><td valign="top"><a href="Other-Directives.html#index-_0023sccs"><code>#sccs</code></a>:</td><td> </td><td valign="top"><a href="Other-Directives.html#Other-Directives">Other Directives</a></td></tr> +<tr><td></td><td valign="top"><a href="Obsolete-Features.html#index-_0023unassert"><code>#unassert</code></a>:</td><td> </td><td valign="top"><a href="Obsolete-Features.html#Obsolete-Features">Obsolete Features</a></td></tr> +<tr><td></td><td valign="top"><a href="Undefining-and-Redefining-Macros.html#index-_0023undef"><code>#undef</code></a>:</td><td> </td><td valign="top"><a href="Undefining-and-Redefining-Macros.html#Undefining-and-Redefining-Macros">Undefining and Redefining Macros</a></td></tr> +<tr><td></td><td valign="top"><a href="Diagnostics.html#index-_0023warning"><code>#warning</code></a>:</td><td> </td><td valign="top"><a href="Diagnostics.html#Diagnostics">Diagnostics</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +</table> +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Index-of-Directives_fn_symbol-1"><b>#</b></a> +</td></tr></table> + + + + +</body> +</html> diff --git a/share/doc/cpp/Initial-processing.html b/share/doc/cpp/Initial-processing.html new file mode 100644 index 0000000..b69d1d7 --- /dev/null +++ b/share/doc/cpp/Initial-processing.html @@ -0,0 +1,243 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Initial processing</title> + +<meta name="description" content="The C Preprocessor: Initial processing"> +<meta name="keywords" content="The C Preprocessor: Initial processing"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Overview.html#Overview" rel="up" title="Overview"> +<link href="Tokenization.html#Tokenization" rel="next" title="Tokenization"> +<link href="Character-sets.html#Character-sets" rel="previous" title="Character sets"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Initial-processing"></a> +<div class="header"> +<p> +Next: <a href="Tokenization.html#Tokenization" accesskey="n" rel="next">Tokenization</a>, Previous: <a href="Character-sets.html#Character-sets" accesskey="p" rel="previous">Character sets</a>, Up: <a href="Overview.html#Overview" accesskey="u" rel="up">Overview</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Initial-processing-1"></a> +<h3 class="section">1.2 Initial processing</h3> + +<p>The preprocessor performs a series of textual transformations on its +input. These happen before all other processing. Conceptually, they +happen in a rigid order, and the entire file is run through each +transformation before the next one begins. CPP actually does them +all at once, for performance reasons. These transformations correspond +roughly to the first three “phases of translation” described in the C +standard. +</p> +<ol> +<li> <a name="index-line-endings"></a> +The input file is read into memory and broken into lines. + +<p>Different systems use different conventions to indicate the end of a +line. GCC accepts the ASCII control sequences <kbd>LF</kbd>, <kbd>CR LF<!-- /@w --></kbd> and <kbd>CR</kbd> as end-of-line markers. These are the canonical +sequences used by Unix, DOS and VMS, and the classic Mac OS (before +OSX) respectively. You may therefore safely copy source code written +on any of those systems to a different one and use it without +conversion. (GCC may lose track of the current line number if a file +doesn’t consistently use one convention, as sometimes happens when it +is edited on computers with different conventions that share a network +file system.) +</p> +<p>If the last line of any input file lacks an end-of-line marker, the end +of the file is considered to implicitly supply one. The C standard says +that this condition provokes undefined behavior, so GCC will emit a +warning message. +</p> +</li><li> <a name="index-trigraphs"></a> +<a name="trigraphs"></a>If trigraphs are enabled, they are replaced by their +corresponding single characters. By default GCC ignores trigraphs, +but if you request a strictly conforming mode with the <samp>-std</samp> +option, or you specify the <samp>-trigraphs</samp> option, then it +converts them. + +<p>These are nine three-character sequences, all starting with ‘<samp>??</samp>’, +that are defined by ISO C to stand for single characters. They permit +obsolete systems that lack some of C’s punctuation to use C. For +example, ‘<samp>??/</samp>’ stands for ‘<samp>\</samp>’, so <tt>'??/n'</tt> is a character +constant for a newline. +</p> +<p>Trigraphs are not popular and many compilers implement them +incorrectly. Portable code should not rely on trigraphs being either +converted or ignored. With <samp>-Wtrigraphs</samp> GCC will warn you +when a trigraph may change the meaning of your program if it were +converted. See <a href="Invocation.html#Wtrigraphs">Wtrigraphs</a>. +</p> +<p>In a string constant, you can prevent a sequence of question marks +from being confused with a trigraph by inserting a backslash between +the question marks, or by separating the string literal at the +trigraph and making use of string literal concatenation. <tt>"(??\?)"</tt> +is the string ‘<samp>(???)</samp>’, not ‘<samp>(?]</samp>’. Traditional C compilers +do not recognize these idioms. +</p> +<p>The nine trigraphs and their replacements are +</p> +<div class="smallexample"> +<pre class="smallexample">Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??- +Replacement: [ ] { } # \ ^ | ~ +</pre></div> + +</li><li> <a name="index-continued-lines"></a> +<a name="index-backslash_002dnewline"></a> +Continued lines are merged into one long line. + +<p>A continued line is a line which ends with a backslash, ‘<samp>\</samp>’. The +backslash is removed and the following line is joined with the current +one. No space is inserted, so you may split a line anywhere, even in +the middle of a word. (It is generally more readable to split lines +only at white space.) +</p> +<p>The trailing backslash on a continued line is commonly referred to as a +<em>backslash-newline</em>. +</p> +<p>If there is white space between a backslash and the end of a line, that +is still a continued line. However, as this is usually the result of an +editing mistake, and many compilers will not accept it as a continued +line, GCC will warn you about it. +</p> +</li><li> <a name="index-comments"></a> +<a name="index-line-comments"></a> +<a name="index-block-comments"></a> +All comments are replaced with single spaces. + +<p>There are two kinds of comments. <em>Block comments</em> begin with +‘<samp>/*</samp>’ and continue until the next ‘<samp>*/</samp>’. Block comments do not +nest: +</p> +<div class="smallexample"> +<pre class="smallexample">/* <span class="roman">this is</span> /* <span class="roman">one comment</span> */ <span class="roman">text outside comment</span> +</pre></div> + +<p><em>Line comments</em> begin with ‘<samp>//</samp>’ and continue to the end of the +current line. Line comments do not nest either, but it does not matter, +because they would end in the same place anyway. +</p> +<div class="smallexample"> +<pre class="smallexample">// <span class="roman">this is</span> // <span class="roman">one comment</span> +<span class="roman">text outside comment</span> +</pre></div> +</li></ol> + +<p>It is safe to put line comments inside block comments, or vice versa. +</p> +<div class="smallexample"> +<pre class="smallexample">/* <span class="roman">block comment</span> + // <span class="roman">contains line comment</span> + <span class="roman">yet more comment</span> + */ <span class="roman">outside comment</span> + +// <span class="roman">line comment</span> /* <span class="roman">contains block comment</span> */ +</pre></div> + +<p>But beware of commenting out one end of a block comment with a line +comment. +</p> +<div class="smallexample"> +<pre class="smallexample"> // <span class="roman">l.c.</span> /* <span class="roman">block comment begins</span> + <span class="roman">oops! this isn’t a comment anymore</span> */ +</pre></div> + +<p>Comments are not recognized within string literals. +<tt>"/* blah */"<!-- /@w --></tt> is the string constant ‘<samp>/* blah */<!-- /@w --></samp>’, not +an empty string. +</p> +<p>Line comments are not in the 1989 edition of the C standard, but they +are recognized by GCC as an extension. In C++ and in the 1999 edition +of the C standard, they are an official part of the language. +</p> +<p>Since these transformations happen before all other processing, you can +split a line mechanically with backslash-newline anywhere. You can +comment out the end of a line. You can continue a line comment onto the +next line with backslash-newline. You can even split ‘<samp>/*</samp>’, +‘<samp>*/</samp>’, and ‘<samp>//</samp>’ onto multiple lines with backslash-newline. +For example: +</p> +<div class="smallexample"> +<pre class="smallexample">/\ +* +*/ # /* +*/ defi\ +ne FO\ +O 10\ +20 +</pre></div> + +<p>is equivalent to <code>#define FOO 1020<!-- /@w --></code>. All these tricks are +extremely confusing and should not be used in code intended to be +readable. +</p> +<p>There is no way to prevent a backslash at the end of a line from being +interpreted as a backslash-newline. This cannot affect any correct +program, however. +</p> +<hr> +<div class="header"> +<p> +Next: <a href="Tokenization.html#Tokenization" accesskey="n" rel="next">Tokenization</a>, Previous: <a href="Character-sets.html#Character-sets" accesskey="p" rel="previous">Character sets</a>, Up: <a href="Overview.html#Overview" accesskey="u" rel="up">Overview</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Invocation.html b/share/doc/cpp/Invocation.html new file mode 100644 index 0000000..a1acc15 --- /dev/null +++ b/share/doc/cpp/Invocation.html @@ -0,0 +1,889 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Invocation</title> + +<meta name="description" content="The C Preprocessor: Invocation"> +<meta name="keywords" content="The C Preprocessor: Invocation"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html#Top" rel="up" title="Top"> +<link href="Environment-Variables.html#Environment-Variables" rel="next" title="Environment Variables"> +<link href="Obsolete-Features.html#Obsolete-Features" rel="previous" title="Obsolete Features"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Invocation"></a> +<div class="header"> +<p> +Next: <a href="Environment-Variables.html#Environment-Variables" accesskey="n" rel="next">Environment Variables</a>, Previous: <a href="Implementation-Details.html#Implementation-Details" accesskey="p" rel="previous">Implementation Details</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Invocation-1"></a> +<h2 class="chapter">12 Invocation</h2> +<a name="index-invocation"></a> +<a name="index-command-line"></a> + +<p>Most often when you use the C preprocessor you do not have to invoke it +explicitly: the C compiler does so automatically. However, the +preprocessor is sometimes useful on its own. You can invoke the +preprocessor either with the <code>cpp</code> command, or via <code>gcc -E</code>. +In GCC, the preprocessor is actually integrated with the compiler +rather than a separate program, and both of these commands invoke +GCC and tell it to stop after the preprocessing phase. +</p> +<p>The <code>cpp</code> options listed here are also accepted by +<code>gcc</code> and have the same meaning. Likewise the <code>cpp</code> +command accepts all the usual <code>gcc</code> driver options, although those +pertaining to compilation phases after preprocessing are ignored. +</p> +<p>Only options specific to preprocessing behavior are documented here. +Refer to the GCC manual for full documentation of other driver options. +</p> + +<p>The <code>cpp</code> command expects two file names as arguments, <var>infile</var> and +<var>outfile</var>. The preprocessor reads <var>infile</var> together with any +other files it specifies with ‘<samp>#include</samp>’. All the output generated +by the combined input files is written in <var>outfile</var>. +</p> +<p>Either <var>infile</var> or <var>outfile</var> may be <samp>-</samp>, which as +<var>infile</var> means to read from standard input and as <var>outfile</var> +means to write to standard output. If either file is omitted, it +means the same as if <samp>-</samp> had been specified for that file. +You can also use the <samp>-o <var>outfile</var></samp> option to specify the +output file. +</p> +<p>Unless otherwise noted, or the option ends in ‘<samp>=</samp>’, all options +which take an argument may have that argument appear either immediately +after the option, or with a space between option and argument: +<samp>-Ifoo</samp> and <samp>-I foo</samp> have the same effect. +</p> +<a name="index-grouping-options"></a> +<a name="index-options_002c-grouping"></a> +<p>Many options have multi-letter names; therefore multiple single-letter +options may <em>not</em> be grouped: <samp>-dM</samp> is very different from +‘<samp><span class="nolinebreak">-d</span> <span class="nolinebreak">-M</span></samp>’<!-- /@w -->. +</p> +<a name="index-options"></a> + +<dl compact="compact"> +<dd> + + +<a name="index-D"></a> +</dd> +<dt><code>-D <var>name</var></code></dt> +<dd><p>Predefine <var>name</var> as a macro, with definition <code>1</code>. +</p> +</dd> +<dt><code>-D <var>name</var>=<var>definition</var></code></dt> +<dd><p>The contents of <var>definition</var> are tokenized and processed as if +they appeared during translation phase three in a ‘<samp>#define</samp>’ +directive. In particular, the definition is truncated by +embedded newline characters. +</p> +<p>If you are invoking the preprocessor from a shell or shell-like +program you may need to use the shell’s quoting syntax to protect +characters such as spaces that have a meaning in the shell syntax. +</p> +<p>If you wish to define a function-like macro on the command line, write +its argument list with surrounding parentheses before the equals sign +(if any). Parentheses are meaningful to most shells, so you should +quote the option. With <code>sh</code> and <code>csh</code>, +<samp>-D'<var>name</var>(<var>args…</var>)=<var>definition</var>'</samp> works. +</p> +<p><samp>-D</samp> and <samp>-U</samp> options are processed in the order they +are given on the command line. All <samp>-imacros <var>file</var></samp> and +<samp>-include <var>file</var></samp> options are processed after all +<samp>-D</samp> and <samp>-U</samp> options. +</p> +<a name="index-U"></a> +</dd> +<dt><code>-U <var>name</var></code></dt> +<dd><p>Cancel any previous definition of <var>name</var>, either built in or +provided with a <samp>-D</samp> option. +</p> +<a name="index-include"></a> +</dd> +<dt><code>-include <var>file</var></code></dt> +<dd><p>Process <var>file</var> as if <code>#include "file"</code> appeared as the first +line of the primary source file. However, the first directory searched +for <var>file</var> is the preprocessor’s working directory <em>instead of</em> +the directory containing the main source file. If not found there, it +is searched for in the remainder of the <code>#include "…"</code> search +chain as normal. +</p> +<p>If multiple <samp>-include</samp> options are given, the files are included +in the order they appear on the command line. +</p> +<a name="index-imacros"></a> +</dd> +<dt><code>-imacros <var>file</var></code></dt> +<dd><p>Exactly like <samp>-include</samp>, except that any output produced by +scanning <var>file</var> is thrown away. Macros it defines remain defined. +This allows you to acquire all the macros from a header without also +processing its declarations. +</p> +<p>All files specified by <samp>-imacros</samp> are processed before all files +specified by <samp>-include</samp>. +</p> +<a name="index-undef"></a> +</dd> +<dt><code>-undef</code></dt> +<dd><p>Do not predefine any system-specific or GCC-specific macros. The +standard predefined macros remain defined. +See <a href="Standard-Predefined-Macros.html#Standard-Predefined-Macros">Standard Predefined Macros</a>. +</p> +<a name="index-pthread"></a> +</dd> +<dt><code>-pthread</code></dt> +<dd><p>Define additional macros required for using the POSIX threads library. +You should use this option consistently for both compilation and linking. +This option is supported on GNU/Linux targets, most other Unix derivatives, +and also on x86 Cygwin and MinGW targets. +</p> +<a name="index-M"></a> +<a name="index-make"></a> +<a name="index-dependencies_002c-make"></a> +</dd> +<dt><code>-M</code></dt> +<dd><p>Instead of outputting the result of preprocessing, output a rule +suitable for <code>make</code> describing the dependencies of the main +source file. The preprocessor outputs one <code>make</code> rule containing +the object file name for that source file, a colon, and the names of all +the included files, including those coming from <samp>-include</samp> or +<samp>-imacros</samp> command-line options. +</p> +<p>Unless specified explicitly (with <samp>-MT</samp> or <samp>-MQ</samp>), the +object file name consists of the name of the source file with any +suffix replaced with object file suffix and with any leading directory +parts removed. If there are many included files then the rule is +split into several lines using ‘<samp>\</samp>’-newline. The rule has no +commands. +</p> +<p>This option does not suppress the preprocessor’s debug output, such as +<samp>-dM</samp>. To avoid mixing such debug output with the dependency +rules you should explicitly specify the dependency output file with +<samp>-MF</samp>, or use an environment variable like +<code>DEPENDENCIES_OUTPUT</code> (see <a href="Environment-Variables.html#Environment-Variables">Environment Variables</a>). Debug output +is still sent to the regular output stream as normal. +</p> +<p>Passing <samp>-M</samp> to the driver implies <samp>-E</samp>, and suppresses +warnings with an implicit <samp>-w</samp>. +</p> +<a name="index-MM"></a> +</dd> +<dt><code>-MM</code></dt> +<dd><p>Like <samp>-M</samp> but do not mention header files that are found in +system header directories, nor header files that are included, +directly or indirectly, from such a header. +</p> +<p>This implies that the choice of angle brackets or double quotes in an +‘<samp>#include</samp>’ directive does not in itself determine whether that +header appears in <samp>-MM</samp> dependency output. +</p> +<a name="dashMF"></a><a name="index-MF"></a> +</dd> +<dt><code>-MF <var>file</var></code></dt> +<dd><p>When used with <samp>-M</samp> or <samp>-MM</samp>, specifies a +file to write the dependencies to. If no <samp>-MF</samp> switch is given +the preprocessor sends the rules to the same place it would send +preprocessed output. +</p> +<p>When used with the driver options <samp>-MD</samp> or <samp>-MMD</samp>, +<samp>-MF</samp> overrides the default dependency output file. +</p> +<p>If <var>file</var> is <samp>-</samp>, then the dependencies are written to <samp>stdout</samp>. +</p> +<a name="index-MG"></a> +</dd> +<dt><code>-MG</code></dt> +<dd><p>In conjunction with an option such as <samp>-M</samp> requesting +dependency generation, <samp>-MG</samp> assumes missing header files are +generated files and adds them to the dependency list without raising +an error. The dependency filename is taken directly from the +<code>#include</code> directive without prepending any path. <samp>-MG</samp> +also suppresses preprocessed output, as a missing header file renders +this useless. +</p> +<p>This feature is used in automatic updating of makefiles. +</p> +<a name="index-Mno_002dmodules"></a> +</dd> +<dt><code>-Mno-modules</code></dt> +<dd><p>Disable dependency generation for compiled module interfaces. +</p> +<a name="index-MP"></a> +</dd> +<dt><code>-MP</code></dt> +<dd><p>This option instructs CPP to add a phony target for each dependency +other than the main file, causing each to depend on nothing. These +dummy rules work around errors <code>make</code> gives if you remove header +files without updating the <samp>Makefile</samp> to match. +</p> +<p>This is typical output: +</p> +<div class="smallexample"> +<pre class="smallexample">test.o: test.c test.h + +test.h: +</pre></div> + +<a name="index-MT"></a> +</dd> +<dt><code>-MT <var>target</var></code></dt> +<dd> +<p>Change the target of the rule emitted by dependency generation. By +default CPP takes the name of the main input file, deletes any +directory components and any file suffix such as ‘<samp>.c</samp>’, and +appends the platform’s usual object suffix. The result is the target. +</p> +<p>An <samp>-MT</samp> option sets the target to be exactly the string you +specify. If you want multiple targets, you can specify them as a single +argument to <samp>-MT</samp>, or use multiple <samp>-MT</samp> options. +</p> +<p>For example, <samp><span class="nolinebreak">-MT</span> '$(objpfx)foo.o'<!-- /@w --></samp> might give +</p> +<div class="smallexample"> +<pre class="smallexample">$(objpfx)foo.o: foo.c +</pre></div> + +<a name="index-MQ"></a> +</dd> +<dt><code>-MQ <var>target</var></code></dt> +<dd> +<p>Same as <samp>-MT</samp>, but it quotes any characters which are special to +Make. <samp><span class="nolinebreak">-MQ</span> '$(objpfx)foo.o'<!-- /@w --></samp> gives +</p> +<div class="smallexample"> +<pre class="smallexample">$$(objpfx)foo.o: foo.c +</pre></div> + +<p>The default target is automatically quoted, as if it were given with +<samp>-MQ</samp>. +</p> +<a name="index-MD"></a> +</dd> +<dt><code>-MD</code></dt> +<dd><p><samp>-MD</samp> is equivalent to <samp>-M -MF <var>file</var></samp>, except that +<samp>-E</samp> is not implied. The driver determines <var>file</var> based on +whether an <samp>-o</samp> option is given. If it is, the driver uses its +argument but with a suffix of <samp>.d</samp>, otherwise it takes the name +of the input file, removes any directory components and suffix, and +applies a <samp>.d</samp> suffix. +</p> +<p>If <samp>-MD</samp> is used in conjunction with <samp>-E</samp>, any +<samp>-o</samp> switch is understood to specify the dependency output file +(see <a href="#dashMF">-MF</a>), but if used without <samp>-E</samp>, each <samp>-o</samp> +is understood to specify a target object file. +</p> +<p>Since <samp>-E</samp> is not implied, <samp>-MD</samp> can be used to generate +a dependency output file as a side effect of the compilation process. +</p> +<a name="index-MMD"></a> +</dd> +<dt><code>-MMD</code></dt> +<dd><p>Like <samp>-MD</samp> except mention only user header files, not system +header files. +</p> +<a name="index-fpreprocessed"></a> +</dd> +<dt><code>-fpreprocessed</code></dt> +<dd><p>Indicate to the preprocessor that the input file has already been +preprocessed. This suppresses things like macro expansion, trigraph +conversion, escaped newline splicing, and processing of most directives. +The preprocessor still recognizes and removes comments, so that you can +pass a file preprocessed with <samp>-C</samp> to the compiler without +problems. In this mode the integrated preprocessor is little more than +a tokenizer for the front ends. +</p> +<p><samp>-fpreprocessed</samp> is implicit if the input file has one of the +extensions ‘<samp>.i</samp>’, ‘<samp>.ii</samp>’ or ‘<samp>.mi</samp>’. These are the +extensions that GCC uses for preprocessed files created by +<samp>-save-temps</samp>. +</p> +<a name="index-fdirectives_002donly"></a> +</dd> +<dt><code>-fdirectives-only</code></dt> +<dd><p>When preprocessing, handle directives, but do not expand macros. +</p> +<p>The option’s behavior depends on the <samp>-E</samp> and <samp>-fpreprocessed</samp> +options. +</p> +<p>With <samp>-E</samp>, preprocessing is limited to the handling of directives +such as <code>#define</code>, <code>#ifdef</code>, and <code>#error</code>. Other +preprocessor operations, such as macro expansion and trigraph +conversion are not performed. In addition, the <samp>-dD</samp> option is +implicitly enabled. +</p> +<p>With <samp>-fpreprocessed</samp>, predefinition of command line and most +builtin macros is disabled. Macros such as <code>__LINE__</code>, which are +contextually dependent, are handled normally. This enables compilation of +files previously preprocessed with <code>-E -fdirectives-only</code>. +</p> +<p>With both <samp>-E</samp> and <samp>-fpreprocessed</samp>, the rules for +<samp>-fpreprocessed</samp> take precedence. This enables full preprocessing of +files previously preprocessed with <code>-E -fdirectives-only</code>. +</p> +<a name="index-fdollars_002din_002didentifiers"></a> +</dd> +<dt><code>-fdollars-in-identifiers</code></dt> +<dd><a name="fdollars_002din_002didentifiers"></a><p>Accept ‘<samp>$</samp>’ in identifiers. +See <a href="Implementation_002ddefined-behavior.html#Identifier-characters">Identifier characters</a>. +</p> +<a name="index-fextended_002didentifiers"></a> +</dd> +<dt><code>-fextended-identifiers</code></dt> +<dd><p>Accept universal character names and extended characters in +identifiers. This option is enabled by default for C99 (and later C +standard versions) and C++. +</p> +<a name="index-fno_002dcanonical_002dsystem_002dheaders"></a> +</dd> +<dt><code>-fno-canonical-system-headers</code></dt> +<dd><p>When preprocessing, do not shorten system header paths with canonicalization. +</p> +<a name="index-fmax_002dinclude_002ddepth"></a> +</dd> +<dt><code>-fmax-include-depth=<var>depth</var></code></dt> +<dd><p>Set the maximum depth of the nested #include. The default is 200. +</p> +<a name="index-ftabstop"></a> +</dd> +<dt><code>-ftabstop=<var>width</var></code></dt> +<dd><p>Set the distance between tab stops. This helps the preprocessor report +correct column numbers in warnings or errors, even if tabs appear on the +line. If the value is less than 1 or greater than 100, the option is +ignored. The default is 8. +</p> +<a name="index-ftrack_002dmacro_002dexpansion"></a> +</dd> +<dt><code>-ftrack-macro-expansion<span class="roman">[</span>=<var>level</var><span class="roman">]</span></code></dt> +<dd><p>Track locations of tokens across macro expansions. This allows the +compiler to emit diagnostic about the current macro expansion stack +when a compilation error occurs in a macro expansion. Using this +option makes the preprocessor and the compiler consume more +memory. The <var>level</var> parameter can be used to choose the level of +precision of token location tracking thus decreasing the memory +consumption if necessary. Value ‘<samp>0</samp>’ of <var>level</var> de-activates +this option. Value ‘<samp>1</samp>’ tracks tokens locations in a +degraded mode for the sake of minimal memory overhead. In this mode +all tokens resulting from the expansion of an argument of a +function-like macro have the same location. Value ‘<samp>2</samp>’ tracks +tokens locations completely. This value is the most memory hungry. +When this option is given no argument, the default parameter value is +‘<samp>2</samp>’. +</p> +<p>Note that <code>-ftrack-macro-expansion=2</code> is activated by default. +</p> +<a name="index-fmacro_002dprefix_002dmap"></a> +</dd> +<dt><code>-fmacro-prefix-map=<var>old</var>=<var>new</var></code></dt> +<dd><p>When preprocessing files residing in directory <samp><var>old</var></samp>, +expand the <code>__FILE__</code> and <code>__BASE_FILE__</code> macros as if the +files resided in directory <samp><var>new</var></samp> instead. This can be used +to change an absolute path to a relative path by using <samp>.</samp> for +<var>new</var> which can result in more reproducible builds that are +location independent. This option also affects +<code>__builtin_FILE()</code> during compilation. See also +<samp>-ffile-prefix-map</samp> and <samp>-fcanon-prefix-map</samp>. +</p> +<a name="index-fexec_002dcharset"></a> +<a name="index-character-set_002c-execution"></a> +</dd> +<dt><code>-fexec-charset=<var>charset</var></code></dt> +<dd><p>Set the execution character set, used for string and character +constants. The default is UTF-8. <var>charset</var> can be any encoding +supported by the system’s <code>iconv</code> library routine. +</p> +<a name="index-fwide_002dexec_002dcharset"></a> +<a name="index-character-set_002c-wide-execution"></a> +</dd> +<dt><code>-fwide-exec-charset=<var>charset</var></code></dt> +<dd><p>Set the wide execution character set, used for wide string and +character constants. The default is one of UTF-32BE, UTF-32LE, UTF-16BE, +or UTF-16LE, whichever corresponds to the width of <code>wchar_t</code> and the +big-endian or little-endian byte order being used for code generation. As +with <samp>-fexec-charset</samp>, <var>charset</var> can be any encoding supported +by the system’s <code>iconv</code> library routine; however, you will have +problems with encodings that do not fit exactly in <code>wchar_t</code>. +</p> +<a name="index-finput_002dcharset"></a> +<a name="index-character-set_002c-input"></a> +</dd> +<dt><code>-finput-charset=<var>charset</var></code></dt> +<dd><p>Set the input character set, used for translation from the character +set of the input file to the source character set used by GCC. If the +locale does not specify, or GCC cannot get this information from the +locale, the default is UTF-8. This can be overridden by either the locale +or this command-line option. Currently the command-line option takes +precedence if there’s a conflict. <var>charset</var> can be any encoding +supported by the system’s <code>iconv</code> library routine. +</p> + +<a name="index-fworking_002ddirectory"></a> +<a name="index-fno_002dworking_002ddirectory"></a> +</dd> +<dt><code>-fworking-directory</code></dt> +<dd><p>Enable generation of linemarkers in the preprocessor output that +let the compiler know the current working directory at the time of +preprocessing. When this option is enabled, the preprocessor +emits, after the initial linemarker, a second linemarker with the +current working directory followed by two slashes. GCC uses this +directory, when it’s present in the preprocessed input, as the +directory emitted as the current working directory in some debugging +information formats. This option is implicitly enabled if debugging +information is enabled, but this can be inhibited with the negated +form <samp>-fno-working-directory</samp>. If the <samp>-P</samp> flag is +present in the command line, this option has no effect, since no +<code>#line</code> directives are emitted whatsoever. +</p> +<a name="index-A"></a> +</dd> +<dt><code>-A <var>predicate</var>=<var>answer</var></code></dt> +<dd><p>Make an assertion with the predicate <var>predicate</var> and answer +<var>answer</var>. This form is preferred to the older form <samp>-A +<var>predicate</var>(<var>answer</var>)</samp>, which is still supported, because +it does not use shell special characters. +See <a href="Obsolete-Features.html#Obsolete-Features">Obsolete Features</a>. +</p> +</dd> +<dt><code>-A -<var>predicate</var>=<var>answer</var></code></dt> +<dd><p>Cancel an assertion with the predicate <var>predicate</var> and answer +<var>answer</var>. +</p> +<a name="index-C"></a> +</dd> +<dt><code>-C</code></dt> +<dd><p>Do not discard comments. All comments are passed through to the output +file, except for comments in processed directives, which are deleted +along with the directive. +</p> +<p>You should be prepared for side effects when using <samp>-C</samp>; it +causes the preprocessor to treat comments as tokens in their own right. +For example, comments appearing at the start of what would be a +directive line have the effect of turning that line into an ordinary +source line, since the first token on the line is no longer a ‘<samp>#</samp>’. +</p> +<a name="index-CC"></a> +</dd> +<dt><code>-CC</code></dt> +<dd><p>Do not discard comments, including during macro expansion. This is +like <samp>-C</samp>, except that comments contained within macros are +also passed through to the output file where the macro is expanded. +</p> +<p>In addition to the side effects of the <samp>-C</samp> option, the +<samp>-CC</samp> option causes all C++-style comments inside a macro +to be converted to C-style comments. This is to prevent later use +of that macro from inadvertently commenting out the remainder of +the source line. +</p> +<p>The <samp>-CC</samp> option is generally used to support lint comments. +</p> +<a name="index-P"></a> +</dd> +<dt><code>-P</code></dt> +<dd><p>Inhibit generation of linemarkers in the output from the preprocessor. +This might be useful when running the preprocessor on something that is +not C code, and will be sent to a program which might be confused by the +linemarkers. +See <a href="Preprocessor-Output.html#Preprocessor-Output">Preprocessor Output</a>. +</p> +<a name="index-traditional-C-language"></a> +<a name="index-C-language_002c-traditional"></a> +<a name="index-traditional_002dcpp"></a> +<a name="index-traditional"></a> +</dd> +<dt><code>-traditional</code></dt> +<dt><code>-traditional-cpp</code></dt> +<dd> +<p>Try to imitate the behavior of pre-standard C preprocessors, as +opposed to ISO C preprocessors. +See <a href="Traditional-Mode.html#Traditional-Mode">Traditional Mode</a>. +</p> +<p>Note that GCC does not otherwise attempt to emulate a pre-standard +C compiler, and these options are only supported with the <samp>-E</samp> +switch, or when invoking CPP explicitly. +</p> +<a name="index-trigraphs-1"></a> +</dd> +<dt><code>-trigraphs</code></dt> +<dd><p>Support ISO C trigraphs. +These are three-character sequences, all starting with ‘<samp>??</samp>’, that +are defined by ISO C to stand for single characters. For example, +‘<samp>??/</samp>’ stands for ‘<samp>\</samp>’, so ‘<samp>'??/n'</samp>’ is a character +constant for a newline. +See <a href="Initial-processing.html#Initial-processing">Initial processing</a>. +</p> + +<p>By default, GCC ignores trigraphs, but in +standard-conforming modes it converts them. See the <samp>-std</samp> and +<samp>-ansi</samp> options. +</p> +<a name="index-remap"></a> +</dd> +<dt><code>-remap</code></dt> +<dd><p>Enable special code to work around file systems which only permit very +short file names, such as MS-DOS. +</p> +<a name="index-H"></a> +</dd> +<dt><code>-H</code></dt> +<dd><p>Print the name of each header file used, in addition to other normal +activities. Each name is indented to show how deep in the +‘<samp>#include</samp>’ stack it is. Precompiled header files are also +printed, even if they are found to be invalid; an invalid precompiled +header file is printed with ‘<samp>...x</samp>’ and a valid one with ‘<samp>...!</samp>’ . +</p> +<a name="index-d"></a> +</dd> +<dt><code>-d<var>letters</var></code></dt> +<dd><p>Says to make debugging dumps during compilation as specified by +<var>letters</var>. The flags documented here are those relevant to the +preprocessor. Other <var>letters</var> are interpreted +by the compiler proper, or reserved for future versions of GCC, and so +are silently ignored. If you specify <var>letters</var> whose behavior +conflicts, the result is undefined. +</p> +<dl compact="compact"> +<dd><a name="index-dM"></a> +</dd> +<dt><code>-dM</code></dt> +<dd><p>Instead of the normal output, generate a list of ‘<samp>#define</samp>’ +directives for all the macros defined during the execution of the +preprocessor, including predefined macros. This gives you a way of +finding out what is predefined in your version of the preprocessor. +Assuming you have no file <samp>foo.h</samp>, the command +</p> +<div class="smallexample"> +<pre class="smallexample">touch foo.h; cpp -dM foo.h +</pre></div> + +<p>shows all the predefined macros. +</p> + +<a name="index-dD"></a> +</dd> +<dt><code>-dD</code></dt> +<dd><p>Like <samp>-dM</samp> except in two respects: it does <em>not</em> include the +predefined macros, and it outputs <em>both</em> the ‘<samp>#define</samp>’ +directives and the result of preprocessing. Both kinds of output go to +the standard output file. +</p> +<a name="index-dN"></a> +</dd> +<dt><code>-dN</code></dt> +<dd><p>Like <samp>-dD</samp>, but emit only the macro names, not their expansions. +</p> +<a name="index-dI"></a> +</dd> +<dt><code>-dI</code></dt> +<dd><p>Output ‘<samp>#include</samp>’ directives in addition to the result of +preprocessing. +</p> +<a name="index-dU"></a> +</dd> +<dt><code>-dU</code></dt> +<dd><p>Like <samp>-dD</samp> except that only macros that are expanded, or whose +definedness is tested in preprocessor directives, are output; the +output is delayed until the use or test of the macro; and +‘<samp>#undef</samp>’ directives are also output for macros tested but +undefined at the time. +</p></dd> +</dl> + +<a name="index-fdebug_002dcpp"></a> +</dd> +<dt><code>-fdebug-cpp</code></dt> +<dd><p>This option is only useful for debugging GCC. When used from CPP or with +<samp>-E</samp>, it dumps debugging information about location maps. Every +token in the output is preceded by the dump of the map its location +belongs to. +</p> +<p>When used from GCC without <samp>-E</samp>, this option has no effect. +</p> + + +<a name="index-I"></a> +<a name="index-iquote"></a> +<a name="index-isystem"></a> +<a name="index-idirafter"></a> +</dd> +<dt><code>-I <var>dir</var></code></dt> +<dt><code>-iquote <var>dir</var></code></dt> +<dt><code>-isystem <var>dir</var></code></dt> +<dt><code>-idirafter <var>dir</var></code></dt> +<dd><p>Add the directory <var>dir</var> to the list of directories to be searched +for header files during preprocessing. +See <a href="Search-Path.html#Search-Path">Search Path</a>. +If <var>dir</var> begins with ‘<samp>=</samp>’ or <code>$SYSROOT</code>, then the ‘<samp>=</samp>’ +or <code>$SYSROOT</code> is replaced by the sysroot prefix; see +<samp>--sysroot</samp> and <samp>-isysroot</samp>. +</p> +<p>Directories specified with <samp>-iquote</samp> apply only to the quote +form of the directive, <code>#include "<var>file</var>"<!-- /@w --></code>. +Directories specified with <samp>-I</samp>, <samp>-isystem</samp>, +or <samp>-idirafter</samp> apply to lookup for both the +<code>#include "<var>file</var>"<!-- /@w --></code> and +<code>#include <<var>file</var>><!-- /@w --></code> directives. +</p> +<p>You can specify any number or combination of these options on the +command line to search for header files in several directories. +The lookup order is as follows: +</p> +<ol> +<li> For the quote form of the include directive, the directory of the current +file is searched first. + +</li><li> For the quote form of the include directive, the directories specified +by <samp>-iquote</samp> options are searched in left-to-right order, +as they appear on the command line. + +</li><li> Directories specified with <samp>-I</samp> options are scanned in +left-to-right order. + +</li><li> Directories specified with <samp>-isystem</samp> options are scanned in +left-to-right order. + +</li><li> Standard system directories are scanned. + +</li><li> Directories specified with <samp>-idirafter</samp> options are scanned in +left-to-right order. +</li></ol> + +<p>You can use <samp>-I</samp> to override a system header +file, substituting your own version, since these directories are +searched before the standard system header file directories. +However, you should +not use this option to add directories that contain vendor-supplied +system header files; use <samp>-isystem</samp> for that. +</p> +<p>The <samp>-isystem</samp> and <samp>-idirafter</samp> options also mark the directory +as a system directory, so that it gets the same special treatment that +is applied to the standard system directories. +See <a href="System-Headers.html#System-Headers">System Headers</a>. +</p> +<p>If a standard system include directory, or a directory specified with +<samp>-isystem</samp>, is also specified with <samp>-I</samp>, the <samp>-I</samp> +option is ignored. The directory is still searched but as a +system directory at its normal position in the system include chain. +This is to ensure that GCC’s procedure to fix buggy system headers and +the ordering for the <code>#include_next</code> directive are not inadvertently +changed. +If you really need to change the search order for system directories, +use the <samp>-nostdinc</samp> and/or <samp>-isystem</samp> options. +See <a href="System-Headers.html#System-Headers">System Headers</a>. +</p> +<a name="index-I_002d"></a> +</dd> +<dt><code>-I-</code></dt> +<dd><p>Split the include path. +This option has been deprecated. Please use <samp>-iquote</samp> instead for +<samp>-I</samp> directories before the <samp>-I-</samp> and remove the <samp>-I-</samp> +option. +</p> +<p>Any directories specified with <samp>-I</samp> +options before <samp>-I-</samp> are searched only for headers requested with +<code>#include "<var>file</var>"<!-- /@w --></code>; they are not searched for +<code>#include <<var>file</var>><!-- /@w --></code>. If additional directories are +specified with <samp>-I</samp> options after the <samp>-I-</samp>, those +directories are searched for all ‘<samp>#include</samp>’ directives. +</p> +<p>In addition, <samp>-I-</samp> inhibits the use of the directory of the current +file directory as the first search directory for <code>#include "<var>file</var>"<!-- /@w --></code>. There is no way to override this effect of <samp>-I-</samp>. +See <a href="Search-Path.html#Search-Path">Search Path</a>. +</p> +<a name="index-iprefix"></a> +</dd> +<dt><code>-iprefix <var>prefix</var></code></dt> +<dd><p>Specify <var>prefix</var> as the prefix for subsequent <samp>-iwithprefix</samp> +options. If the prefix represents a directory, you should include the +final ‘<samp>/</samp>’. +</p> +<a name="index-iwithprefix"></a> +<a name="index-iwithprefixbefore"></a> +</dd> +<dt><code>-iwithprefix <var>dir</var></code></dt> +<dt><code>-iwithprefixbefore <var>dir</var></code></dt> +<dd><p>Append <var>dir</var> to the prefix specified previously with +<samp>-iprefix</samp>, and add the resulting directory to the include search +path. <samp>-iwithprefixbefore</samp> puts it in the same place <samp>-I</samp> +would; <samp>-iwithprefix</samp> puts it where <samp>-idirafter</samp> would. +</p> +<a name="index-isysroot"></a> +</dd> +<dt><code>-isysroot <var>dir</var></code></dt> +<dd><p>This option is like the <samp>--sysroot</samp> option, but applies only to +header files (except for Darwin targets, where it applies to both header +files and libraries). See the <samp>--sysroot</samp> option for more +information. +</p> +<a name="index-imultilib"></a> +</dd> +<dt><code>-imultilib <var>dir</var></code></dt> +<dd><p>Use <var>dir</var> as a subdirectory of the directory containing +target-specific C++ headers. +</p> +<a name="index-nostdinc"></a> +</dd> +<dt><code>-nostdinc</code></dt> +<dd><p>Do not search the standard system directories for header files. +Only the directories explicitly specified with <samp>-I</samp>, +<samp>-iquote</samp>, <samp>-isystem</samp>, and/or <samp>-idirafter</samp> +options (and the directory of the current file, if appropriate) +are searched. +</p> +<a name="index-nostdinc_002b_002b"></a> +</dd> +<dt><code>-nostdinc++</code></dt> +<dd><p>Do not search for header files in the C++-specific standard directories, +but do still search the other standard directories. (This option is +used when building the C++ library.) +</p> + + + +<a name="index-Wcomment"></a> +<a name="index-Wcomments"></a> +</dd> +<dt><code>-Wcomment</code></dt> +<dt><code>-Wcomments</code></dt> +<dd><p>Warn whenever a comment-start sequence ‘<samp>/*</samp>’ appears in a ‘<samp>/*</samp>’ +comment, or whenever a backslash-newline appears in a ‘<samp>//</samp>’ comment. +This warning is enabled by <samp>-Wall</samp>. +</p> +<a name="index-Wtrigraphs"></a> +</dd> +<dt><code>-Wtrigraphs</code></dt> +<dd><a name="Wtrigraphs"></a><p>Warn if any trigraphs are encountered that might change the meaning of +the program. Trigraphs within comments are not warned about, +except those that would form escaped newlines. +</p> +<p>This option is implied by <samp>-Wall</samp>. If <samp>-Wall</samp> is not +given, this option is still enabled unless trigraphs are enabled. To +get trigraph conversion without warnings, but get the other +<samp>-Wall</samp> warnings, use ‘<samp>-trigraphs -Wall -Wno-trigraphs</samp>’. +</p> +<a name="index-Wundef"></a> +<a name="index-Wno_002dundef"></a> +</dd> +<dt><code>-Wundef</code></dt> +<dd><p>Warn if an undefined identifier is evaluated in an <code>#if</code> directive. +Such identifiers are replaced with zero. +</p> +<a name="index-Wexpansion_002dto_002ddefined"></a> +</dd> +<dt><code>-Wexpansion-to-defined</code></dt> +<dd><p>Warn whenever ‘<samp>defined</samp>’ is encountered in the expansion of a macro +(including the case where the macro is expanded by an ‘<samp>#if</samp>’ directive). +Such usage is not portable. +This warning is also enabled by <samp>-Wpedantic</samp> and <samp>-Wextra</samp>. +</p> +<a name="index-Wunused_002dmacros"></a> +</dd> +<dt><code>-Wunused-macros</code></dt> +<dd><p>Warn about macros defined in the main file that are unused. A macro +is <em>used</em> if it is expanded or tested for existence at least once. +The preprocessor also warns if the macro has not been used at the +time it is redefined or undefined. +</p> +<p>Built-in macros, macros defined on the command line, and macros +defined in include files are not warned about. +</p> +<p><em>Note:</em> If a macro is actually used, but only used in skipped +conditional blocks, then the preprocessor reports it as unused. To avoid the +warning in such a case, you might improve the scope of the macro’s +definition by, for example, moving it into the first skipped block. +Alternatively, you could provide a dummy use with something like: +</p> +<div class="smallexample"> +<pre class="smallexample">#if defined the_macro_causing_the_warning +#endif +</pre></div> + +<a name="index-Wno_002dendif_002dlabels"></a> +<a name="index-Wendif_002dlabels"></a> +</dd> +<dt><code>-Wno-endif-labels</code></dt> +<dd><p>Do not warn whenever an <code>#else</code> or an <code>#endif</code> are followed by text. +This sometimes happens in older programs with code of the form +</p> +<div class="smallexample"> +<pre class="smallexample">#if FOO +… +#else FOO +… +#endif FOO +</pre></div> + +<p>The second and third <code>FOO</code> should be in comments. +This warning is on by default. +</p></dd> +</dl> + +<hr> +<div class="header"> +<p> +Next: <a href="Environment-Variables.html#Environment-Variables" accesskey="n" rel="next">Environment Variables</a>, Previous: <a href="Implementation-Details.html#Implementation-Details" accesskey="p" rel="previous">Implementation Details</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Line-Control.html b/share/doc/cpp/Line-Control.html new file mode 100644 index 0000000..12e1aa1 --- /dev/null +++ b/share/doc/cpp/Line-Control.html @@ -0,0 +1,139 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Line Control</title> + +<meta name="description" content="The C Preprocessor: Line Control"> +<meta name="keywords" content="The C Preprocessor: Line Control"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html#Top" rel="up" title="Top"> +<link href="Pragmas.html#Pragmas" rel="next" title="Pragmas"> +<link href="Diagnostics.html#Diagnostics" rel="previous" title="Diagnostics"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Line-Control"></a> +<div class="header"> +<p> +Next: <a href="Pragmas.html#Pragmas" accesskey="n" rel="next">Pragmas</a>, Previous: <a href="Diagnostics.html#Diagnostics" accesskey="p" rel="previous">Diagnostics</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Line-Control-1"></a> +<h2 class="chapter">6 Line Control</h2> +<a name="index-line-control"></a> + +<p>The C preprocessor informs the C compiler of the location in your source +code where each token came from. Presently, this is just the file name +and line number. All the tokens resulting from macro expansion are +reported as having appeared on the line of the source file where the +outermost macro was used. We intend to be more accurate in the future. +</p> +<p>If you write a program which generates source code, such as the +<code>bison</code> parser generator, you may want to adjust the preprocessor’s +notion of the current file name and line number by hand. Parts of the +output from <code>bison</code> are generated from scratch, other parts come +from a standard parser file. The rest are copied verbatim from +<code>bison</code>’s input. You would like compiler error messages and +symbolic debuggers to be able to refer to <code>bison</code>’s input file. +</p> +<a name="index-_0023line"></a> +<p><code>bison</code> or any such program can arrange this by writing +‘<samp>#line</samp>’ directives into the output file. ‘<samp>#line</samp>’ is a +directive that specifies the original line number and source file name +for subsequent input in the current preprocessor input file. +‘<samp>#line</samp>’ has three variants: +</p> +<dl compact="compact"> +<dt><code>#line <var>linenum</var></code></dt> +<dd><p><var>linenum</var> is a non-negative decimal integer constant. It specifies +the line number which should be reported for the following line of +input. Subsequent lines are counted from <var>linenum</var>. +</p> +</dd> +<dt><code>#line <var>linenum</var> <var>filename</var></code></dt> +<dd><p><var>linenum</var> is the same as for the first form, and has the same +effect. In addition, <var>filename</var> is a string constant. The +following line and all subsequent lines are reported to come from the +file it specifies, until something else happens to change that. +<var>filename</var> is interpreted according to the normal rules for a string +constant: backslash escapes are interpreted. This is different from +‘<samp>#include</samp>’. +</p> +</dd> +<dt><code>#line <var>anything else</var></code></dt> +<dd><p><var>anything else</var> is checked for macro calls, which are expanded. +The result should match one of the above two forms. +</p></dd> +</dl> + +<p>‘<samp>#line</samp>’ directives alter the results of the <code>__FILE__</code> and +<code>__LINE__</code> predefined macros from that point on. See <a href="Standard-Predefined-Macros.html#Standard-Predefined-Macros">Standard Predefined Macros</a>. They do not have any effect on ‘<samp>#include</samp>’’s +idea of the directory containing the current file. +</p> +<hr> +<div class="header"> +<p> +Next: <a href="Pragmas.html#Pragmas" accesskey="n" rel="next">Pragmas</a>, Previous: <a href="Diagnostics.html#Diagnostics" accesskey="p" rel="previous">Diagnostics</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Macro-Arguments.html b/share/doc/cpp/Macro-Arguments.html new file mode 100644 index 0000000..33aaf33 --- /dev/null +++ b/share/doc/cpp/Macro-Arguments.html @@ -0,0 +1,193 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Macro Arguments</title> + +<meta name="description" content="The C Preprocessor: Macro Arguments"> +<meta name="keywords" content="The C Preprocessor: Macro Arguments"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Macros.html#Macros" rel="up" title="Macros"> +<link href="Stringizing.html#Stringizing" rel="next" title="Stringizing"> +<link href="Function_002dlike-Macros.html#Function_002dlike-Macros" rel="previous" title="Function-like Macros"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Macro-Arguments"></a> +<div class="header"> +<p> +Next: <a href="Stringizing.html#Stringizing" accesskey="n" rel="next">Stringizing</a>, Previous: <a href="Function_002dlike-Macros.html#Function_002dlike-Macros" accesskey="p" rel="previous">Function-like Macros</a>, Up: <a href="Macros.html#Macros" accesskey="u" rel="up">Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Macro-Arguments-1"></a> +<h3 class="section">3.3 Macro Arguments</h3> +<a name="index-arguments"></a> +<a name="index-macros-with-arguments"></a> +<a name="index-arguments-in-macro-definitions"></a> + +<p>Function-like macros can take <em>arguments</em>, just like true functions. +To define a macro that uses arguments, you insert <em>parameters</em> +between the pair of parentheses in the macro definition that make the +macro function-like. The parameters must be valid C identifiers, +separated by commas and optionally whitespace. +</p> +<p>To invoke a macro that takes arguments, you write the name of the macro +followed by a list of <em>actual arguments</em> in parentheses, separated +by commas. The invocation of the macro need not be restricted to a +single logical line—it can cross as many lines in the source file as +you wish. The number of arguments you give must match the number of +parameters in the macro definition. When the macro is expanded, each +use of a parameter in its body is replaced by the tokens of the +corresponding argument. (You need not use all of the parameters in the +macro body.) +</p> +<p>As an example, here is a macro that computes the minimum of two numeric +values, as it is defined in many C programs, and some uses. +</p> +<div class="smallexample"> +<pre class="smallexample">#define min(X, Y) ((X) < (Y) ? (X) : (Y)) + x = min(a, b); → x = ((a) < (b) ? (a) : (b)); + y = min(1, 2); → y = ((1) < (2) ? (1) : (2)); + z = min(a + 28, *p); → z = ((a + 28) < (*p) ? (a + 28) : (*p)); +</pre></div> + +<p>(In this small example you can already see several of the dangers of +macro arguments. See <a href="Macro-Pitfalls.html#Macro-Pitfalls">Macro Pitfalls</a>, for detailed explanations.) +</p> +<p>Leading and trailing whitespace in each argument is dropped, and all +whitespace between the tokens of an argument is reduced to a single +space. Parentheses within each argument must balance; a comma within +such parentheses does not end the argument. However, there is no +requirement for square brackets or braces to balance, and they do not +prevent a comma from separating arguments. Thus, +</p> +<div class="smallexample"> +<pre class="smallexample">macro (array[x = y, x + 1]) +</pre></div> + +<p>passes two arguments to <code>macro</code>: <code>array[x = y</code> and <code>x + +1]</code>. If you want to supply <code>array[x = y, x + 1]</code> as an argument, +you can write it as <code>array[(x = y, x + 1)]</code>, which is equivalent C +code. +</p> +<p>All arguments to a macro are completely macro-expanded before they are +substituted into the macro body. After substitution, the complete text +is scanned again for macros to expand, including the arguments. This rule +may seem strange, but it is carefully designed so you need not worry +about whether any function call is actually a macro invocation. You can +run into trouble if you try to be too clever, though. See <a href="Argument-Prescan.html#Argument-Prescan">Argument Prescan</a>, for detailed discussion. +</p> +<p>For example, <code>min (min (a, b), c)</code> is first expanded to +</p> +<div class="smallexample"> +<pre class="smallexample"> min (((a) < (b) ? (a) : (b)), (c)) +</pre></div> + +<p>and then to +</p> +<div class="smallexample"> +<pre class="smallexample">((((a) < (b) ? (a) : (b))) < (c) + ? (((a) < (b) ? (a) : (b))) + : (c)) +</pre></div> + +<p>(Line breaks shown here for clarity would not actually be generated.) +</p> +<a name="index-empty-macro-arguments"></a> +<p>You can leave macro arguments empty; this is not an error to the +preprocessor (but many macros will then expand to invalid code). +You cannot leave out arguments entirely; if a macro takes two arguments, +there must be exactly one comma at the top level of its argument list. +Here are some silly examples using <code>min</code>: +</p> +<div class="smallexample"> +<pre class="smallexample">min(, b) → (( ) < (b) ? ( ) : (b)) +min(a, ) → ((a ) < ( ) ? (a ) : ( )) +min(,) → (( ) < ( ) ? ( ) : ( )) +min((,),) → (((,)) < ( ) ? ((,)) : ( )) + +min() error→ macro "min" requires 2 arguments, but only 1 given +min(,,) error→ macro "min" passed 3 arguments, but takes just 2 +</pre></div> + +<p>Whitespace is not a preprocessing token, so if a macro <code>foo</code> takes +one argument, <code>foo ()<!-- /@w --></code> and <code>foo ( )<!-- /@w --></code> both supply it an +empty argument. Previous GNU preprocessor implementations and +documentation were incorrect on this point, insisting that a +function-like macro that takes a single argument be passed a space if an +empty argument was required. +</p> +<p>Macro parameters appearing inside string literals are not replaced by +their corresponding actual arguments. +</p> +<div class="smallexample"> +<pre class="smallexample">#define foo(x) x, "x" +foo(bar) → bar, "x" +</pre></div> + +<hr> +<div class="header"> +<p> +Next: <a href="Stringizing.html#Stringizing" accesskey="n" rel="next">Stringizing</a>, Previous: <a href="Function_002dlike-Macros.html#Function_002dlike-Macros" accesskey="p" rel="previous">Function-like Macros</a>, Up: <a href="Macros.html#Macros" accesskey="u" rel="up">Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Macro-Pitfalls.html b/share/doc/cpp/Macro-Pitfalls.html new file mode 100644 index 0000000..30372c1 --- /dev/null +++ b/share/doc/cpp/Macro-Pitfalls.html @@ -0,0 +1,108 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Macro Pitfalls</title> + +<meta name="description" content="The C Preprocessor: Macro Pitfalls"> +<meta name="keywords" content="The C Preprocessor: Macro Pitfalls"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Macros.html#Macros" rel="up" title="Macros"> +<link href="Misnesting.html#Misnesting" rel="next" title="Misnesting"> +<link href="Directives-Within-Macro-Arguments.html#Directives-Within-Macro-Arguments" rel="previous" title="Directives Within Macro Arguments"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Macro-Pitfalls"></a> +<div class="header"> +<p> +Previous: <a href="Directives-Within-Macro-Arguments.html#Directives-Within-Macro-Arguments" accesskey="p" rel="previous">Directives Within Macro Arguments</a>, Up: <a href="Macros.html#Macros" accesskey="u" rel="up">Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Macro-Pitfalls-1"></a> +<h3 class="section">3.10 Macro Pitfalls</h3> +<a name="index-problems-with-macros"></a> +<a name="index-pitfalls-of-macros"></a> + +<p>In this section we describe some special rules that apply to macros and +macro expansion, and point out certain cases in which the rules have +counter-intuitive consequences that you must watch out for. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="Misnesting.html#Misnesting" accesskey="1">Misnesting</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Operator-Precedence-Problems.html#Operator-Precedence-Problems" accesskey="2">Operator Precedence Problems</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Swallowing-the-Semicolon.html#Swallowing-the-Semicolon" accesskey="3">Swallowing the Semicolon</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Duplication-of-Side-Effects.html#Duplication-of-Side-Effects" accesskey="4">Duplication of Side Effects</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Self_002dReferential-Macros.html#Self_002dReferential-Macros" accesskey="5">Self-Referential Macros</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Argument-Prescan.html#Argument-Prescan" accesskey="6">Argument Prescan</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Newlines-in-Arguments.html#Newlines-in-Arguments" accesskey="7">Newlines in Arguments</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +</table> + + + + +</body> +</html> diff --git a/share/doc/cpp/Macros.html b/share/doc/cpp/Macros.html new file mode 100644 index 0000000..9fb338b --- /dev/null +++ b/share/doc/cpp/Macros.html @@ -0,0 +1,122 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Macros</title> + +<meta name="description" content="The C Preprocessor: Macros"> +<meta name="keywords" content="The C Preprocessor: Macros"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html#Top" rel="up" title="Top"> +<link href="Object_002dlike-Macros.html#Object_002dlike-Macros" rel="next" title="Object-like Macros"> +<link href="System-Headers.html#System-Headers" rel="previous" title="System Headers"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Macros"></a> +<div class="header"> +<p> +Next: <a href="Conditionals.html#Conditionals" accesskey="n" rel="next">Conditionals</a>, Previous: <a href="Header-Files.html#Header-Files" accesskey="p" rel="previous">Header Files</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Macros-1"></a> +<h2 class="chapter">3 Macros</h2> + +<p>A <em>macro</em> is a fragment of code which has been given a name. +Whenever the name is used, it is replaced by the contents of the macro. +There are two kinds of macros. They differ mostly in what they look +like when they are used. <em>Object-like</em> macros resemble data objects +when used, <em>function-like</em> macros resemble function calls. +</p> +<p>You may define any valid identifier as a macro, even if it is a C +keyword. The preprocessor does not know anything about keywords. This +can be useful if you wish to hide a keyword such as <code>const</code> from an +older compiler that does not understand it. However, the preprocessor +operator <code>defined</code> (see <a href="Defined.html#Defined">Defined</a>) can never be defined as a +macro, and C++’s named operators (see <a href="C_002b_002b-Named-Operators.html#C_002b_002b-Named-Operators">C++ Named Operators</a>) cannot be +macros when you are compiling C++. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="Object_002dlike-Macros.html#Object_002dlike-Macros" accesskey="1">Object-like Macros</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Function_002dlike-Macros.html#Function_002dlike-Macros" accesskey="2">Function-like Macros</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Macro-Arguments.html#Macro-Arguments" accesskey="3">Macro Arguments</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Stringizing.html#Stringizing" accesskey="4">Stringizing</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Concatenation.html#Concatenation" accesskey="5">Concatenation</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Variadic-Macros.html#Variadic-Macros" accesskey="6">Variadic Macros</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Predefined-Macros.html#Predefined-Macros" accesskey="7">Predefined Macros</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Undefining-and-Redefining-Macros.html#Undefining-and-Redefining-Macros" accesskey="8">Undefining and Redefining Macros</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Directives-Within-Macro-Arguments.html#Directives-Within-Macro-Arguments" accesskey="9">Directives Within Macro Arguments</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Macro-Pitfalls.html#Macro-Pitfalls">Macro Pitfalls</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +</table> + + + + +</body> +</html> diff --git a/share/doc/cpp/Misnesting.html b/share/doc/cpp/Misnesting.html new file mode 100644 index 0000000..4a47bb9 --- /dev/null +++ b/share/doc/cpp/Misnesting.html @@ -0,0 +1,115 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Misnesting</title> + +<meta name="description" content="The C Preprocessor: Misnesting"> +<meta name="keywords" content="The C Preprocessor: Misnesting"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Macro-Pitfalls.html#Macro-Pitfalls" rel="up" title="Macro Pitfalls"> +<link href="Operator-Precedence-Problems.html#Operator-Precedence-Problems" rel="next" title="Operator Precedence Problems"> +<link href="Macro-Pitfalls.html#Macro-Pitfalls" rel="previous" title="Macro Pitfalls"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Misnesting"></a> +<div class="header"> +<p> +Next: <a href="Operator-Precedence-Problems.html#Operator-Precedence-Problems" accesskey="n" rel="next">Operator Precedence Problems</a>, Up: <a href="Macro-Pitfalls.html#Macro-Pitfalls" accesskey="u" rel="up">Macro Pitfalls</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Misnesting-1"></a> +<h4 class="subsection">3.10.1 Misnesting</h4> + +<p>When a macro is called with arguments, the arguments are substituted +into the macro body and the result is checked, together with the rest of +the input file, for more macro calls. It is possible to piece together +a macro call coming partially from the macro body and partially from the +arguments. For example, +</p> +<div class="smallexample"> +<pre class="smallexample">#define twice(x) (2*(x)) +#define call_with_1(x) x(1) +call_with_1 (twice) + → twice(1) + → (2*(1)) +</pre></div> + +<p>Macro definitions do not have to have balanced parentheses. By writing +an unbalanced open parenthesis in a macro body, it is possible to create +a macro call that begins inside the macro body but ends outside of it. +For example, +</p> +<div class="smallexample"> +<pre class="smallexample">#define strange(file) fprintf (file, "%s %d", +… +strange(stderr) p, 35) + → fprintf (stderr, "%s %d", p, 35) +</pre></div> + +<p>The ability to piece together a macro call can be useful, but the use of +unbalanced open parentheses in a macro body is just confusing, and +should be avoided. +</p> + + + +</body> +</html> diff --git a/share/doc/cpp/Newlines-in-Arguments.html b/share/doc/cpp/Newlines-in-Arguments.html new file mode 100644 index 0000000..7b9cce7 --- /dev/null +++ b/share/doc/cpp/Newlines-in-Arguments.html @@ -0,0 +1,108 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Newlines in Arguments</title> + +<meta name="description" content="The C Preprocessor: Newlines in Arguments"> +<meta name="keywords" content="The C Preprocessor: Newlines in Arguments"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Macro-Pitfalls.html#Macro-Pitfalls" rel="up" title="Macro Pitfalls"> +<link href="Conditionals.html#Conditionals" rel="next" title="Conditionals"> +<link href="Argument-Prescan.html#Argument-Prescan" rel="previous" title="Argument Prescan"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Newlines-in-Arguments"></a> +<div class="header"> +<p> +Previous: <a href="Argument-Prescan.html#Argument-Prescan" accesskey="p" rel="previous">Argument Prescan</a>, Up: <a href="Macro-Pitfalls.html#Macro-Pitfalls" accesskey="u" rel="up">Macro Pitfalls</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Newlines-in-Arguments-1"></a> +<h4 class="subsection">3.10.7 Newlines in Arguments</h4> +<a name="index-newlines-in-macro-arguments"></a> + +<p>The invocation of a function-like macro can extend over many logical +lines. However, in the present implementation, the entire expansion +comes out on one line. Thus line numbers emitted by the compiler or +debugger refer to the line the invocation started on, which might be +different to the line containing the argument causing the problem. +</p> +<p>Here is an example illustrating this: +</p> +<div class="smallexample"> +<pre class="smallexample">#define ignore_second_arg(a,b,c) a; c + +ignore_second_arg (foo (), + ignored (), + syntax error); +</pre></div> + +<p>The syntax error triggered by the tokens <code>syntax error</code> results in +an error message citing line three—the line of ignore_second_arg— +even though the problematic code comes from line five. +</p> +<p>We consider this a bug, and intend to fix it in the near future. +</p> + + + +</body> +</html> diff --git a/share/doc/cpp/Object_002dlike-Macros.html b/share/doc/cpp/Object_002dlike-Macros.html new file mode 100644 index 0000000..70bc407 --- /dev/null +++ b/share/doc/cpp/Object_002dlike-Macros.html @@ -0,0 +1,207 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Object-like Macros</title> + +<meta name="description" content="The C Preprocessor: Object-like Macros"> +<meta name="keywords" content="The C Preprocessor: Object-like Macros"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Macros.html#Macros" rel="up" title="Macros"> +<link href="Function_002dlike-Macros.html#Function_002dlike-Macros" rel="next" title="Function-like Macros"> +<link href="Macros.html#Macros" rel="previous" title="Macros"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Object_002dlike-Macros"></a> +<div class="header"> +<p> +Next: <a href="Function_002dlike-Macros.html#Function_002dlike-Macros" accesskey="n" rel="next">Function-like Macros</a>, Up: <a href="Macros.html#Macros" accesskey="u" rel="up">Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Object_002dlike-Macros-1"></a> +<h3 class="section">3.1 Object-like Macros</h3> +<a name="index-object_002dlike-macro"></a> +<a name="index-symbolic-constants"></a> +<a name="index-manifest-constants"></a> + +<p>An <em>object-like macro</em> is a simple identifier which will be replaced +by a code fragment. It is called object-like because it looks like a +data object in code that uses it. They are most commonly used to give +symbolic names to numeric constants. +</p> +<a name="index-_0023define"></a> +<p>You create macros with the ‘<samp>#define</samp>’ directive. ‘<samp>#define</samp>’ is +followed by the name of the macro and then the token sequence it should +be an abbreviation for, which is variously referred to as the macro’s +<em>body</em>, <em>expansion</em> or <em>replacement list</em>. For example, +</p> +<div class="smallexample"> +<pre class="smallexample">#define BUFFER_SIZE 1024 +</pre></div> + +<p>defines a macro named <code>BUFFER_SIZE</code> as an abbreviation for the +token <code>1024</code>. If somewhere after this ‘<samp>#define</samp>’ directive +there comes a C statement of the form +</p> +<div class="smallexample"> +<pre class="smallexample">foo = (char *) malloc (BUFFER_SIZE); +</pre></div> + +<p>then the C preprocessor will recognize and <em>expand</em> the macro +<code>BUFFER_SIZE</code>. The C compiler will see the same tokens as it would +if you had written +</p> +<div class="smallexample"> +<pre class="smallexample">foo = (char *) malloc (1024); +</pre></div> + +<p>By convention, macro names are written in uppercase. Programs are +easier to read when it is possible to tell at a glance which names are +macros. +</p> +<p>The macro’s body ends at the end of the ‘<samp>#define</samp>’ line. You may +continue the definition onto multiple lines, if necessary, using +backslash-newline. When the macro is expanded, however, it will all +come out on one line. For example, +</p> +<div class="smallexample"> +<pre class="smallexample">#define NUMBERS 1, \ + 2, \ + 3 +int x[] = { NUMBERS }; + → int x[] = { 1, 2, 3 }; +</pre></div> + +<p>The most common visible consequence of this is surprising line numbers +in error messages. +</p> +<p>There is no restriction on what can go in a macro body provided it +decomposes into valid preprocessing tokens. Parentheses need not +balance, and the body need not resemble valid C code. (If it does not, +you may get error messages from the C compiler when you use the macro.) +</p> +<p>The C preprocessor scans your program sequentially. Macro definitions +take effect at the place you write them. Therefore, the following input +to the C preprocessor +</p> +<div class="smallexample"> +<pre class="smallexample">foo = X; +#define X 4 +bar = X; +</pre></div> + +<p>produces +</p> +<div class="smallexample"> +<pre class="smallexample">foo = X; +bar = 4; +</pre></div> + +<p>When the preprocessor expands a macro name, the macro’s expansion +replaces the macro invocation, then the expansion is examined for more +macros to expand. For example, +</p> +<div class="smallexample"> +<pre class="smallexample">#define TABLESIZE BUFSIZE +#define BUFSIZE 1024 +TABLESIZE + → BUFSIZE + → 1024 +</pre></div> + +<p><code>TABLESIZE</code> is expanded first to produce <code>BUFSIZE</code>, then that +macro is expanded to produce the final result, <code>1024</code>. +</p> +<p>Notice that <code>BUFSIZE</code> was not defined when <code>TABLESIZE</code> was +defined. The ‘<samp>#define</samp>’ for <code>TABLESIZE</code> uses exactly the +expansion you specify—in this case, <code>BUFSIZE</code>—and does not +check to see whether it too contains macro names. Only when you +<em>use</em> <code>TABLESIZE</code> is the result of its expansion scanned for +more macro names. +</p> +<p>This makes a difference if you change the definition of <code>BUFSIZE</code> +at some point in the source file. <code>TABLESIZE</code>, defined as shown, +will always expand using the definition of <code>BUFSIZE</code> that is +currently in effect: +</p> +<div class="smallexample"> +<pre class="smallexample">#define BUFSIZE 1020 +#define TABLESIZE BUFSIZE +#undef BUFSIZE +#define BUFSIZE 37 +</pre></div> + +<p>Now <code>TABLESIZE</code> expands (in two stages) to <code>37</code>. +</p> +<p>If the expansion of a macro contains its own name, either directly or +via intermediate macros, it is not expanded again when the expansion is +examined for more macros. This prevents infinite recursion. +See <a href="Self_002dReferential-Macros.html#Self_002dReferential-Macros">Self-Referential Macros</a>, for the precise details. +</p> +<hr> +<div class="header"> +<p> +Next: <a href="Function_002dlike-Macros.html#Function_002dlike-Macros" accesskey="n" rel="next">Function-like Macros</a>, Up: <a href="Macros.html#Macros" accesskey="u" rel="up">Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Obsolete-Features.html b/share/doc/cpp/Obsolete-Features.html new file mode 100644 index 0000000..4a64af5 --- /dev/null +++ b/share/doc/cpp/Obsolete-Features.html @@ -0,0 +1,175 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Obsolete Features</title> + +<meta name="description" content="The C Preprocessor: Obsolete Features"> +<meta name="keywords" content="The C Preprocessor: Obsolete Features"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Implementation-Details.html#Implementation-Details" rel="up" title="Implementation Details"> +<link href="Invocation.html#Invocation" rel="next" title="Invocation"> +<link href="Implementation-limits.html#Implementation-limits" rel="previous" title="Implementation limits"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Obsolete-Features"></a> +<div class="header"> +<p> +Previous: <a href="Implementation-limits.html#Implementation-limits" accesskey="p" rel="previous">Implementation limits</a>, Up: <a href="Implementation-Details.html#Implementation-Details" accesskey="u" rel="up">Implementation Details</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Obsolete-Features-1"></a> +<h3 class="section">11.3 Obsolete Features</h3> + +<p>CPP has some features which are present mainly for compatibility with +older programs. We discourage their use in new code. In some cases, +we plan to remove the feature in a future version of GCC. +</p> +<a name="Assertions"></a> +<h4 class="subsection">11.3.1 Assertions</h4> +<a name="index-assertions"></a> + +<p><em>Assertions</em> are a deprecated alternative to macros in writing +conditionals to test what sort of computer or system the compiled +program will run on. Assertions are usually predefined, but you can +define them with preprocessing directives or command-line options. +</p> +<p>Assertions were intended to provide a more systematic way to describe +the compiler’s target system and we added them for compatibility with +existing compilers. In practice they are just as unpredictable as the +system-specific predefined macros. In addition, they are not part of +any standard, and only a few compilers support them. +Therefore, the use of assertions is <strong>less</strong> portable than the use +of system-specific predefined macros. We recommend you do not use them at +all. +</p> +<a name="index-predicates"></a> +<p>An assertion looks like this: +</p> +<div class="smallexample"> +<pre class="smallexample">#<var>predicate</var> (<var>answer</var>) +</pre></div> + +<p><var>predicate</var> must be a single identifier. <var>answer</var> can be any +sequence of tokens; all characters are significant except for leading +and trailing whitespace, and differences in internal whitespace +sequences are ignored. (This is similar to the rules governing macro +redefinition.) Thus, <code>(x + y)</code> is different from <code>(x+y)</code> but +equivalent to <code>( x + y )<!-- /@w --></code>. Parentheses do not nest inside an +answer. +</p> +<a name="index-testing-predicates"></a> +<p>To test an assertion, you write it in an ‘<samp>#if</samp>’. For example, this +conditional succeeds if either <code>vax</code> or <code>ns16000</code> has been +asserted as an answer for <code>machine</code>. +</p> +<div class="smallexample"> +<pre class="smallexample">#if #machine (vax) || #machine (ns16000) +</pre></div> + +<p>You can test whether <em>any</em> answer is asserted for a predicate by +omitting the answer in the conditional: +</p> +<div class="smallexample"> +<pre class="smallexample">#if #machine +</pre></div> + +<a name="index-_0023assert"></a> +<p>Assertions are made with the ‘<samp>#assert</samp>’ directive. Its sole +argument is the assertion to make, without the leading ‘<samp>#</samp>’ that +identifies assertions in conditionals. +</p> +<div class="smallexample"> +<pre class="smallexample">#assert <var>predicate</var> (<var>answer</var>) +</pre></div> + +<p>You may make several assertions with the same predicate and different +answers. Subsequent assertions do not override previous ones for the +same predicate. All the answers for any given predicate are +simultaneously true. +</p> +<a name="index-assertions_002c-canceling"></a> +<a name="index-_0023unassert"></a> +<p>Assertions can be canceled with the ‘<samp>#unassert</samp>’ directive. It +has the same syntax as ‘<samp>#assert</samp>’. In that form it cancels only the +answer which was specified on the ‘<samp>#unassert</samp>’ line; other answers +for that predicate remain true. You can cancel an entire predicate by +leaving out the answer: +</p> +<div class="smallexample"> +<pre class="smallexample">#unassert <var>predicate</var> +</pre></div> + +<p>In either form, if no such assertion has been made, ‘<samp>#unassert</samp>’ has +no effect. +</p> +<p>You can also make or cancel assertions using command-line options. +See <a href="Invocation.html#Invocation">Invocation</a>. +</p> +<hr> +<div class="header"> +<p> +Previous: <a href="Implementation-limits.html#Implementation-limits" accesskey="p" rel="previous">Implementation limits</a>, Up: <a href="Implementation-Details.html#Implementation-Details" accesskey="u" rel="up">Implementation Details</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Once_002dOnly-Headers.html b/share/doc/cpp/Once_002dOnly-Headers.html new file mode 100644 index 0000000..612b60d --- /dev/null +++ b/share/doc/cpp/Once_002dOnly-Headers.html @@ -0,0 +1,134 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Once-Only Headers</title> + +<meta name="description" content="The C Preprocessor: Once-Only Headers"> +<meta name="keywords" content="The C Preprocessor: Once-Only Headers"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Header-Files.html#Header-Files" rel="up" title="Header Files"> +<link href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef" rel="next" title="Alternatives to Wrapper #ifndef"> +<link href="Search-Path.html#Search-Path" rel="previous" title="Search Path"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Once_002dOnly-Headers"></a> +<div class="header"> +<p> +Next: <a href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef" accesskey="n" rel="next">Alternatives to Wrapper #ifndef</a>, Previous: <a href="Search-Path.html#Search-Path" accesskey="p" rel="previous">Search Path</a>, Up: <a href="Header-Files.html#Header-Files" accesskey="u" rel="up">Header Files</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Once_002dOnly-Headers-1"></a> +<h3 class="section">2.4 Once-Only Headers</h3> +<a name="index-repeated-inclusion"></a> +<a name="index-including-just-once"></a> +<a name="index-wrapper-_0023ifndef"></a> + +<p>If a header file happens to be included twice, the compiler will process +its contents twice. This is very likely to cause an error, e.g. when the +compiler sees the same structure definition twice. Even if it does not, +it will certainly waste time. +</p> +<p>The standard way to prevent this is to enclose the entire real contents +of the file in a conditional, like this: +</p> +<div class="smallexample"> +<pre class="smallexample">/* File foo. */ +#ifndef FILE_FOO_SEEN +#define FILE_FOO_SEEN + +<var>the entire file</var> + +#endif /* !FILE_FOO_SEEN */ +</pre></div> + +<p>This construct is commonly known as a <em>wrapper #ifndef</em>. +When the header is included again, the conditional will be false, +because <code>FILE_FOO_SEEN</code> is defined. The preprocessor will skip +over the entire contents of the file, and the compiler will not see it +twice. +</p> +<p>CPP optimizes even further. It remembers when a header file has a +wrapper ‘<samp>#ifndef</samp>’. If a subsequent ‘<samp>#include</samp>’ specifies that +header, and the macro in the ‘<samp>#ifndef</samp>’ is still defined, it does +not bother to rescan the file at all. +</p> +<p>You can put comments outside the wrapper. They will not interfere with +this optimization. +</p> +<a name="index-controlling-macro"></a> +<a name="index-guard-macro"></a> +<p>The macro <code>FILE_FOO_SEEN</code> is called the <em>controlling macro</em> or +<em>guard macro</em>. In a user header file, the macro name should not +begin with ‘<samp>_</samp>’. In a system header file, it should begin with +‘<samp>__</samp>’ to avoid conflicts with user programs. In any kind of header +file, the macro name should contain the name of the file and some +additional text, to avoid conflicts with other header files. +</p> +<hr> +<div class="header"> +<p> +Next: <a href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef" accesskey="n" rel="next">Alternatives to Wrapper #ifndef</a>, Previous: <a href="Search-Path.html#Search-Path" accesskey="p" rel="previous">Search Path</a>, Up: <a href="Header-Files.html#Header-Files" accesskey="u" rel="up">Header Files</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Operator-Precedence-Problems.html b/share/doc/cpp/Operator-Precedence-Problems.html new file mode 100644 index 0000000..7daed27 --- /dev/null +++ b/share/doc/cpp/Operator-Precedence-Problems.html @@ -0,0 +1,153 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Operator Precedence Problems</title> + +<meta name="description" content="The C Preprocessor: Operator Precedence Problems"> +<meta name="keywords" content="The C Preprocessor: Operator Precedence Problems"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Macro-Pitfalls.html#Macro-Pitfalls" rel="up" title="Macro Pitfalls"> +<link href="Swallowing-the-Semicolon.html#Swallowing-the-Semicolon" rel="next" title="Swallowing the Semicolon"> +<link href="Misnesting.html#Misnesting" rel="previous" title="Misnesting"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Operator-Precedence-Problems"></a> +<div class="header"> +<p> +Next: <a href="Swallowing-the-Semicolon.html#Swallowing-the-Semicolon" accesskey="n" rel="next">Swallowing the Semicolon</a>, Previous: <a href="Misnesting.html#Misnesting" accesskey="p" rel="previous">Misnesting</a>, Up: <a href="Macro-Pitfalls.html#Macro-Pitfalls" accesskey="u" rel="up">Macro Pitfalls</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Operator-Precedence-Problems-1"></a> +<h4 class="subsection">3.10.2 Operator Precedence Problems</h4> +<a name="index-parentheses-in-macro-bodies"></a> + +<p>You may have noticed that in most of the macro definition examples shown +above, each occurrence of a macro argument name had parentheses around +it. In addition, another pair of parentheses usually surround the +entire macro definition. Here is why it is best to write macros that +way. +</p> +<p>Suppose you define a macro as follows, +</p> +<div class="smallexample"> +<pre class="smallexample">#define ceil_div(x, y) (x + y - 1) / y +</pre></div> + +<p>whose purpose is to divide, rounding up. (One use for this operation is +to compute how many <code>int</code> objects are needed to hold a certain +number of <code>char</code> objects.) Then suppose it is used as follows: +</p> +<div class="smallexample"> +<pre class="smallexample">a = ceil_div (b & c, sizeof (int)); + → a = (b & c + sizeof (int) - 1) / sizeof (int); +</pre></div> + +<p>This does not do what is intended. The operator-precedence rules of +C make it equivalent to this: +</p> +<div class="smallexample"> +<pre class="smallexample">a = (b & (c + sizeof (int) - 1)) / sizeof (int); +</pre></div> + +<p>What we want is this: +</p> +<div class="smallexample"> +<pre class="smallexample">a = ((b & c) + sizeof (int) - 1)) / sizeof (int); +</pre></div> + +<p>Defining the macro as +</p> +<div class="smallexample"> +<pre class="smallexample">#define ceil_div(x, y) ((x) + (y) - 1) / (y) +</pre></div> + +<p>provides the desired result. +</p> +<p>Unintended grouping can result in another way. Consider <code>sizeof +ceil_div(1, 2)</code>. That has the appearance of a C expression that would +compute the size of the type of <code>ceil_div (1, 2)</code>, but in fact it +means something very different. Here is what it expands to: +</p> +<div class="smallexample"> +<pre class="smallexample">sizeof ((1) + (2) - 1) / (2) +</pre></div> + +<p>This would take the size of an integer and divide it by two. The +precedence rules have put the division outside the <code>sizeof</code> when it +was intended to be inside. +</p> +<p>Parentheses around the entire macro definition prevent such problems. +Here, then, is the recommended way to define <code>ceil_div</code>: +</p> +<div class="smallexample"> +<pre class="smallexample">#define ceil_div(x, y) (((x) + (y) - 1) / (y)) +</pre></div> + +<hr> +<div class="header"> +<p> +Next: <a href="Swallowing-the-Semicolon.html#Swallowing-the-Semicolon" accesskey="n" rel="next">Swallowing the Semicolon</a>, Previous: <a href="Misnesting.html#Misnesting" accesskey="p" rel="previous">Misnesting</a>, Up: <a href="Macro-Pitfalls.html#Macro-Pitfalls" accesskey="u" rel="up">Macro Pitfalls</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Option-Index.html b/share/doc/cpp/Option-Index.html new file mode 100644 index 0000000..841f0b6 --- /dev/null +++ b/share/doc/cpp/Option-Index.html @@ -0,0 +1,262 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Option Index</title> + +<meta name="description" content="The C Preprocessor: Option Index"> +<meta name="keywords" content="The C Preprocessor: Option Index"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html#Top" rel="up" title="Top"> +<link href="Concept-Index.html#Concept-Index" rel="next" title="Concept Index"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="previous" title="Index of Directives"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Option-Index"></a> +<div class="header"> +<p> +Next: <a href="Concept-Index.html#Concept-Index" accesskey="n" rel="next">Concept Index</a>, Previous: <a href="Index-of-Directives.html#Index-of-Directives" accesskey="p" rel="previous">Index of Directives</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Option-Index-1"></a> +<h2 class="unnumbered">Option Index</h2> +<p>CPP’s command-line options and environment variables are indexed here +without any initial ‘<samp>-</samp>’ or ‘<samp>--</samp>’. +</p><table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Option-Index_op_letter-A"><b>A</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-C"><b>C</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-D"><b>D</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-F"><b>F</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-H"><b>H</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-I"><b>I</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-M"><b>M</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-N"><b>N</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-O"><b>O</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-P"><b>P</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-R"><b>R</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-S"><b>S</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-T"><b>T</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-U"><b>U</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-W"><b>W</b></a> + +</td></tr></table> +<table class="index-op" border="0"> +<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Option-Index_op_letter-A">A</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-A"><code>A</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Option-Index_op_letter-C">C</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-C"><code>C</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-CC"><code>CC</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Environment-Variables.html#index-CPATH"><code>CPATH</code></a>:</td><td> </td><td valign="top"><a href="Environment-Variables.html#Environment-Variables">Environment Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="Environment-Variables.html#index-CPLUS_005fINCLUDE_005fPATH"><code>CPLUS_INCLUDE_PATH</code></a>:</td><td> </td><td valign="top"><a href="Environment-Variables.html#Environment-Variables">Environment Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="Environment-Variables.html#index-C_005fINCLUDE_005fPATH"><code>C_INCLUDE_PATH</code></a>:</td><td> </td><td valign="top"><a href="Environment-Variables.html#Environment-Variables">Environment Variables</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Option-Index_op_letter-D">D</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-D"><code>D</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-d"><code>d</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-dD"><code>dD</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Environment-Variables.html#index-DEPENDENCIES_005fOUTPUT"><code>DEPENDENCIES_OUTPUT</code></a>:</td><td> </td><td valign="top"><a href="Environment-Variables.html#Environment-Variables">Environment Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-dI"><code>dI</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-dM"><code>dM</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-dN"><code>dN</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-dU"><code>dU</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Option-Index_op_letter-F">F</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-fdebug_002dcpp"><code>fdebug-cpp</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-fdirectives_002donly"><code>fdirectives-only</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-fdollars_002din_002didentifiers"><code>fdollars-in-identifiers</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-fexec_002dcharset"><code>fexec-charset</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-fextended_002didentifiers"><code>fextended-identifiers</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-finput_002dcharset"><code>finput-charset</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-fmacro_002dprefix_002dmap"><code>fmacro-prefix-map</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-fmax_002dinclude_002ddepth"><code>fmax-include-depth</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-fno_002dcanonical_002dsystem_002dheaders"><code>fno-canonical-system-headers</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-fno_002dworking_002ddirectory"><code>fno-working-directory</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-fpreprocessed"><code>fpreprocessed</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-ftabstop"><code>ftabstop</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-ftrack_002dmacro_002dexpansion"><code>ftrack-macro-expansion</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-fwide_002dexec_002dcharset"><code>fwide-exec-charset</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-fworking_002ddirectory"><code>fworking-directory</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Option-Index_op_letter-H">H</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-H"><code>H</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Option-Index_op_letter-I">I</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-I"><code>I</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-I_002d"><code>I-</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-idirafter"><code>idirafter</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-imacros"><code>imacros</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-imultilib"><code>imultilib</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-include"><code>include</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-iprefix"><code>iprefix</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-iquote"><code>iquote</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-isysroot"><code>isysroot</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-isystem"><code>isystem</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-iwithprefix"><code>iwithprefix</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-iwithprefixbefore"><code>iwithprefixbefore</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Option-Index_op_letter-M">M</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-M"><code>M</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-MD"><code>MD</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-MF"><code>MF</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-MG"><code>MG</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-MM"><code>MM</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-MMD"><code>MMD</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-Mno_002dmodules"><code>Mno-modules</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-MP"><code>MP</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-MQ"><code>MQ</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-MT"><code>MT</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Option-Index_op_letter-N">N</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-nostdinc"><code>nostdinc</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-nostdinc_002b_002b"><code>nostdinc++</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Option-Index_op_letter-O">O</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Environment-Variables.html#index-OBJC_005fINCLUDE_005fPATH"><code>OBJC_INCLUDE_PATH</code></a>:</td><td> </td><td valign="top"><a href="Environment-Variables.html#Environment-Variables">Environment Variables</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Option-Index_op_letter-P">P</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-P"><code>P</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-pthread"><code>pthread</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Option-Index_op_letter-R">R</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-remap"><code>remap</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Option-Index_op_letter-S">S</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Environment-Variables.html#index-SOURCE_005fDATE_005fEPOCH"><code>SOURCE_DATE_EPOCH</code></a>:</td><td> </td><td valign="top"><a href="Environment-Variables.html#Environment-Variables">Environment Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="Environment-Variables.html#index-SUNPRO_005fDEPENDENCIES"><code>SUNPRO_DEPENDENCIES</code></a>:</td><td> </td><td valign="top"><a href="Environment-Variables.html#Environment-Variables">Environment Variables</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Option-Index_op_letter-T">T</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-traditional"><code>traditional</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-traditional_002dcpp"><code>traditional-cpp</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-trigraphs-1"><code>trigraphs</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Option-Index_op_letter-U">U</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-U"><code>U</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-undef"><code>undef</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Option-Index_op_letter-W">W</a></th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-Wcomment"><code>Wcomment</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-Wcomments"><code>Wcomments</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-Wendif_002dlabels"><code>Wendif-labels</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-Wexpansion_002dto_002ddefined"><code>Wexpansion-to-defined</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-Wno_002dendif_002dlabels"><code>Wno-endif-labels</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-Wno_002dundef"><code>Wno-undef</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-Wtrigraphs"><code>Wtrigraphs</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-Wundef"><code>Wundef</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td></td><td valign="top"><a href="Invocation.html#index-Wunused_002dmacros"><code>Wunused-macros</code></a>:</td><td> </td><td valign="top"><a href="Invocation.html#Invocation">Invocation</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +</table> +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Option-Index_op_letter-A"><b>A</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-C"><b>C</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-D"><b>D</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-F"><b>F</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-H"><b>H</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-I"><b>I</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-M"><b>M</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-N"><b>N</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-O"><b>O</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-P"><b>P</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-R"><b>R</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-S"><b>S</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-T"><b>T</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-U"><b>U</b></a> + +<a class="summary-letter" href="#Option-Index_op_letter-W"><b>W</b></a> + +</td></tr></table> + +<hr> +<div class="header"> +<p> +Next: <a href="Concept-Index.html#Concept-Index" accesskey="n" rel="next">Concept Index</a>, Previous: <a href="Index-of-Directives.html#Index-of-Directives" accesskey="p" rel="previous">Index of Directives</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Other-Directives.html b/share/doc/cpp/Other-Directives.html new file mode 100644 index 0000000..d55104d --- /dev/null +++ b/share/doc/cpp/Other-Directives.html @@ -0,0 +1,105 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Other Directives</title> + +<meta name="description" content="The C Preprocessor: Other Directives"> +<meta name="keywords" content="The C Preprocessor: Other Directives"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html#Top" rel="up" title="Top"> +<link href="Preprocessor-Output.html#Preprocessor-Output" rel="next" title="Preprocessor Output"> +<link href="Pragmas.html#Pragmas" rel="previous" title="Pragmas"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Other-Directives"></a> +<div class="header"> +<p> +Next: <a href="Preprocessor-Output.html#Preprocessor-Output" accesskey="n" rel="next">Preprocessor Output</a>, Previous: <a href="Pragmas.html#Pragmas" accesskey="p" rel="previous">Pragmas</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Other-Directives-1"></a> +<h2 class="chapter">8 Other Directives</h2> + +<a name="index-_0023ident"></a> +<a name="index-_0023sccs"></a> +<p>The ‘<samp>#ident</samp>’ directive takes one argument, a string constant. On +some systems, that string constant is copied into a special segment of +the object file. On other systems, the directive is ignored. The +‘<samp>#sccs</samp>’ directive is a synonym for ‘<samp>#ident</samp>’. +</p> +<p>These directives are not part of the C standard, but they are not +official GNU extensions either. What historical information we have +been able to find, suggests they originated with System V. +</p> +<a name="index-null-directive"></a> +<p>The <em>null directive</em> consists of a ‘<samp>#</samp>’ followed by a newline, +with only whitespace (including comments) in between. A null directive +is understood as a preprocessing directive but has no effect on the +preprocessor output. The primary significance of the existence of the +null directive is that an input line consisting of just a ‘<samp>#</samp>’ will +produce no output, rather than a line of output containing just a +‘<samp>#</samp>’. Supposedly some old C programs contain such lines. +</p> + + + +</body> +</html> diff --git a/share/doc/cpp/Overview.html b/share/doc/cpp/Overview.html new file mode 100644 index 0000000..f7b8a91 --- /dev/null +++ b/share/doc/cpp/Overview.html @@ -0,0 +1,148 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Overview</title> + +<meta name="description" content="The C Preprocessor: Overview"> +<meta name="keywords" content="The C Preprocessor: Overview"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html#Top" rel="up" title="Top"> +<link href="Character-sets.html#Character-sets" rel="next" title="Character sets"> +<link href="index.html#Top" rel="previous" title="Top"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Overview"></a> +<div class="header"> +<p> +Next: <a href="Header-Files.html#Header-Files" accesskey="n" rel="next">Header Files</a>, Previous: <a href="index.html#Top" accesskey="p" rel="previous">Top</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Overview-1"></a> +<h2 class="chapter">1 Overview</h2> +<p>The C preprocessor, often known as <em>cpp</em>, is a <em>macro processor</em> +that is used automatically by the C compiler to transform your program +before compilation. It is called a macro processor because it allows +you to define <em>macros</em>, which are brief abbreviations for longer +constructs. +</p> +<p>The C preprocessor is intended to be used only with C, C++, and +Objective-C source code. In the past, it has been abused as a general +text processor. It will choke on input which does not obey C’s lexical +rules. For example, apostrophes will be interpreted as the beginning of +character constants, and cause errors. Also, you cannot rely on it +preserving characteristics of the input which are not significant to +C-family languages. If a Makefile is preprocessed, all the hard tabs +will be removed, and the Makefile will not work. +</p> +<p>Having said that, you can often get away with using cpp on things which +are not C. Other Algol-ish programming languages are often safe +(Ada, etc.) So is assembly, with caution. <samp>-traditional-cpp</samp> +mode preserves more white space, and is otherwise more permissive. Many +of the problems can be avoided by writing C or C++ style comments +instead of native language comments, and keeping macros simple. +</p> +<p>Wherever possible, you should use a preprocessor geared to the language +you are writing in. Modern versions of the GNU assembler have macro +facilities. Most high level programming languages have their own +conditional compilation and inclusion mechanism. If all else fails, +try a true general text processor, such as GNU M4. +</p> +<p>C preprocessors vary in some details. This manual discusses the GNU C +preprocessor, which provides a small superset of the features of ISO +Standard C. In its default mode, the GNU C preprocessor does not do a +few things required by the standard. These are features which are +rarely, if ever, used, and may cause surprising changes to the meaning +of a program which does not expect them. To get strict ISO Standard C, +you should use the <samp>-std=c90</samp>, <samp>-std=c99</samp>, +<samp>-std=c11</samp> or <samp>-std=c17</samp> options, depending +on which version of the standard you want. To get all the mandatory +diagnostics, you must also use <samp>-pedantic</samp>. See <a href="Invocation.html#Invocation">Invocation</a>. +</p> +<p>This manual describes the behavior of the ISO preprocessor. To +minimize gratuitous differences, where the ISO preprocessor’s +behavior does not conflict with traditional semantics, the +traditional preprocessor should behave the same way. The various +differences that do exist are detailed in the section <a href="Traditional-Mode.html#Traditional-Mode">Traditional Mode</a>. +</p> +<p>For clarity, unless noted otherwise, references to ‘<samp>CPP</samp>’ in this +manual refer to GNU CPP. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="Character-sets.html#Character-sets" accesskey="1">Character sets</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Initial-processing.html#Initial-processing" accesskey="2">Initial processing</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Tokenization.html#Tokenization" accesskey="3">Tokenization</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="The-preprocessing-language.html#The-preprocessing-language" accesskey="4">The preprocessing language</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +</table> + +<hr> +<div class="header"> +<p> +Next: <a href="Header-Files.html#Header-Files" accesskey="n" rel="next">Header Files</a>, Previous: <a href="index.html#Top" accesskey="p" rel="previous">Top</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Pragmas.html b/share/doc/cpp/Pragmas.html new file mode 100644 index 0000000..3aa7f4b --- /dev/null +++ b/share/doc/cpp/Pragmas.html @@ -0,0 +1,231 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Pragmas</title> + +<meta name="description" content="The C Preprocessor: Pragmas"> +<meta name="keywords" content="The C Preprocessor: Pragmas"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html#Top" rel="up" title="Top"> +<link href="Other-Directives.html#Other-Directives" rel="next" title="Other Directives"> +<link href="Line-Control.html#Line-Control" rel="previous" title="Line Control"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Pragmas"></a> +<div class="header"> +<p> +Next: <a href="Other-Directives.html#Other-Directives" accesskey="n" rel="next">Other Directives</a>, Previous: <a href="Line-Control.html#Line-Control" accesskey="p" rel="previous">Line Control</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Pragmas-1"></a> +<h2 class="chapter">7 Pragmas</h2> + +<a name="index-pragma-directive"></a> + +<p>The ‘<samp>#pragma</samp>’ directive is the method specified by the C standard +for providing additional information to the compiler, beyond what is +conveyed in the language itself. The forms of this directive +(commonly known as <em>pragmas</em>) specified by C standard are prefixed with +<code>STDC</code>. A C compiler is free to attach any meaning it likes to other +pragmas. Most GNU-defined, supported pragmas have been given a +<code>GCC</code> prefix. +</p> +<a name="index-_005fPragma"></a> +<p>C99 introduced the <code><span class="nolinebreak">_Pragma</span><!-- /@w --></code> operator. This feature addresses a +major problem with ‘<samp>#pragma</samp>’: being a directive, it cannot be +produced as the result of macro expansion. <code><span class="nolinebreak">_Pragma</span><!-- /@w --></code> is an +operator, much like <code>sizeof</code> or <code>defined</code>, and can be embedded +in a macro. +</p> +<p>Its syntax is <code><span class="nolinebreak">_Pragma</span> (<var><span class="nolinebreak">string-literal</span></var>)<!-- /@w --></code>, where +<var>string-literal</var> can be either a normal or wide-character string +literal. It is destringized, by replacing all ‘<samp>\\</samp>’ with a single +‘<samp>\</samp>’ and all ‘<samp>\"</samp>’ with a ‘<samp>"</samp>’. The result is then +processed as if it had appeared as the right hand side of a +‘<samp>#pragma</samp>’ directive. For example, +</p> +<div class="smallexample"> +<pre class="smallexample">_Pragma ("GCC dependency \"parse.y\"") +</pre></div> + +<p>has the same effect as <code>#pragma GCC dependency "parse.y"</code>. The +same effect could be achieved using macros, for example +</p> +<div class="smallexample"> +<pre class="smallexample">#define DO_PRAGMA(x) _Pragma (#x) +DO_PRAGMA (GCC dependency "parse.y") +</pre></div> + +<p>The standard is unclear on where a <code>_Pragma</code> operator can appear. +The preprocessor does not accept it within a preprocessing conditional +directive like ‘<samp>#if</samp>’. To be safe, you are probably best keeping it +out of directives other than ‘<samp>#define</samp>’, and putting it on a line of +its own. +</p> +<p>This manual documents the pragmas which are meaningful to the +preprocessor itself. Other pragmas are meaningful to the C or C++ +compilers. They are documented in the GCC manual. +</p> +<p>GCC plugins may provide their own pragmas. +</p> +<dl compact="compact"> +<dt><code>#pragma GCC dependency</code> +<a name="index-_0023pragma-GCC-dependency"></a> +</dt> +<dd><p><code>#pragma GCC dependency</code> allows you to check the relative dates of +the current file and another file. If the other file is more recent than +the current file, a warning is issued. This is useful if the current +file is derived from the other file, and should be regenerated. The +other file is searched for using the normal include search path. +Optional trailing text can be used to give more information in the +warning message. +</p> +<div class="smallexample"> +<pre class="smallexample">#pragma GCC dependency "parse.y" +#pragma GCC dependency "/usr/include/time.h" rerun fixincludes +</pre></div> + +</dd> +<dt><code>#pragma GCC poison</code> +<a name="index-_0023pragma-GCC-poison"></a> +</dt> +<dd><p>Sometimes, there is an identifier that you want to remove completely +from your program, and make sure that it never creeps back in. To +enforce this, you can <em>poison</em> the identifier with this pragma. +<code>#pragma GCC poison</code> is followed by a list of identifiers to +poison. If any of those identifiers appears anywhere in the source +after the directive, it is a hard error. For example, +</p> +<div class="smallexample"> +<pre class="smallexample">#pragma GCC poison printf sprintf fprintf +sprintf(some_string, "hello"); +</pre></div> + +<p>will produce an error. +</p> +<p>If a poisoned identifier appears as part of the expansion of a macro +which was defined before the identifier was poisoned, it will <em>not</em> +cause an error. This lets you poison an identifier without worrying +about system headers defining macros that use it. +</p> +<p>For example, +</p> +<div class="smallexample"> +<pre class="smallexample">#define strrchr rindex +#pragma GCC poison rindex +strrchr(some_string, 'h'); +</pre></div> + +<p>will not produce an error. +</p> +</dd> +<dt><code>#pragma GCC system_header</code> +<a name="index-_0023pragma-GCC-system_005fheader-1"></a> +</dt> +<dd><p>This pragma takes no arguments. It causes the rest of the code in the +current file to be treated as if it came from a system header. +See <a href="System-Headers.html#System-Headers">System Headers</a>. +</p> +</dd> +<dt><code>#pragma GCC warning</code> +<a name="index-_0023pragma-GCC-warning"></a> +</dt> +<dt><code>#pragma GCC error</code> +<a name="index-_0023pragma-GCC-error"></a> +</dt> +<dd><p><code>#pragma GCC warning "message"</code> causes the preprocessor to issue +a warning diagnostic with the text ‘<samp>message</samp>’. The message +contained in the pragma must be a single string literal. Similarly, +<code>#pragma GCC error "message"</code> issues an error message. Unlike +the ‘<samp>#warning</samp>’ and ‘<samp>#error</samp>’ directives, these pragmas can be +embedded in preprocessor macros using ‘<samp>_Pragma</samp>’. +</p> +</dd> +<dt><code>#pragma once</code> +<a name="index-_0023pragma-once"></a> +</dt> +<dd><p>If <code>#pragma once</code> is seen when scanning a header file, that +file will never be read again, no matter what. It is a less-portable +alternative to using ‘<samp>#ifndef</samp>’ to guard the contents of header files +against multiple inclusions. +</p> +</dd> +<dt><code>#pragma region {tokens}...</code> +<a name="index-_0023pragma-region-_007btokens_007d_002e_002e_002e"></a> +</dt> +<dt><code>#pragma endregion {tokens}...</code> +<a name="index-_0023pragma-endregion-_007btokens_007d_002e_002e_002e"></a> +</dt> +<dd><p>These pragmas are accepted, but have no effect. +</p> +</dd> +</dl> + +<hr> +<div class="header"> +<p> +Next: <a href="Other-Directives.html#Other-Directives" accesskey="n" rel="next">Other Directives</a>, Previous: <a href="Line-Control.html#Line-Control" accesskey="p" rel="previous">Line Control</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Predefined-Macros.html b/share/doc/cpp/Predefined-Macros.html new file mode 100644 index 0000000..ac1d568 --- /dev/null +++ b/share/doc/cpp/Predefined-Macros.html @@ -0,0 +1,104 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Predefined Macros</title> + +<meta name="description" content="The C Preprocessor: Predefined Macros"> +<meta name="keywords" content="The C Preprocessor: Predefined Macros"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Macros.html#Macros" rel="up" title="Macros"> +<link href="Standard-Predefined-Macros.html#Standard-Predefined-Macros" rel="next" title="Standard Predefined Macros"> +<link href="Variadic-Macros.html#Variadic-Macros" rel="previous" title="Variadic Macros"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Predefined-Macros"></a> +<div class="header"> +<p> +Next: <a href="Undefining-and-Redefining-Macros.html#Undefining-and-Redefining-Macros" accesskey="n" rel="next">Undefining and Redefining Macros</a>, Previous: <a href="Variadic-Macros.html#Variadic-Macros" accesskey="p" rel="previous">Variadic Macros</a>, Up: <a href="Macros.html#Macros" accesskey="u" rel="up">Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Predefined-Macros-1"></a> +<h3 class="section">3.7 Predefined Macros</h3> + +<a name="index-predefined-macros"></a> +<p>Several object-like macros are predefined; you use them without +supplying their definitions. They fall into three classes: standard, +common, and system-specific. +</p> +<p>In C++, there is a fourth category, the named operators. They act like +predefined macros, but you cannot undefine them. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="Standard-Predefined-Macros.html#Standard-Predefined-Macros" accesskey="1">Standard Predefined Macros</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Common-Predefined-Macros.html#Common-Predefined-Macros" accesskey="2">Common Predefined Macros</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="System_002dspecific-Predefined-Macros.html#System_002dspecific-Predefined-Macros" accesskey="3">System-specific Predefined Macros</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="C_002b_002b-Named-Operators.html#C_002b_002b-Named-Operators" accesskey="4">C++ Named Operators</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +</table> + + + + +</body> +</html> diff --git a/share/doc/cpp/Preprocessor-Output.html b/share/doc/cpp/Preprocessor-Output.html new file mode 100644 index 0000000..7ee5fcd --- /dev/null +++ b/share/doc/cpp/Preprocessor-Output.html @@ -0,0 +1,164 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Preprocessor Output</title> + +<meta name="description" content="The C Preprocessor: Preprocessor Output"> +<meta name="keywords" content="The C Preprocessor: Preprocessor Output"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html#Top" rel="up" title="Top"> +<link href="Traditional-Mode.html#Traditional-Mode" rel="next" title="Traditional Mode"> +<link href="Other-Directives.html#Other-Directives" rel="previous" title="Other Directives"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Preprocessor-Output"></a> +<div class="header"> +<p> +Next: <a href="Traditional-Mode.html#Traditional-Mode" accesskey="n" rel="next">Traditional Mode</a>, Previous: <a href="Other-Directives.html#Other-Directives" accesskey="p" rel="previous">Other Directives</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Preprocessor-Output-1"></a> +<h2 class="chapter">9 Preprocessor Output</h2> + +<p>When the C preprocessor is used with the C, C++, or Objective-C +compilers, it is integrated into the compiler and communicates a stream +of binary tokens directly to the compiler’s parser. However, it can +also be used in the more conventional standalone mode, where it produces +textual output. +</p> +<a name="index-output-format"></a> +<p>The output from the C preprocessor looks much like the input, except +that all preprocessing directive lines have been replaced with blank +lines and all comments with spaces. Long runs of blank lines are +discarded. +</p> +<p>The ISO standard specifies that it is implementation defined whether a +preprocessor preserves whitespace between tokens, or replaces it with +e.g. a single space. In GNU CPP, whitespace between tokens is collapsed +to become a single space, with the exception that the first token on a +non-directive line is preceded with sufficient spaces that it appears in +the same column in the preprocessed output that it appeared in the +original source file. This is so the output is easy to read. +CPP does not insert any +whitespace where there was none in the original source, except where +necessary to prevent an accidental token paste. +</p> +<a name="index-linemarkers"></a> +<p>Source file name and line number information is conveyed by lines +of the form +</p> +<div class="smallexample"> +<pre class="smallexample"># <var>linenum</var> <var>filename</var> <var>flags</var> +</pre></div> + +<p>These are called <em>linemarkers</em>. They are inserted as needed into +the output (but never within a string or character constant). They mean +that the following line originated in file <var>filename</var> at line +<var>linenum</var>. <var>filename</var> will never contain any non-printing +characters; they are replaced with octal escape sequences. +</p> +<p>After the file name comes zero or more flags, which are ‘<samp>1</samp>’, +‘<samp>2</samp>’, ‘<samp>3</samp>’, or ‘<samp>4</samp>’. If there are multiple flags, spaces +separate them. Here is what the flags mean: +</p> +<dl compact="compact"> +<dt>‘<samp>1</samp>’</dt> +<dd><p>This indicates the start of a new file. +</p></dd> +<dt>‘<samp>2</samp>’</dt> +<dd><p>This indicates returning to a file (after having included another file). +</p></dd> +<dt>‘<samp>3</samp>’</dt> +<dd><p>This indicates that the following text comes from a system header file, +so certain warnings should be suppressed. +</p></dd> +<dt>‘<samp>4</samp>’</dt> +<dd><p>This indicates that the following text should be treated as being +wrapped in an implicit <code>extern "C"</code> block. +</p></dd> +</dl> + +<p>As an extension, the preprocessor accepts linemarkers in non-assembler +input files. They are treated like the corresponding ‘<samp>#line</samp>’ +directive, (see <a href="Line-Control.html#Line-Control">Line Control</a>), except that trailing flags are +permitted, and are interpreted with the meanings described above. If +multiple flags are given, they must be in ascending order. +</p> +<p>Some directives may be duplicated in the output of the preprocessor. +These are ‘<samp>#ident</samp>’ (always), ‘<samp>#pragma</samp>’ (only if the +preprocessor does not handle the pragma itself), and ‘<samp>#define</samp>’ and +‘<samp>#undef</samp>’ (with certain debugging options). If this happens, the +‘<samp>#</samp>’ of the directive will always be in the first column, and there +will be no space between the ‘<samp>#</samp>’ and the directive name. If macro +expansion happens to generate tokens which might be mistaken for a +duplicated directive, a space will be inserted between the ‘<samp>#</samp>’ and +the directive name. +</p> +<hr> +<div class="header"> +<p> +Next: <a href="Traditional-Mode.html#Traditional-Mode" accesskey="n" rel="next">Traditional Mode</a>, Previous: <a href="Other-Directives.html#Other-Directives" accesskey="p" rel="previous">Other Directives</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Search-Path.html b/share/doc/cpp/Search-Path.html new file mode 100644 index 0000000..8ccecbc --- /dev/null +++ b/share/doc/cpp/Search-Path.html @@ -0,0 +1,134 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Search Path</title> + +<meta name="description" content="The C Preprocessor: Search Path"> +<meta name="keywords" content="The C Preprocessor: Search Path"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Header-Files.html#Header-Files" rel="up" title="Header Files"> +<link href="Once_002dOnly-Headers.html#Once_002dOnly-Headers" rel="next" title="Once-Only Headers"> +<link href="Include-Operation.html#Include-Operation" rel="previous" title="Include Operation"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Search-Path"></a> +<div class="header"> +<p> +Next: <a href="Once_002dOnly-Headers.html#Once_002dOnly-Headers" accesskey="n" rel="next">Once-Only Headers</a>, Previous: <a href="Include-Operation.html#Include-Operation" accesskey="p" rel="previous">Include Operation</a>, Up: <a href="Header-Files.html#Header-Files" accesskey="u" rel="up">Header Files</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Search-Path-1"></a> +<h3 class="section">2.3 Search Path</h3> + +<p>By default, the preprocessor looks for header files included by the quote +form of the directive <code>#include "<var>file</var>"<!-- /@w --></code> first relative to +the directory of the current file, and then in a preconfigured list +of standard system directories. +For example, if <samp>/usr/include/sys/stat.h</samp> contains +<code>#include "types.h"<!-- /@w --></code>, GCC looks for <samp>types.h</samp> first in +<samp>/usr/include/sys</samp>, then in its usual search path. +</p> +<p>For the angle-bracket form <code>#include <<var>file</var>><!-- /@w --></code>, the +preprocessor’s default behavior is to look only in the standard system +directories. The exact search directory list depends on the target +system, how GCC is configured, and where it is installed. You can +find the default search directory list for your version of CPP by +invoking it with the <samp>-v</samp> option. For example, +</p> +<div class="smallexample"> +<pre class="smallexample">cpp -v /dev/null -o /dev/null +</pre></div> + +<p>There are a number of command-line options you can use to add +additional directories to the search path. +The most commonly-used option is <samp>-I<var>dir</var></samp>, which causes +<var>dir</var> to be searched after the current directory (for the quote +form of the directive) and ahead of the standard system directories. +You can specify multiple <samp>-I</samp> options on the command line, +in which case the directories are searched in left-to-right order. +</p> +<p>If you need separate control over the search paths for the quote and +angle-bracket forms of the ‘<samp>#include</samp>’ directive, you can use the +<samp>-iquote</samp> and/or <samp>-isystem</samp> options instead of <samp>-I</samp>. +See <a href="Invocation.html#Invocation">Invocation</a>, for a detailed description of these options, as +well as others that are less generally useful. +</p> +<p>If you specify other options on the command line, such as <samp>-I</samp>, +that affect where the preprocessor searches for header files, the +directory list printed by the <samp>-v</samp> option reflects the actual +search path used by the preprocessor. +</p> +<p>Note that you can also prevent the preprocessor from searching any of +the default system header directories with the <samp>-nostdinc</samp> +option. This is useful when you are compiling an operating system +kernel or some other program that does not use the standard C library +facilities, or the standard C library itself. +</p> +<hr> +<div class="header"> +<p> +Next: <a href="Once_002dOnly-Headers.html#Once_002dOnly-Headers" accesskey="n" rel="next">Once-Only Headers</a>, Previous: <a href="Include-Operation.html#Include-Operation" accesskey="p" rel="previous">Include Operation</a>, Up: <a href="Header-Files.html#Header-Files" accesskey="u" rel="up">Header Files</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Self_002dReferential-Macros.html b/share/doc/cpp/Self_002dReferential-Macros.html new file mode 100644 index 0000000..e223eaf --- /dev/null +++ b/share/doc/cpp/Self_002dReferential-Macros.html @@ -0,0 +1,155 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Self-Referential Macros</title> + +<meta name="description" content="The C Preprocessor: Self-Referential Macros"> +<meta name="keywords" content="The C Preprocessor: Self-Referential Macros"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Macro-Pitfalls.html#Macro-Pitfalls" rel="up" title="Macro Pitfalls"> +<link href="Argument-Prescan.html#Argument-Prescan" rel="next" title="Argument Prescan"> +<link href="Duplication-of-Side-Effects.html#Duplication-of-Side-Effects" rel="previous" title="Duplication of Side Effects"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Self_002dReferential-Macros"></a> +<div class="header"> +<p> +Next: <a href="Argument-Prescan.html#Argument-Prescan" accesskey="n" rel="next">Argument Prescan</a>, Previous: <a href="Duplication-of-Side-Effects.html#Duplication-of-Side-Effects" accesskey="p" rel="previous">Duplication of Side Effects</a>, Up: <a href="Macro-Pitfalls.html#Macro-Pitfalls" accesskey="u" rel="up">Macro Pitfalls</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Self_002dReferential-Macros-1"></a> +<h4 class="subsection">3.10.5 Self-Referential Macros</h4> +<a name="index-self_002dreference"></a> + +<p>A <em>self-referential</em> macro is one whose name appears in its +definition. Recall that all macro definitions are rescanned for more +macros to replace. If the self-reference were considered a use of the +macro, it would produce an infinitely large expansion. To prevent this, +the self-reference is not considered a macro call. It is passed into +the preprocessor output unchanged. Consider an example: +</p> +<div class="smallexample"> +<pre class="smallexample">#define foo (4 + foo) +</pre></div> + +<p>where <code>foo</code> is also a variable in your program. +</p> +<p>Following the ordinary rules, each reference to <code>foo</code> will expand +into <code>(4 + foo)</code>; then this will be rescanned and will expand into +<code>(4 + (4 + foo))</code>; and so on until the computer runs out of memory. +</p> +<p>The self-reference rule cuts this process short after one step, at +<code>(4 + foo)</code>. Therefore, this macro definition has the possibly +useful effect of causing the program to add 4 to the value of <code>foo</code> +wherever <code>foo</code> is referred to. +</p> +<p>In most cases, it is a bad idea to take advantage of this feature. A +person reading the program who sees that <code>foo</code> is a variable will +not expect that it is a macro as well. The reader will come across the +identifier <code>foo</code> in the program and think its value should be that +of the variable <code>foo</code>, whereas in fact the value is four greater. +</p> +<p>One common, useful use of self-reference is to create a macro which +expands to itself. If you write +</p> +<div class="smallexample"> +<pre class="smallexample">#define EPERM EPERM +</pre></div> + +<p>then the macro <code>EPERM</code> expands to <code>EPERM</code>. Effectively, it is +left alone by the preprocessor whenever it’s used in running text. You +can tell that it’s a macro with ‘<samp>#ifdef</samp>’. You might do this if you +want to define numeric constants with an <code>enum</code>, but have +‘<samp>#ifdef</samp>’ be true for each constant. +</p> +<p>If a macro <code>x</code> expands to use a macro <code>y</code>, and the expansion of +<code>y</code> refers to the macro <code>x</code>, that is an <em>indirect +self-reference</em> of <code>x</code>. <code>x</code> is not expanded in this case +either. Thus, if we have +</p> +<div class="smallexample"> +<pre class="smallexample">#define x (4 + y) +#define y (2 * x) +</pre></div> + +<p>then <code>x</code> and <code>y</code> expand as follows: +</p> +<div class="smallexample"> +<pre class="smallexample">x → (4 + y) + → (4 + (2 * x)) + +y → (2 * x) + → (2 * (4 + y)) +</pre></div> + +<p>Each macro is expanded when it appears in the definition of the other +macro, but not when it indirectly appears in its own definition. +</p> +<hr> +<div class="header"> +<p> +Next: <a href="Argument-Prescan.html#Argument-Prescan" accesskey="n" rel="next">Argument Prescan</a>, Previous: <a href="Duplication-of-Side-Effects.html#Duplication-of-Side-Effects" accesskey="p" rel="previous">Duplication of Side Effects</a>, Up: <a href="Macro-Pitfalls.html#Macro-Pitfalls" accesskey="u" rel="up">Macro Pitfalls</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Standard-Predefined-Macros.html b/share/doc/cpp/Standard-Predefined-Macros.html new file mode 100644 index 0000000..df3bda8 --- /dev/null +++ b/share/doc/cpp/Standard-Predefined-Macros.html @@ -0,0 +1,240 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Standard Predefined Macros</title> + +<meta name="description" content="The C Preprocessor: Standard Predefined Macros"> +<meta name="keywords" content="The C Preprocessor: Standard Predefined Macros"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Predefined-Macros.html#Predefined-Macros" rel="up" title="Predefined Macros"> +<link href="Common-Predefined-Macros.html#Common-Predefined-Macros" rel="next" title="Common Predefined Macros"> +<link href="Predefined-Macros.html#Predefined-Macros" rel="previous" title="Predefined Macros"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Standard-Predefined-Macros"></a> +<div class="header"> +<p> +Next: <a href="Common-Predefined-Macros.html#Common-Predefined-Macros" accesskey="n" rel="next">Common Predefined Macros</a>, Up: <a href="Predefined-Macros.html#Predefined-Macros" accesskey="u" rel="up">Predefined Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Standard-Predefined-Macros-1"></a> +<h4 class="subsection">3.7.1 Standard Predefined Macros</h4> +<a name="index-standard-predefined-macros_002e"></a> + +<p>The standard predefined macros are specified by the relevant +language standards, so they are available with all compilers that +implement those standards. Older compilers may not provide all of +them. Their names all start with double underscores. +</p> +<dl compact="compact"> +<dt><code>__FILE__</code></dt> +<dd><p>This macro expands to the name of the current input file, in the form of +a C string constant. This is the path by which the preprocessor opened +the file, not the short name specified in ‘<samp>#include</samp>’ or as the +input file name argument. For example, +<code>"/usr/local/include/myheader.h"</code> is a possible expansion of this +macro. +</p> +</dd> +<dt><code>__LINE__</code></dt> +<dd><p>This macro expands to the current input line number, in the form of a +decimal integer constant. While we call it a predefined macro, it’s +a pretty strange macro, since its “definition” changes with each +new line of source code. +</p></dd> +</dl> + +<p><code>__FILE__</code> and <code>__LINE__</code> are useful in generating an error +message to report an inconsistency detected by the program; the message +can state the source line at which the inconsistency was detected. For +example, +</p> +<div class="smallexample"> +<pre class="smallexample">fprintf (stderr, "Internal error: " + "negative string length " + "%d at %s, line %d.", + length, __FILE__, __LINE__); +</pre></div> + +<p>An ‘<samp>#include</samp>’ directive changes the expansions of <code>__FILE__</code> +and <code>__LINE__</code> to correspond to the included file. At the end of +that file, when processing resumes on the input file that contained +the ‘<samp>#include</samp>’ directive, the expansions of <code>__FILE__</code> and +<code>__LINE__</code> revert to the values they had before the +‘<samp>#include</samp>’ (but <code>__LINE__</code> is then incremented by one as +processing moves to the line after the ‘<samp>#include</samp>’). +</p> +<p>A ‘<samp>#line</samp>’ directive changes <code>__LINE__</code>, and may change +<code>__FILE__</code> as well. See <a href="Line-Control.html#Line-Control">Line Control</a>. +</p> +<p>C99 introduced <code>__func__</code>, and GCC has provided <code>__FUNCTION__</code> +for a long time. Both of these are strings containing the name of the +current function (there are slight semantic differences; see the GCC +manual). Neither of them is a macro; the preprocessor does not know the +name of the current function. They tend to be useful in conjunction +with <code>__FILE__</code> and <code>__LINE__</code>, though. +</p> +<dl compact="compact"> +<dt><code>__DATE__</code></dt> +<dd><p>This macro expands to a string constant that describes the date on which +the preprocessor is being run. The string constant contains eleven +characters and looks like <code>"Feb 12 1996"<!-- /@w --></code>. If the day of the +month is less than 10, it is padded with a space on the left. +</p> +<p>If GCC cannot determine the current date, it will emit a warning message +(once per compilation) and <code>__DATE__</code> will expand to +<code>"??? ?? ????"<!-- /@w --></code>. +</p> +</dd> +<dt><code>__TIME__</code></dt> +<dd><p>This macro expands to a string constant that describes the time at +which the preprocessor is being run. The string constant contains +eight characters and looks like <code>"23:59:01"</code>. +</p> +<p>If GCC cannot determine the current time, it will emit a warning message +(once per compilation) and <code>__TIME__</code> will expand to +<code>"??:??:??"</code>. +</p> +</dd> +<dt><code>__STDC__</code></dt> +<dd><p>In normal operation, this macro expands to the constant 1, to signify +that this compiler conforms to ISO Standard C. If GNU CPP is used with +a compiler other than GCC, this is not necessarily true; however, the +preprocessor always conforms to the standard unless the +<samp>-traditional-cpp</samp> option is used. +</p> +<p>This macro is not defined if the <samp>-traditional-cpp</samp> option is used. +</p> +<p>On some hosts, the system compiler uses a different convention, where +<code>__STDC__</code> is normally 0, but is 1 if the user specifies strict +conformance to the C Standard. CPP follows the host convention when +processing system header files, but when processing user files +<code>__STDC__</code> is always 1. This has been reported to cause problems; +for instance, some versions of Solaris provide X Windows headers that +expect <code>__STDC__</code> to be either undefined or 1. See <a href="Invocation.html#Invocation">Invocation</a>. +</p> +</dd> +<dt><code>__STDC_VERSION__</code></dt> +<dd><p>This macro expands to the C Standard’s version number, a long integer +constant of the form <code><var>yyyy</var><var>mm</var>L</code> where <var>yyyy</var> and +<var>mm</var> are the year and month of the Standard version. This signifies +which version of the C Standard the compiler conforms to. Like +<code>__STDC__</code>, this is not necessarily accurate for the entire +implementation, unless GNU CPP is being used with GCC. +</p> +<p>The value <code>199409L</code> signifies the 1989 C standard as amended in +1994, which is the current default; the value <code>199901L</code> signifies +the 1999 revision of the C standard; the value <code>201112L</code> +signifies the 2011 revision of the C standard; the value +<code>201710L</code> signifies the 2017 revision of the C standard (which is +otherwise identical to the 2011 version apart from correction of +defects). An unspecified value larger than <code>201710L</code> is used for +the experimental <samp>-std=c2x</samp> and <samp>-std=gnu2x</samp> modes. +</p> +<p>This macro is not defined if the <samp>-traditional-cpp</samp> option is +used, nor when compiling C++ or Objective-C. +</p> +</dd> +<dt><code>__STDC_HOSTED__</code></dt> +<dd><p>This macro is defined, with value 1, if the compiler’s target is a +<em>hosted environment</em>. A hosted environment has the complete +facilities of the standard C library available. +</p> +</dd> +<dt><code>__cplusplus</code></dt> +<dd><p>This macro is defined when the C++ compiler is in use. You can use +<code>__cplusplus</code> to test whether a header is compiled by a C compiler +or a C++ compiler. This macro is similar to <code>__STDC_VERSION__</code>, in +that it expands to a version number. Depending on the language standard +selected, the value of the macro is +<code>199711L</code> for the 1998 C++ standard, +<code>201103L</code> for the 2011 C++ standard, +<code>201402L</code> for the 2014 C++ standard, +<code>201703L</code> for the 2017 C++ standard, +<code>202002L</code> for the 2020 C++ standard, +or an unspecified value strictly larger than <code>202002L</code> for the +experimental languages enabled by <samp>-std=c++23</samp> and +<samp>-std=gnu++23</samp>. +</p> +</dd> +<dt><code>__OBJC__</code></dt> +<dd><p>This macro is defined, with value 1, when the Objective-C compiler is in +use. You can use <code>__OBJC__</code> to test whether a header is compiled +by a C compiler or an Objective-C compiler. +</p> +</dd> +<dt><code>__ASSEMBLER__</code></dt> +<dd><p>This macro is defined with value 1 when preprocessing assembly +language. +</p> +</dd> +</dl> + +<hr> +<div class="header"> +<p> +Next: <a href="Common-Predefined-Macros.html#Common-Predefined-Macros" accesskey="n" rel="next">Common Predefined Macros</a>, Up: <a href="Predefined-Macros.html#Predefined-Macros" accesskey="u" rel="up">Predefined Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Stringizing.html b/share/doc/cpp/Stringizing.html new file mode 100644 index 0000000..e97c519 --- /dev/null +++ b/share/doc/cpp/Stringizing.html @@ -0,0 +1,167 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Stringizing</title> + +<meta name="description" content="The C Preprocessor: Stringizing"> +<meta name="keywords" content="The C Preprocessor: Stringizing"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Macros.html#Macros" rel="up" title="Macros"> +<link href="Concatenation.html#Concatenation" rel="next" title="Concatenation"> +<link href="Macro-Arguments.html#Macro-Arguments" rel="previous" title="Macro Arguments"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Stringizing"></a> +<div class="header"> +<p> +Next: <a href="Concatenation.html#Concatenation" accesskey="n" rel="next">Concatenation</a>, Previous: <a href="Macro-Arguments.html#Macro-Arguments" accesskey="p" rel="previous">Macro Arguments</a>, Up: <a href="Macros.html#Macros" accesskey="u" rel="up">Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Stringizing-1"></a> +<h3 class="section">3.4 Stringizing</h3> +<a name="index-stringizing"></a> +<a name="index-_0023-operator"></a> + +<p>Sometimes you may want to convert a macro argument into a string +constant. Parameters are not replaced inside string constants, but you +can use the ‘<samp>#</samp>’ preprocessing operator instead. When a macro +parameter is used with a leading ‘<samp>#</samp>’, the preprocessor replaces it +with the literal text of the actual argument, converted to a string +constant. Unlike normal parameter replacement, the argument is not +macro-expanded first. This is called <em>stringizing</em>. +</p> +<p>There is no way to combine an argument with surrounding text and +stringize it all together. Instead, you can write a series of adjacent +string constants and stringized arguments. The preprocessor +replaces the stringized arguments with string constants. The C +compiler then combines all the adjacent string constants into one +long string. +</p> +<p>Here is an example of a macro definition that uses stringizing: +</p> +<div class="smallexample"> +<pre class="smallexample">#define WARN_IF(EXP) \ +do { if (EXP) \ + fprintf (stderr, "Warning: " #EXP "\n"); } \ +while (0) +WARN_IF (x == 0); + → do { if (x == 0) + fprintf (stderr, "Warning: " "x == 0" "\n"); } while (0); +</pre></div> + +<p>The argument for <code>EXP</code> is substituted once, as-is, into the +<code>if</code> statement, and once, stringized, into the argument to +<code>fprintf</code>. If <code>x</code> were a macro, it would be expanded in the +<code>if</code> statement, but not in the string. +</p> +<p>The <code>do</code> and <code>while (0)</code> are a kludge to make it possible to +write <code>WARN_IF (<var>arg</var>);</code>, which the resemblance of +<code>WARN_IF</code> to a function would make C programmers want to do; see +<a href="Swallowing-the-Semicolon.html#Swallowing-the-Semicolon">Swallowing the Semicolon</a>. +</p> +<p>Stringizing in C involves more than putting double-quote characters +around the fragment. The preprocessor backslash-escapes the quotes +surrounding embedded string constants, and all backslashes within string and +character constants, in order to get a valid C string constant with the +proper contents. Thus, stringizing <code>p = "foo\n";<!-- /@w --></code> results in +<tt>"p = \"foo\\n\";"<!-- /@w --></tt>. However, backslashes that are not inside string +or character constants are not duplicated: ‘<samp>\n</samp>’ by itself +stringizes to <tt>"\n"</tt>. +</p> +<p>All leading and trailing whitespace in text being stringized is +ignored. Any sequence of whitespace in the middle of the text is +converted to a single space in the stringized result. Comments are +replaced by whitespace long before stringizing happens, so they +never appear in stringized text. +</p> +<p>There is no way to convert a macro argument into a character constant. +</p> +<p>If you want to stringize the result of expansion of a macro argument, +you have to use two levels of macros. +</p> +<div class="smallexample"> +<pre class="smallexample">#define xstr(s) str(s) +#define str(s) #s +#define foo 4 +str (foo) + → "foo" +xstr (foo) + → xstr (4) + → str (4) + → "4" +</pre></div> + +<p><code>s</code> is stringized when it is used in <code>str</code>, so it is not +macro-expanded first. But <code>s</code> is an ordinary argument to +<code>xstr</code>, so it is completely macro-expanded before <code>xstr</code> +itself is expanded (see <a href="Argument-Prescan.html#Argument-Prescan">Argument Prescan</a>). Therefore, by the time +<code>str</code> gets to its argument, it has already been macro-expanded. +</p> +<hr> +<div class="header"> +<p> +Next: <a href="Concatenation.html#Concatenation" accesskey="n" rel="next">Concatenation</a>, Previous: <a href="Macro-Arguments.html#Macro-Arguments" accesskey="p" rel="previous">Macro Arguments</a>, Up: <a href="Macros.html#Macros" accesskey="u" rel="up">Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Swallowing-the-Semicolon.html b/share/doc/cpp/Swallowing-the-Semicolon.html new file mode 100644 index 0000000..e6af6cc --- /dev/null +++ b/share/doc/cpp/Swallowing-the-Semicolon.html @@ -0,0 +1,149 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Swallowing the Semicolon</title> + +<meta name="description" content="The C Preprocessor: Swallowing the Semicolon"> +<meta name="keywords" content="The C Preprocessor: Swallowing the Semicolon"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Macro-Pitfalls.html#Macro-Pitfalls" rel="up" title="Macro Pitfalls"> +<link href="Duplication-of-Side-Effects.html#Duplication-of-Side-Effects" rel="next" title="Duplication of Side Effects"> +<link href="Operator-Precedence-Problems.html#Operator-Precedence-Problems" rel="previous" title="Operator Precedence Problems"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Swallowing-the-Semicolon"></a> +<div class="header"> +<p> +Next: <a href="Duplication-of-Side-Effects.html#Duplication-of-Side-Effects" accesskey="n" rel="next">Duplication of Side Effects</a>, Previous: <a href="Operator-Precedence-Problems.html#Operator-Precedence-Problems" accesskey="p" rel="previous">Operator Precedence Problems</a>, Up: <a href="Macro-Pitfalls.html#Macro-Pitfalls" accesskey="u" rel="up">Macro Pitfalls</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Swallowing-the-Semicolon-1"></a> +<h4 class="subsection">3.10.3 Swallowing the Semicolon</h4> +<a name="index-semicolons-_0028after-macro-calls_0029"></a> + +<p>Often it is desirable to define a macro that expands into a compound +statement. Consider, for example, the following macro, that advances a +pointer (the argument <code>p</code> says where to find it) across whitespace +characters: +</p> +<div class="smallexample"> +<pre class="smallexample">#define SKIP_SPACES(p, limit) \ +{ char *lim = (limit); \ + while (p < lim) { \ + if (*p++ != ' ') { \ + p--; break; }}} +</pre></div> + +<p>Here backslash-newline is used to split the macro definition, which must +be a single logical line, so that it resembles the way such code would +be laid out if not part of a macro definition. +</p> +<p>A call to this macro might be <code>SKIP_SPACES (p, lim)</code>. Strictly +speaking, the call expands to a compound statement, which is a complete +statement with no need for a semicolon to end it. However, since it +looks like a function call, it minimizes confusion if you can use it +like a function call, writing a semicolon afterward, as in +<code>SKIP_SPACES (p, lim);</code> +</p> +<p>This can cause trouble before <code>else</code> statements, because the +semicolon is actually a null statement. Suppose you write +</p> +<div class="smallexample"> +<pre class="smallexample">if (*p != 0) + SKIP_SPACES (p, lim); +else … +</pre></div> + +<p>The presence of two statements—the compound statement and a null +statement—in between the <code>if</code> condition and the <code>else</code> +makes invalid C code. +</p> +<p>The definition of the macro <code>SKIP_SPACES</code> can be altered to solve +this problem, using a <code>do … while</code> statement. Here is how: +</p> +<div class="smallexample"> +<pre class="smallexample">#define SKIP_SPACES(p, limit) \ +do { char *lim = (limit); \ + while (p < lim) { \ + if (*p++ != ' ') { \ + p--; break; }}} \ +while (0) +</pre></div> + +<p>Now <code>SKIP_SPACES (p, lim);</code> expands into +</p> +<div class="smallexample"> +<pre class="smallexample">do {…} while (0); +</pre></div> + +<p>which is one statement. The loop executes exactly once; most compilers +generate no extra code for it. +</p> +<hr> +<div class="header"> +<p> +Next: <a href="Duplication-of-Side-Effects.html#Duplication-of-Side-Effects" accesskey="n" rel="next">Duplication of Side Effects</a>, Previous: <a href="Operator-Precedence-Problems.html#Operator-Precedence-Problems" accesskey="p" rel="previous">Operator Precedence Problems</a>, Up: <a href="Macro-Pitfalls.html#Macro-Pitfalls" accesskey="u" rel="up">Macro Pitfalls</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/System-Headers.html b/share/doc/cpp/System-Headers.html new file mode 100644 index 0000000..0af2f0c --- /dev/null +++ b/share/doc/cpp/System-Headers.html @@ -0,0 +1,115 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: System Headers</title> + +<meta name="description" content="The C Preprocessor: System Headers"> +<meta name="keywords" content="The C Preprocessor: System Headers"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Header-Files.html#Header-Files" rel="up" title="Header Files"> +<link href="Macros.html#Macros" rel="next" title="Macros"> +<link href="Wrapper-Headers.html#Wrapper-Headers" rel="previous" title="Wrapper Headers"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="System-Headers"></a> +<div class="header"> +<p> +Previous: <a href="Wrapper-Headers.html#Wrapper-Headers" accesskey="p" rel="previous">Wrapper Headers</a>, Up: <a href="Header-Files.html#Header-Files" accesskey="u" rel="up">Header Files</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="System-Headers-1"></a> +<h3 class="section">2.8 System Headers</h3> +<a name="index-system-header-files-1"></a> + +<p>The header files declaring interfaces to the operating system and +runtime libraries often cannot be written in strictly conforming C. +Therefore, GCC gives code found in <em>system headers</em> special +treatment. All warnings, other than those generated by ‘<samp>#warning</samp>’ +(see <a href="Diagnostics.html#Diagnostics">Diagnostics</a>), are suppressed while GCC is processing a system +header. Macros defined in a system header are immune to a few warnings +wherever they are expanded. This immunity is granted on an ad-hoc +basis, when we find that a warning generates lots of false positives +because of code in macros defined in system headers. +</p> +<p>Normally, only the headers found in specific directories are considered +system headers. These directories are determined when GCC is compiled. +There are, however, two ways to make normal headers into system headers: +</p> +<ul> +<li> Header files found in directories added to the search path with the +<samp>-isystem</samp> and <samp>-idirafter</samp> command-line options are +treated as system headers for the purposes of diagnostics. + +</li><li> <a name="index-_0023pragma-GCC-system_005fheader"></a> +There is also a directive, <code>#pragma GCC <span class="nolinebreak">system_header</span><!-- /@w --></code>, which +tells GCC to consider the rest of the current include file a system +header, no matter where it was found. Code that comes before the +‘<samp>#pragma</samp>’ in the file is not affected. <code>#pragma GCC <span class="nolinebreak">system_header</span><!-- /@w --></code> has no effect in the primary source file. +</li></ul> + +<p>On some targets, such as RS/6000 AIX, GCC implicitly surrounds all +system headers with an ‘<samp>extern "C"</samp>’ block when compiling as C++. +</p> + + + +</body> +</html> diff --git a/share/doc/cpp/System_002dspecific-Predefined-Macros.html b/share/doc/cpp/System_002dspecific-Predefined-Macros.html new file mode 100644 index 0000000..98891f3 --- /dev/null +++ b/share/doc/cpp/System_002dspecific-Predefined-Macros.html @@ -0,0 +1,127 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: System-specific Predefined Macros</title> + +<meta name="description" content="The C Preprocessor: System-specific Predefined Macros"> +<meta name="keywords" content="The C Preprocessor: System-specific Predefined Macros"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Predefined-Macros.html#Predefined-Macros" rel="up" title="Predefined Macros"> +<link href="C_002b_002b-Named-Operators.html#C_002b_002b-Named-Operators" rel="next" title="C++ Named Operators"> +<link href="Common-Predefined-Macros.html#Common-Predefined-Macros" rel="previous" title="Common Predefined Macros"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="System_002dspecific-Predefined-Macros"></a> +<div class="header"> +<p> +Next: <a href="C_002b_002b-Named-Operators.html#C_002b_002b-Named-Operators" accesskey="n" rel="next">C++ Named Operators</a>, Previous: <a href="Common-Predefined-Macros.html#Common-Predefined-Macros" accesskey="p" rel="previous">Common Predefined Macros</a>, Up: <a href="Predefined-Macros.html#Predefined-Macros" accesskey="u" rel="up">Predefined Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="System_002dspecific-Predefined-Macros-1"></a> +<h4 class="subsection">3.7.3 System-specific Predefined Macros</h4> + +<a name="index-system_002dspecific-predefined-macros"></a> +<a name="index-predefined-macros_002c-system_002dspecific"></a> +<a name="index-reserved-namespace"></a> + +<p>The C preprocessor normally predefines several macros that indicate what +type of system and machine is in use. They are obviously different on +each target supported by GCC. This manual, being for all systems and +machines, cannot tell you what their names are, but you can use +<code>cpp -dM</code> to see them all. See <a href="Invocation.html#Invocation">Invocation</a>. All system-specific +predefined macros expand to a constant value, so you can test them with +either ‘<samp>#ifdef</samp>’ or ‘<samp>#if</samp>’. +</p> +<p>The C standard requires that all system-specific macros be part of the +<em>reserved namespace</em>. All names which begin with two underscores, +or an underscore and a capital letter, are reserved for the compiler and +library to use as they wish. However, historically system-specific +macros have had names with no special prefix; for instance, it is common +to find <code>unix</code> defined on Unix systems. For all such macros, GCC +provides a parallel macro with two underscores added at the beginning +and the end. If <code>unix</code> is defined, <code>__unix__</code> will be defined +too. There will never be more than two underscores; the parallel of +<code>_mips</code> is <code>__mips__</code>. +</p> +<p>When the <samp>-ansi</samp> option, or any <samp>-std</samp> option that +requests strict conformance, is given to the compiler, all the +system-specific predefined macros outside the reserved namespace are +suppressed. The parallel macros, inside the reserved namespace, remain +defined. +</p> +<p>We are slowly phasing out all predefined macros which are outside the +reserved namespace. You should never use them in new programs, and we +encourage you to correct older code to use the parallel macros whenever +you find it. We don’t recommend you use the system-specific macros that +are in the reserved namespace, either. It is better in the long run to +check specifically for features you need, using a tool such as +<code>autoconf</code>. +</p> +<hr> +<div class="header"> +<p> +Next: <a href="C_002b_002b-Named-Operators.html#C_002b_002b-Named-Operators" accesskey="n" rel="next">C++ Named Operators</a>, Previous: <a href="Common-Predefined-Macros.html#Common-Predefined-Macros" accesskey="p" rel="previous">Common Predefined Macros</a>, Up: <a href="Predefined-Macros.html#Predefined-Macros" accesskey="u" rel="up">Predefined Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/The-preprocessing-language.html b/share/doc/cpp/The-preprocessing-language.html new file mode 100644 index 0000000..d372899 --- /dev/null +++ b/share/doc/cpp/The-preprocessing-language.html @@ -0,0 +1,154 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: The preprocessing language</title> + +<meta name="description" content="The C Preprocessor: The preprocessing language"> +<meta name="keywords" content="The C Preprocessor: The preprocessing language"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Overview.html#Overview" rel="up" title="Overview"> +<link href="Header-Files.html#Header-Files" rel="next" title="Header Files"> +<link href="Tokenization.html#Tokenization" rel="previous" title="Tokenization"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="The-preprocessing-language"></a> +<div class="header"> +<p> +Previous: <a href="Tokenization.html#Tokenization" accesskey="p" rel="previous">Tokenization</a>, Up: <a href="Overview.html#Overview" accesskey="u" rel="up">Overview</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="The-preprocessing-language-1"></a> +<h3 class="section">1.4 The preprocessing language</h3> +<a name="index-directives"></a> +<a name="index-preprocessing-directives"></a> +<a name="index-directive-line"></a> +<a name="index-directive-name"></a> + +<p>After tokenization, the stream of tokens may simply be passed straight +to the compiler’s parser. However, if it contains any operations in the +<em>preprocessing language</em>, it will be transformed first. This stage +corresponds roughly to the standard’s “translation phase 4” and is +what most people think of as the preprocessor’s job. +</p> +<p>The preprocessing language consists of <em>directives</em> to be executed +and <em>macros</em> to be expanded. Its primary capabilities are: +</p> +<ul> +<li> Inclusion of header files. These are files of declarations that can be +substituted into your program. + +</li><li> Macro expansion. You can define <em>macros</em>, which are abbreviations +for arbitrary fragments of C code. The preprocessor will replace the +macros with their definitions throughout the program. Some macros are +automatically defined for you. + +</li><li> Conditional compilation. You can include or exclude parts of the +program according to various conditions. + +</li><li> Line control. If you use a program to combine or rearrange source files +into an intermediate file which is then compiled, you can use line +control to inform the compiler where each source line originally came +from. + +</li><li> Diagnostics. You can detect problems at compile time and issue errors +or warnings. +</li></ul> + +<p>There are a few more, less useful, features. +</p> +<p>Except for expansion of predefined macros, all these operations are +triggered with <em>preprocessing directives</em>. Preprocessing directives +are lines in your program that start with ‘<samp>#</samp>’. Whitespace is +allowed before and after the ‘<samp>#</samp>’. The ‘<samp>#</samp>’ is followed by an +identifier, the <em>directive name</em>. It specifies the operation to +perform. Directives are commonly referred to as ‘<samp>#<var>name</var></samp>’ +where <var>name</var> is the directive name. For example, ‘<samp>#define</samp>’ is +the directive that defines a macro. +</p> +<p>The ‘<samp>#</samp>’ which begins a directive cannot come from a macro +expansion. Also, the directive name is not macro expanded. Thus, if +<code>foo</code> is defined as a macro expanding to <code>define</code>, that does +not make ‘<samp>#foo</samp>’ a valid preprocessing directive. +</p> +<p>The set of valid directive names is fixed. Programs cannot define new +preprocessing directives. +</p> +<p>Some directives require arguments; these make up the rest of the +directive line and must be separated from the directive name by +whitespace. For example, ‘<samp>#define</samp>’ must be followed by a macro +name and the intended expansion of the macro. +</p> +<p>A preprocessing directive cannot cover more than one line. The line +may, however, be continued with backslash-newline, or by a block comment +which extends past the end of the line. In either case, when the +directive is processed, the continuations have already been merged with +the first line to make one long line. +</p> +<hr> +<div class="header"> +<p> +Previous: <a href="Tokenization.html#Tokenization" accesskey="p" rel="previous">Tokenization</a>, Up: <a href="Overview.html#Overview" accesskey="u" rel="up">Overview</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Tokenization.html b/share/doc/cpp/Tokenization.html new file mode 100644 index 0000000..d997eeb --- /dev/null +++ b/share/doc/cpp/Tokenization.html @@ -0,0 +1,251 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Tokenization</title> + +<meta name="description" content="The C Preprocessor: Tokenization"> +<meta name="keywords" content="The C Preprocessor: Tokenization"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Overview.html#Overview" rel="up" title="Overview"> +<link href="The-preprocessing-language.html#The-preprocessing-language" rel="next" title="The preprocessing language"> +<link href="Initial-processing.html#Initial-processing" rel="previous" title="Initial processing"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Tokenization"></a> +<div class="header"> +<p> +Next: <a href="The-preprocessing-language.html#The-preprocessing-language" accesskey="n" rel="next">The preprocessing language</a>, Previous: <a href="Initial-processing.html#Initial-processing" accesskey="p" rel="previous">Initial processing</a>, Up: <a href="Overview.html#Overview" accesskey="u" rel="up">Overview</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Tokenization-1"></a> +<h3 class="section">1.3 Tokenization</h3> + +<a name="index-tokens"></a> +<a name="index-preprocessing-tokens"></a> +<p>After the textual transformations are finished, the input file is +converted into a sequence of <em>preprocessing tokens</em>. These mostly +correspond to the syntactic tokens used by the C compiler, but there are +a few differences. White space separates tokens; it is not itself a +token of any kind. Tokens do not have to be separated by white space, +but it is often necessary to avoid ambiguities. +</p> +<p>When faced with a sequence of characters that has more than one possible +tokenization, the preprocessor is greedy. It always makes each token, +starting from the left, as big as possible before moving on to the next +token. For instance, <code>a+++++b</code> is interpreted as +<code>a ++ ++ + b<!-- /@w --></code>, not as <code>a ++ + ++ b<!-- /@w --></code>, even though the +latter tokenization could be part of a valid C program and the former +could not. +</p> +<p>Once the input file is broken into tokens, the token boundaries never +change, except when the ‘<samp>##</samp>’ preprocessing operator is used to paste +tokens together. See <a href="Concatenation.html#Concatenation">Concatenation</a>. For example, +</p> +<div class="smallexample"> +<pre class="smallexample">#define foo() bar +foo()baz + → bar baz +<em>not</em> + → barbaz +</pre></div> + +<p>The compiler does not re-tokenize the preprocessor’s output. Each +preprocessing token becomes one compiler token. +</p> +<a name="index-identifiers"></a> +<p>Preprocessing tokens fall into five broad classes: identifiers, +preprocessing numbers, string literals, punctuators, and other. An +<em>identifier</em> is the same as an identifier in C: any sequence of +letters, digits, or underscores, which begins with a letter or +underscore. Keywords of C have no significance to the preprocessor; +they are ordinary identifiers. You can define a macro whose name is a +keyword, for instance. The only identifier which can be considered a +preprocessing keyword is <code>defined</code>. See <a href="Defined.html#Defined">Defined</a>. +</p> +<p>This is mostly true of other languages which use the C preprocessor. +However, a few of the keywords of C++ are significant even in the +preprocessor. See <a href="C_002b_002b-Named-Operators.html#C_002b_002b-Named-Operators">C++ Named Operators</a>. +</p> +<p>In the 1999 C standard, identifiers may contain letters which are not +part of the “basic source character set”, at the implementation’s +discretion (such as accented Latin letters, Greek letters, or Chinese +ideograms). This may be done with an extended character set, or the +‘<samp>\u</samp>’ and ‘<samp>\U</samp>’ escape sequences. +</p> +<p>As an extension, GCC treats ‘<samp>$</samp>’ as a letter. This is for +compatibility with some systems, such as VMS, where ‘<samp>$</samp>’ is commonly +used in system-defined function and object names. ‘<samp>$</samp>’ is not a +letter in strictly conforming mode, or if you specify the <samp>-$</samp> +option. See <a href="Invocation.html#Invocation">Invocation</a>. +</p> +<a name="index-numbers"></a> +<a name="index-preprocessing-numbers"></a> +<p>A <em>preprocessing number</em> has a rather bizarre definition. The +category includes all the normal integer and floating point constants +one expects of C, but also a number of other things one might not +initially recognize as a number. Formally, preprocessing numbers begin +with an optional period, a required decimal digit, and then continue +with any sequence of letters, digits, underscores, periods, and +exponents. Exponents are the two-character sequences ‘<samp>e+</samp>’, +‘<samp>e-</samp>’, ‘<samp>E+</samp>’, ‘<samp>E-</samp>’, ‘<samp>p+</samp>’, ‘<samp>p-</samp>’, ‘<samp>P+</samp>’, and +‘<samp>P-</samp>’. (The exponents that begin with ‘<samp>p</samp>’ or ‘<samp>P</samp>’ are +used for hexadecimal floating-point constants.) +</p> +<p>The purpose of this unusual definition is to isolate the preprocessor +from the full complexity of numeric constants. It does not have to +distinguish between lexically valid and invalid floating-point numbers, +which is complicated. The definition also permits you to split an +identifier at any position and get exactly two tokens, which can then be +pasted back together with the ‘<samp>##</samp>’ operator. +</p> +<p>It’s possible for preprocessing numbers to cause programs to be +misinterpreted. For example, <code>0xE+12</code> is a preprocessing number +which does not translate to any valid numeric constant, therefore a +syntax error. It does not mean <code>0xE + 12<!-- /@w --></code>, which is what you +might have intended. +</p> +<a name="index-string-literals"></a> +<a name="index-string-constants"></a> +<a name="index-character-constants"></a> +<a name="index-header-file-names"></a> +<p><em>String literals</em> are string constants, character constants, and +header file names (the argument of ‘<samp>#include</samp>’).<a name="DOCF2" href="#FOOT2"><sup>2</sup></a> String constants and character +constants are straightforward: <tt>"…"</tt> or <tt>'…'</tt>. In +either case embedded quotes should be escaped with a backslash: +<tt>'\''</tt> is the character constant for ‘<samp>'</samp>’. There is no limit on +the length of a character constant, but the value of a character +constant that contains more than one character is +implementation-defined. See <a href="Implementation-Details.html#Implementation-Details">Implementation Details</a>. +</p> +<p>Header file names either look like string constants, <tt>"…"</tt>, or are +written with angle brackets instead, <tt><…></tt>. In either case, +backslash is an ordinary character. There is no way to escape the +closing quote or angle bracket. The preprocessor looks for the header +file in different places depending on which form you use. See <a href="Include-Operation.html#Include-Operation">Include Operation</a>. +</p> +<p>No string literal may extend past the end of a line. You may use continued +lines instead, or string constant concatenation. +</p> +<a name="index-punctuators"></a> +<a name="index-digraphs"></a> +<a name="index-alternative-tokens"></a> +<p><em>Punctuators</em> are all the usual bits of punctuation which are +meaningful to C and C++. All but three of the punctuation characters in +ASCII are C punctuators. The exceptions are ‘<samp>@</samp>’, ‘<samp>$</samp>’, and +‘<samp>`</samp>’. In addition, all the two- and three-character operators are +punctuators. There are also six <em>digraphs</em>, which the C++ standard +calls <em>alternative tokens</em>, which are merely alternate ways to spell +other punctuators. This is a second attempt to work around missing +punctuation in obsolete systems. It has no negative side effects, +unlike trigraphs, but does not cover as much ground. The digraphs and +their corresponding normal punctuators are: +</p> +<div class="smallexample"> +<pre class="smallexample">Digraph: <% %> <: :> %: %:%: +Punctuator: { } [ ] # ## +</pre></div> + +<a name="index-other-tokens"></a> +<p>Any other single byte is considered “other” and passed on to the +preprocessor’s output unchanged. The C compiler will almost certainly +reject source code containing “other” tokens. In ASCII, the only +“other” characters are ‘<samp>@</samp>’, ‘<samp>$</samp>’, ‘<samp>`</samp>’, and control +characters other than NUL (all bits zero). (Note that ‘<samp>$</samp>’ is +normally considered a letter.) All bytes with the high bit set +(numeric range 0x7F–0xFF) that were not succesfully interpreted as +part of an extended character in the input encoding are also “other” +in the present implementation. +</p> +<p>NUL is a special case because of the high probability that its +appearance is accidental, and because it may be invisible to the user +(many terminals do not display NUL at all). Within comments, NULs are +silently ignored, just as any other character would be. In running +text, NUL is considered white space. For example, these two directives +have the same meaning. +</p> +<div class="smallexample"> +<pre class="smallexample">#define X^@1 +#define X 1 +</pre></div> + +<p>(where ‘<samp>^@</samp>’ is ASCII NUL). Within string or character constants, +NULs are preserved. In the latter two cases the preprocessor emits a +warning message. +</p> +<div class="footnote"> +<hr> +<h4 class="footnotes-heading">Footnotes</h4> + +<h3><a name="FOOT2" href="#DOCF2">(2)</a></h3> +<p>The C +standard uses the term <em>string literal</em> to refer only to what we are +calling <em>string constants</em>.</p> +</div> +<hr> +<div class="header"> +<p> +Next: <a href="The-preprocessing-language.html#The-preprocessing-language" accesskey="n" rel="next">The preprocessing language</a>, Previous: <a href="Initial-processing.html#Initial-processing" accesskey="p" rel="previous">Initial processing</a>, Up: <a href="Overview.html#Overview" accesskey="u" rel="up">Overview</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Traditional-Mode.html b/share/doc/cpp/Traditional-Mode.html new file mode 100644 index 0000000..21bdfbb --- /dev/null +++ b/share/doc/cpp/Traditional-Mode.html @@ -0,0 +1,114 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Traditional Mode</title> + +<meta name="description" content="The C Preprocessor: Traditional Mode"> +<meta name="keywords" content="The C Preprocessor: Traditional Mode"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="index.html#Top" rel="up" title="Top"> +<link href="Traditional-lexical-analysis.html#Traditional-lexical-analysis" rel="next" title="Traditional lexical analysis"> +<link href="Preprocessor-Output.html#Preprocessor-Output" rel="previous" title="Preprocessor Output"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Traditional-Mode"></a> +<div class="header"> +<p> +Next: <a href="Implementation-Details.html#Implementation-Details" accesskey="n" rel="next">Implementation Details</a>, Previous: <a href="Preprocessor-Output.html#Preprocessor-Output" accesskey="p" rel="previous">Preprocessor Output</a>, Up: <a href="index.html#Top" accesskey="u" rel="up">Top</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Traditional-Mode-1"></a> +<h2 class="chapter">10 Traditional Mode</h2> + +<p>Traditional (pre-standard) C preprocessing is rather different from +the preprocessing specified by the standard. When the preprocessor +is invoked with the +<samp>-traditional-cpp</samp> option, it attempts to emulate a traditional +preprocessor. +</p> +<p>This mode is not useful for compiling C code with GCC, +but is intended for use with non-C preprocessing applications. Thus +traditional mode semantics are supported only when invoking +the preprocessor explicitly, and not in the compiler front ends. +</p> +<p>The implementation does not correspond precisely to the behavior of +early pre-standard versions of GCC, nor to any true traditional preprocessor. +After all, inconsistencies among traditional implementations were a +major motivation for C standardization. However, we intend that it +should be compatible with true traditional preprocessors in all ways +that actually matter. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="Traditional-lexical-analysis.html#Traditional-lexical-analysis" accesskey="1">Traditional lexical analysis</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Traditional-macros.html#Traditional-macros" accesskey="2">Traditional macros</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Traditional-miscellany.html#Traditional-miscellany" accesskey="3">Traditional miscellany</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Traditional-warnings.html#Traditional-warnings" accesskey="4">Traditional warnings</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +</table> + + + + +</body> +</html> diff --git a/share/doc/cpp/Traditional-lexical-analysis.html b/share/doc/cpp/Traditional-lexical-analysis.html new file mode 100644 index 0000000..b4e4ccb --- /dev/null +++ b/share/doc/cpp/Traditional-lexical-analysis.html @@ -0,0 +1,155 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Traditional lexical analysis</title> + +<meta name="description" content="The C Preprocessor: Traditional lexical analysis"> +<meta name="keywords" content="The C Preprocessor: Traditional lexical analysis"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Traditional-Mode.html#Traditional-Mode" rel="up" title="Traditional Mode"> +<link href="Traditional-macros.html#Traditional-macros" rel="next" title="Traditional macros"> +<link href="Traditional-Mode.html#Traditional-Mode" rel="previous" title="Traditional Mode"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Traditional-lexical-analysis"></a> +<div class="header"> +<p> +Next: <a href="Traditional-macros.html#Traditional-macros" accesskey="n" rel="next">Traditional macros</a>, Up: <a href="Traditional-Mode.html#Traditional-Mode" accesskey="u" rel="up">Traditional Mode</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Traditional-lexical-analysis-1"></a> +<h3 class="section">10.1 Traditional lexical analysis</h3> + +<p>The traditional preprocessor does not decompose its input into tokens +the same way a standards-conforming preprocessor does. The input is +simply treated as a stream of text with minimal internal form. +</p> +<p>This implementation does not treat trigraphs (see <a href="Initial-processing.html#trigraphs">trigraphs</a>) +specially since they were an invention of the standards committee. It +handles arbitrarily-positioned escaped newlines properly and splices +the lines as you would expect; many traditional preprocessors did not +do this. +</p> +<p>The form of horizontal whitespace in the input file is preserved in +the output. In particular, hard tabs remain hard tabs. This can be +useful if, for example, you are preprocessing a Makefile. +</p> +<p>Traditional CPP only recognizes C-style block comments, and treats the +‘<samp>/*</samp>’ sequence as introducing a comment only if it lies outside +quoted text. Quoted text is introduced by the usual single and double +quotes, and also by an initial ‘<samp><</samp>’ in a <code>#include</code> +directive. +</p> +<p>Traditionally, comments are completely removed and are not replaced +with a space. Since a traditional compiler does its own tokenization +of the output of the preprocessor, this means that comments can +effectively be used as token paste operators. However, comments +behave like separators for text handled by the preprocessor itself, +since it doesn’t re-lex its input. For example, in +</p> +<div class="smallexample"> +<pre class="smallexample">#if foo/**/bar +</pre></div> + +<p>‘<samp>foo</samp>’ and ‘<samp>bar</samp>’ are distinct identifiers and expanded +separately if they happen to be macros. In other words, this +directive is equivalent to +</p> +<div class="smallexample"> +<pre class="smallexample">#if foo bar +</pre></div> + +<p>rather than +</p> +<div class="smallexample"> +<pre class="smallexample">#if foobar +</pre></div> + +<p>Generally speaking, in traditional mode an opening quote need not have +a matching closing quote. In particular, a macro may be defined with +replacement text that contains an unmatched quote. Of course, if you +attempt to compile preprocessed output containing an unmatched quote +you will get a syntax error. +</p> +<p>However, all preprocessing directives other than <code>#define</code> +require matching quotes. For example: +</p> +<div class="smallexample"> +<pre class="smallexample">#define m This macro's fine and has an unmatched quote +"/* This is not a comment. */ +/* <span class="roman">This is a comment. The following #include directive + is ill-formed.</span> */ +#include <stdio.h +</pre></div> + +<p>Just as for the ISO preprocessor, what would be a closing quote can be +escaped with a backslash to prevent the quoted text from closing. +</p> +<hr> +<div class="header"> +<p> +Next: <a href="Traditional-macros.html#Traditional-macros" accesskey="n" rel="next">Traditional macros</a>, Up: <a href="Traditional-Mode.html#Traditional-Mode" accesskey="u" rel="up">Traditional Mode</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Traditional-macros.html b/share/doc/cpp/Traditional-macros.html new file mode 100644 index 0000000..1175aba --- /dev/null +++ b/share/doc/cpp/Traditional-macros.html @@ -0,0 +1,180 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Traditional macros</title> + +<meta name="description" content="The C Preprocessor: Traditional macros"> +<meta name="keywords" content="The C Preprocessor: Traditional macros"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Traditional-Mode.html#Traditional-Mode" rel="up" title="Traditional Mode"> +<link href="Traditional-miscellany.html#Traditional-miscellany" rel="next" title="Traditional miscellany"> +<link href="Traditional-lexical-analysis.html#Traditional-lexical-analysis" rel="previous" title="Traditional lexical analysis"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Traditional-macros"></a> +<div class="header"> +<p> +Next: <a href="Traditional-miscellany.html#Traditional-miscellany" accesskey="n" rel="next">Traditional miscellany</a>, Previous: <a href="Traditional-lexical-analysis.html#Traditional-lexical-analysis" accesskey="p" rel="previous">Traditional lexical analysis</a>, Up: <a href="Traditional-Mode.html#Traditional-Mode" accesskey="u" rel="up">Traditional Mode</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Traditional-macros-1"></a> +<h3 class="section">10.2 Traditional macros</h3> + +<p>The major difference between traditional and ISO macros is that the +former expand to text rather than to a token sequence. CPP removes +all leading and trailing horizontal whitespace from a macro’s +replacement text before storing it, but preserves the form of internal +whitespace. +</p> +<p>One consequence is that it is legitimate for the replacement text to +contain an unmatched quote (see <a href="Traditional-lexical-analysis.html#Traditional-lexical-analysis">Traditional lexical analysis</a>). An +unclosed string or character constant continues into the text +following the macro call. Similarly, the text at the end of a macro’s +expansion can run together with the text after the macro invocation to +produce a single token. +</p> +<p>Normally comments are removed from the replacement text after the +macro is expanded, but if the <samp>-CC</samp> option is passed on the +command-line comments are preserved. (In fact, the current +implementation removes comments even before saving the macro +replacement text, but it careful to do it in such a way that the +observed effect is identical even in the function-like macro case.) +</p> +<p>The ISO stringizing operator ‘<samp>#</samp>’ and token paste operator +‘<samp>##</samp>’ have no special meaning. As explained later, an effect +similar to these operators can be obtained in a different way. Macro +names that are embedded in quotes, either from the main file or after +macro replacement, do not expand. +</p> +<p>CPP replaces an unquoted object-like macro name with its replacement +text, and then rescans it for further macros to replace. Unlike +standard macro expansion, traditional macro expansion has no provision +to prevent recursion. If an object-like macro appears unquoted in its +replacement text, it will be replaced again during the rescan pass, +and so on <em>ad infinitum</em>. GCC detects when it is expanding +recursive macros, emits an error message, and continues after the +offending macro invocation. +</p> +<div class="smallexample"> +<pre class="smallexample">#define PLUS + +#define INC(x) PLUS+x +INC(foo); + → ++foo; +</pre></div> + +<p>Function-like macros are similar in form but quite different in +behavior to their ISO counterparts. Their arguments are contained +within parentheses, are comma-separated, and can cross physical lines. +Commas within nested parentheses are not treated as argument +separators. Similarly, a quote in an argument cannot be left +unclosed; a following comma or parenthesis that comes before the +closing quote is treated like any other character. There is no +facility for handling variadic macros. +</p> +<p>This implementation removes all comments from macro arguments, unless +the <samp>-C</samp> option is given. The form of all other horizontal +whitespace in arguments is preserved, including leading and trailing +whitespace. In particular +</p> +<div class="smallexample"> +<pre class="smallexample">f( ) +</pre></div> + +<p>is treated as an invocation of the macro ‘<samp>f</samp>’ with a single +argument consisting of a single space. If you want to invoke a +function-like macro that takes no arguments, you must not leave any +whitespace between the parentheses. +</p> +<p>If a macro argument crosses a new line, the new line is replaced with +a space when forming the argument. If the previous line contained an +unterminated quote, the following line inherits the quoted state. +</p> +<p>Traditional preprocessors replace parameters in the replacement text +with their arguments regardless of whether the parameters are within +quotes or not. This provides a way to stringize arguments. For +example +</p> +<div class="smallexample"> +<pre class="smallexample">#define str(x) "x" +str(/* <span class="roman">A comment</span> */some text ) + → "some text " +</pre></div> + +<p>Note that the comment is removed, but that the trailing space is +preserved. Here is an example of using a comment to effect token +pasting. +</p> +<div class="smallexample"> +<pre class="smallexample">#define suffix(x) foo_/**/x +suffix(bar) + → foo_bar +</pre></div> + +<hr> +<div class="header"> +<p> +Next: <a href="Traditional-miscellany.html#Traditional-miscellany" accesskey="n" rel="next">Traditional miscellany</a>, Previous: <a href="Traditional-lexical-analysis.html#Traditional-lexical-analysis" accesskey="p" rel="previous">Traditional lexical analysis</a>, Up: <a href="Traditional-Mode.html#Traditional-Mode" accesskey="u" rel="up">Traditional Mode</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Traditional-miscellany.html b/share/doc/cpp/Traditional-miscellany.html new file mode 100644 index 0000000..8965487 --- /dev/null +++ b/share/doc/cpp/Traditional-miscellany.html @@ -0,0 +1,109 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Traditional miscellany</title> + +<meta name="description" content="The C Preprocessor: Traditional miscellany"> +<meta name="keywords" content="The C Preprocessor: Traditional miscellany"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Traditional-Mode.html#Traditional-Mode" rel="up" title="Traditional Mode"> +<link href="Traditional-warnings.html#Traditional-warnings" rel="next" title="Traditional warnings"> +<link href="Traditional-macros.html#Traditional-macros" rel="previous" title="Traditional macros"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Traditional-miscellany"></a> +<div class="header"> +<p> +Next: <a href="Traditional-warnings.html#Traditional-warnings" accesskey="n" rel="next">Traditional warnings</a>, Previous: <a href="Traditional-macros.html#Traditional-macros" accesskey="p" rel="previous">Traditional macros</a>, Up: <a href="Traditional-Mode.html#Traditional-Mode" accesskey="u" rel="up">Traditional Mode</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Traditional-miscellany-1"></a> +<h3 class="section">10.3 Traditional miscellany</h3> + +<p>Here are some things to be aware of when using the traditional +preprocessor. +</p> +<ul> +<li> Preprocessing directives are recognized only when their leading +‘<samp>#</samp>’ appears in the first column. There can be no whitespace +between the beginning of the line and the ‘<samp>#</samp>’, but whitespace can +follow the ‘<samp>#</samp>’. + +</li><li> A true traditional C preprocessor does not recognize ‘<samp>#error</samp>’ or +‘<samp>#pragma</samp>’, and may not recognize ‘<samp>#elif</samp>’. CPP supports all +the directives in traditional mode that it supports in ISO mode, +including extensions, with the exception that the effects of +‘<samp>#pragma GCC poison</samp>’ are undefined. + +</li><li> __STDC__ is not defined. + +</li><li> If you use digraphs the behavior is undefined. + +</li><li> If a line that looks like a directive appears within macro arguments, +the behavior is undefined. + +</li></ul> + + + + +</body> +</html> diff --git a/share/doc/cpp/Traditional-warnings.html b/share/doc/cpp/Traditional-warnings.html new file mode 100644 index 0000000..591de60 --- /dev/null +++ b/share/doc/cpp/Traditional-warnings.html @@ -0,0 +1,131 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Traditional warnings</title> + +<meta name="description" content="The C Preprocessor: Traditional warnings"> +<meta name="keywords" content="The C Preprocessor: Traditional warnings"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Traditional-Mode.html#Traditional-Mode" rel="up" title="Traditional Mode"> +<link href="Implementation-Details.html#Implementation-Details" rel="next" title="Implementation Details"> +<link href="Traditional-miscellany.html#Traditional-miscellany" rel="previous" title="Traditional miscellany"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Traditional-warnings"></a> +<div class="header"> +<p> +Previous: <a href="Traditional-miscellany.html#Traditional-miscellany" accesskey="p" rel="previous">Traditional miscellany</a>, Up: <a href="Traditional-Mode.html#Traditional-Mode" accesskey="u" rel="up">Traditional Mode</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Traditional-warnings-1"></a> +<h3 class="section">10.4 Traditional warnings</h3> +<p>You can request warnings about features that did not exist, or worked +differently, in traditional C with the <samp>-Wtraditional</samp> option. +GCC does not warn about features of ISO C which you must use when you +are using a conforming compiler, such as the ‘<samp>#</samp>’ and ‘<samp>##</samp>’ +operators. +</p> +<p>Presently <samp>-Wtraditional</samp> warns about: +</p> +<ul> +<li> Macro parameters that appear within string literals in the macro body. +In traditional C macro replacement takes place within string literals, +but does not in ISO C. + +</li><li> In traditional C, some preprocessor directives did not exist. +Traditional preprocessors would only consider a line to be a directive +if the ‘<samp>#</samp>’ appeared in column 1 on the line. Therefore +<samp>-Wtraditional</samp> warns about directives that traditional C +understands but would ignore because the ‘<samp>#</samp>’ does not appear as the +first character on the line. It also suggests you hide directives like +‘<samp>#pragma</samp>’ not understood by traditional C by indenting them. Some +traditional implementations would not recognize ‘<samp>#elif</samp>’, so it +suggests avoiding it altogether. + +</li><li> A function-like macro that appears without an argument list. In some +traditional preprocessors this was an error. In ISO C it merely means +that the macro is not expanded. + +</li><li> The unary plus operator. This did not exist in traditional C. + +</li><li> The ‘<samp>U</samp>’ and ‘<samp>LL</samp>’ integer constant suffixes, which were not +available in traditional C. (Traditional C does support the ‘<samp>L</samp>’ +suffix for simple long integer constants.) You are not warned about +uses of these suffixes in macros defined in system headers. For +instance, <code>UINT_MAX</code> may well be defined as <code>4294967295U</code>, but +you will not be warned if you use <code>UINT_MAX</code>. + +<p>You can usually avoid the warning, and the related warning about +constants which are so large that they are unsigned, by writing the +integer constant in question in hexadecimal, with no U suffix. Take +care, though, because this gives the wrong result in exotic cases. +</p></li></ul> + +<hr> +<div class="header"> +<p> +Previous: <a href="Traditional-miscellany.html#Traditional-miscellany" accesskey="p" rel="previous">Traditional miscellany</a>, Up: <a href="Traditional-Mode.html#Traditional-Mode" accesskey="u" rel="up">Traditional Mode</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Undefining-and-Redefining-Macros.html b/share/doc/cpp/Undefining-and-Redefining-Macros.html new file mode 100644 index 0000000..f7e4ba1 --- /dev/null +++ b/share/doc/cpp/Undefining-and-Redefining-Macros.html @@ -0,0 +1,144 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Undefining and Redefining Macros</title> + +<meta name="description" content="The C Preprocessor: Undefining and Redefining Macros"> +<meta name="keywords" content="The C Preprocessor: Undefining and Redefining Macros"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Macros.html#Macros" rel="up" title="Macros"> +<link href="Directives-Within-Macro-Arguments.html#Directives-Within-Macro-Arguments" rel="next" title="Directives Within Macro Arguments"> +<link href="C_002b_002b-Named-Operators.html#C_002b_002b-Named-Operators" rel="previous" title="C++ Named Operators"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Undefining-and-Redefining-Macros"></a> +<div class="header"> +<p> +Next: <a href="Directives-Within-Macro-Arguments.html#Directives-Within-Macro-Arguments" accesskey="n" rel="next">Directives Within Macro Arguments</a>, Previous: <a href="Predefined-Macros.html#Predefined-Macros" accesskey="p" rel="previous">Predefined Macros</a>, Up: <a href="Macros.html#Macros" accesskey="u" rel="up">Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Undefining-and-Redefining-Macros-1"></a> +<h3 class="section">3.8 Undefining and Redefining Macros</h3> +<a name="index-undefining-macros"></a> +<a name="index-redefining-macros"></a> +<a name="index-_0023undef"></a> + +<p>If a macro ceases to be useful, it may be <em>undefined</em> with the +‘<samp>#undef</samp>’ directive. ‘<samp>#undef</samp>’ takes a single argument, the +name of the macro to undefine. You use the bare macro name, even if the +macro is function-like. It is an error if anything appears on the line +after the macro name. ‘<samp>#undef</samp>’ has no effect if the name is not a +macro. +</p> +<div class="smallexample"> +<pre class="smallexample">#define FOO 4 +x = FOO; → x = 4; +#undef FOO +x = FOO; → x = FOO; +</pre></div> + +<p>Once a macro has been undefined, that identifier may be <em>redefined</em> +as a macro by a subsequent ‘<samp>#define</samp>’ directive. The new definition +need not have any resemblance to the old definition. +</p> +<p>However, if an identifier which is currently a macro is redefined, then +the new definition must be <em>effectively the same</em> as the old one. +Two macro definitions are effectively the same if: +</p><ul> +<li> Both are the same type of macro (object- or function-like). +</li><li> All the tokens of the replacement list are the same. +</li><li> If there are any parameters, they are the same. +</li><li> Whitespace appears in the same places in both. It need not be +exactly the same amount of whitespace, though. Remember that comments +count as whitespace. +</li></ul> + +<p>These definitions are effectively the same: +</p><div class="smallexample"> +<pre class="smallexample">#define FOUR (2 + 2) +#define FOUR (2 + 2) +#define FOUR (2 /* <span class="roman">two</span> */ + 2) +</pre></div> +<p>but these are not: +</p><div class="smallexample"> +<pre class="smallexample">#define FOUR (2 + 2) +#define FOUR ( 2+2 ) +#define FOUR (2 * 2) +#define FOUR(score,and,seven,years,ago) (2 + 2) +</pre></div> + +<p>If a macro is redefined with a definition that is not effectively the +same as the old one, the preprocessor issues a warning and changes the +macro to use the new definition. If the new definition is effectively +the same, the redefinition is silently ignored. This allows, for +instance, two different headers to define a common macro. The +preprocessor will only complain if the definitions do not match. +</p> +<hr> +<div class="header"> +<p> +Next: <a href="Directives-Within-Macro-Arguments.html#Directives-Within-Macro-Arguments" accesskey="n" rel="next">Directives Within Macro Arguments</a>, Previous: <a href="Predefined-Macros.html#Predefined-Macros" accesskey="p" rel="previous">Predefined Macros</a>, Up: <a href="Macros.html#Macros" accesskey="u" rel="up">Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Variadic-Macros.html b/share/doc/cpp/Variadic-Macros.html new file mode 100644 index 0000000..eaa454c --- /dev/null +++ b/share/doc/cpp/Variadic-Macros.html @@ -0,0 +1,223 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Variadic Macros</title> + +<meta name="description" content="The C Preprocessor: Variadic Macros"> +<meta name="keywords" content="The C Preprocessor: Variadic Macros"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Macros.html#Macros" rel="up" title="Macros"> +<link href="Predefined-Macros.html#Predefined-Macros" rel="next" title="Predefined Macros"> +<link href="Concatenation.html#Concatenation" rel="previous" title="Concatenation"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Variadic-Macros"></a> +<div class="header"> +<p> +Next: <a href="Predefined-Macros.html#Predefined-Macros" accesskey="n" rel="next">Predefined Macros</a>, Previous: <a href="Concatenation.html#Concatenation" accesskey="p" rel="previous">Concatenation</a>, Up: <a href="Macros.html#Macros" accesskey="u" rel="up">Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Variadic-Macros-1"></a> +<h3 class="section">3.6 Variadic Macros</h3> +<a name="index-variable-number-of-arguments"></a> +<a name="index-macros-with-variable-arguments"></a> +<a name="index-variadic-macros"></a> + +<p>A macro can be declared to accept a variable number of arguments much as +a function can. The syntax for defining the macro is similar to that of +a function. Here is an example: +</p> +<div class="smallexample"> +<pre class="smallexample">#define eprintf(...) fprintf (stderr, __VA_ARGS__) +</pre></div> + +<p>This kind of macro is called <em>variadic</em>. When the macro is invoked, +all the tokens in its argument list after the last named argument (this +macro has none), including any commas, become the <em>variable +argument</em>. This sequence of tokens replaces the identifier +<code><span class="nolinebreak">__VA_ARGS__</span><!-- /@w --></code> in the macro body wherever it appears. Thus, we +have this expansion: +</p> +<div class="smallexample"> +<pre class="smallexample">eprintf ("%s:%d: ", input_file, lineno) + → fprintf (stderr, "%s:%d: ", input_file, lineno) +</pre></div> + +<p>The variable argument is completely macro-expanded before it is inserted +into the macro expansion, just like an ordinary argument. You may use +the ‘<samp>#</samp>’ and ‘<samp>##</samp>’ operators to stringize the variable argument +or to paste its leading or trailing token with another token. (But see +below for an important special case for ‘<samp>##</samp>’.) +</p> +<p>If your macro is complicated, you may want a more descriptive name for +the variable argument than <code><span class="nolinebreak">__VA_ARGS__</span><!-- /@w --></code>. CPP permits +this, as an extension. You may write an argument name immediately +before the ‘<samp>...</samp>’; that name is used for the variable argument. +The <code>eprintf</code> macro above could be written +</p> +<div class="smallexample"> +<pre class="smallexample">#define eprintf(args...) fprintf (stderr, args) +</pre></div> + +<p>using this extension. You cannot use <code><span class="nolinebreak">__VA_ARGS__</span><!-- /@w --></code> and this +extension in the same macro. +</p> +<p>You can have named arguments as well as variable arguments in a variadic +macro. We could define <code>eprintf</code> like this, instead: +</p> +<div class="smallexample"> +<pre class="smallexample">#define eprintf(format, ...) fprintf (stderr, format, __VA_ARGS__) +</pre></div> + +<p>This formulation looks more descriptive, but historically it was less +flexible: you had to supply at least one argument after the format +string. In standard C, you could not omit the comma separating the +named argument from the variable arguments. (Note that this +restriction has been lifted in C++20, and never existed in GNU C; see +below.) +</p> +<p>Furthermore, if you left the variable argument empty, you would have +gotten a syntax error, because there would have been an extra comma +after the format string. +</p> +<div class="smallexample"> +<pre class="smallexample">eprintf("success!\n", ); + → fprintf(stderr, "success!\n", ); +</pre></div> + +<p>This has been fixed in C++20, and GNU CPP also has a pair of +extensions which deal with this problem. +</p> +<p>First, in GNU CPP, and in C++ beginning in C++20, you are allowed to +leave the variable argument out entirely: +</p> +<div class="smallexample"> +<pre class="smallexample">eprintf ("success!\n") + → fprintf(stderr, "success!\n", ); +</pre></div> + +<p>Second, C++20 introduces the <code><span class="nolinebreak">__VA_OPT__</span><!-- /@w --></code> function macro. +This macro may only appear in the definition of a variadic macro. If +the variable argument has any tokens, then a <code><span class="nolinebreak">__VA_OPT__</span><!-- /@w --></code> +invocation expands to its argument; but if the variable argument does +not have any tokens, the <code><span class="nolinebreak">__VA_OPT__</span><!-- /@w --></code> expands to nothing: +</p> +<div class="smallexample"> +<pre class="smallexample">#define eprintf(format, ...) \ + fprintf (stderr, format __VA_OPT__(,) __VA_ARGS__) +</pre></div> + +<p><code><span class="nolinebreak">__VA_OPT__</span><!-- /@w --></code> is also available in GNU C and GNU C++. +</p> +<p>Historically, GNU CPP has also had another extension to handle the +trailing comma: the ‘<samp>##</samp>’ token paste operator has a special +meaning when placed between a comma and a variable argument. Despite +the introduction of <code><span class="nolinebreak">__VA_OPT__</span><!-- /@w --></code>, this extension remains +supported in GNU CPP, for backward compatibility. If you write +</p> +<div class="smallexample"> +<pre class="smallexample">#define eprintf(format, ...) fprintf (stderr, format, ##__VA_ARGS__) +</pre></div> + +<p>and the variable argument is left out when the <code>eprintf</code> macro is +used, then the comma before the ‘<samp>##</samp>’ will be deleted. This does +<em>not</em> happen if you pass an empty argument, nor does it happen if +the token preceding ‘<samp>##</samp>’ is anything other than a comma. +</p> +<div class="smallexample"> +<pre class="smallexample">eprintf ("success!\n") + → fprintf(stderr, "success!\n"); +</pre></div> + +<p>The above explanation is ambiguous about the case where the only macro +parameter is a variable arguments parameter, as it is meaningless to +try to distinguish whether no argument at all is an empty argument or +a missing argument. +CPP retains the comma when conforming to a specific C +standard. Otherwise the comma is dropped as an extension to the standard. +</p> +<p>The C standard +mandates that the only place the identifier <code><span class="nolinebreak">__VA_ARGS__</span><!-- /@w --></code> +can appear is in the replacement list of a variadic macro. It may not +be used as a macro name, macro argument name, or within a different type +of macro. It may also be forbidden in open text; the standard is +ambiguous. We recommend you avoid using it except for its defined +purpose. +</p> +<p>Likewise, C++ forbids <code><span class="nolinebreak">__VA_OPT__</span><!-- /@w --></code> anywhere outside the +replacement list of a variadic macro. +</p> +<p>Variadic macros became a standard part of the C language with C99. +GNU CPP previously supported them +with a named variable argument +(‘<samp>args...</samp>’, not ‘<samp>...</samp>’ and <code><span class="nolinebreak">__VA_ARGS__</span><!-- /@w --></code>), which +is still supported for backward compatibility. +</p> +<hr> +<div class="header"> +<p> +Next: <a href="Predefined-Macros.html#Predefined-Macros" accesskey="n" rel="next">Predefined Macros</a>, Previous: <a href="Concatenation.html#Concatenation" accesskey="p" rel="previous">Concatenation</a>, Up: <a href="Macros.html#Macros" accesskey="u" rel="up">Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Wrapper-Headers.html b/share/doc/cpp/Wrapper-Headers.html new file mode 100644 index 0000000..8f54504 --- /dev/null +++ b/share/doc/cpp/Wrapper-Headers.html @@ -0,0 +1,137 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Wrapper Headers</title> + +<meta name="description" content="The C Preprocessor: Wrapper Headers"> +<meta name="keywords" content="The C Preprocessor: Wrapper Headers"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Header-Files.html#Header-Files" rel="up" title="Header Files"> +<link href="System-Headers.html#System-Headers" rel="next" title="System Headers"> +<link href="Computed-Includes.html#Computed-Includes" rel="previous" title="Computed Includes"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Wrapper-Headers"></a> +<div class="header"> +<p> +Next: <a href="System-Headers.html#System-Headers" accesskey="n" rel="next">System Headers</a>, Previous: <a href="Computed-Includes.html#Computed-Includes" accesskey="p" rel="previous">Computed Includes</a>, Up: <a href="Header-Files.html#Header-Files" accesskey="u" rel="up">Header Files</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Wrapper-Headers-1"></a> +<h3 class="section">2.7 Wrapper Headers</h3> +<a name="index-wrapper-headers"></a> +<a name="index-overriding-a-header-file"></a> +<a name="index-_0023include_005fnext"></a> + +<p>Sometimes it is necessary to adjust the contents of a system-provided +header file without editing it directly. GCC’s <code>fixincludes</code> +operation does this, for example. One way to do that would be to create +a new header file with the same name and insert it in the search path +before the original header. That works fine as long as you’re willing +to replace the old header entirely. But what if you want to refer to +the old header from the new one? +</p> +<p>You cannot simply include the old header with ‘<samp>#include</samp>’. That +will start from the beginning, and find your new header again. If your +header is not protected from multiple inclusion (see <a href="Once_002dOnly-Headers.html#Once_002dOnly-Headers">Once-Only Headers</a>), it will recurse infinitely and cause a fatal error. +</p> +<p>You could include the old header with an absolute pathname: +</p><div class="smallexample"> +<pre class="smallexample">#include "/usr/include/old-header.h" +</pre></div> +<p>This works, but is not clean; should the system headers ever move, you +would have to edit the new headers to match. +</p> +<p>There is no way to solve this problem within the C standard, but you can +use the GNU extension ‘<samp>#include_next</samp>’. It means, “Include the +<em>next</em> file with this name”. This directive works like +‘<samp>#include</samp>’ except in searching for the specified file: it starts +searching the list of header file directories <em>after</em> the directory +in which the current file was found. +</p> +<p>Suppose you specify <samp>-I /usr/local/include</samp>, and the list of +directories to search also includes <samp>/usr/include</samp>; and suppose +both directories contain <samp>signal.h</samp>. Ordinary <code>#include <signal.h><!-- /@w --></code> finds the file under <samp>/usr/local/include</samp>. If that +file contains <code><span class="nolinebreak">#include_next</span> <signal.h><!-- /@w --></code>, it starts searching +after that directory, and finds the file in <samp>/usr/include</samp>. +</p> +<p>‘<samp>#include_next</samp>’ does not distinguish between <code><<var>file</var>></code> +and <code>"<var>file</var>"</code> inclusion, nor does it check that the file you +specify has the same name as the current file. It simply looks for the +file named, starting with the directory in the search path after the one +where the current file was found. +</p> +<p>The use of ‘<samp>#include_next</samp>’ can lead to great confusion. We +recommend it be used only when there is no other alternative. In +particular, it should not be used in the headers belonging to a specific +program; it should be used only to make global corrections along the +lines of <code>fixincludes</code>. +</p> +<hr> +<div class="header"> +<p> +Next: <a href="System-Headers.html#System-Headers" accesskey="n" rel="next">System Headers</a>, Previous: <a href="Computed-Includes.html#Computed-Includes" accesskey="p" rel="previous">Computed Includes</a>, Up: <a href="Header-Files.html#Header-Files" accesskey="u" rel="up">Header Files</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/Wtrigraphs.html b/share/doc/cpp/Wtrigraphs.html new file mode 100644 index 0000000..a5a883f --- /dev/null +++ b/share/doc/cpp/Wtrigraphs.html @@ -0,0 +1,70 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<!-- This file redirects to the location of a node or anchor --> +<head> +<title>The C Preprocessor: Wtrigraphs</title> + +<meta name="description" content="The C Preprocessor: Wtrigraphs"> +<meta name="keywords" content="The C Preprocessor: Wtrigraphs"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + +<meta http-equiv="Refresh" content="0; url=Invocation.html#Wtrigraphs"> + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> + +<p>The node you are looking for is at <a href="Invocation.html#Wtrigraphs">Wtrigraphs</a>.</p> +</body> diff --git a/share/doc/cpp/_005f_005fhas_005fattribute.html b/share/doc/cpp/_005f_005fhas_005fattribute.html new file mode 100644 index 0000000..67e5b17 --- /dev/null +++ b/share/doc/cpp/_005f_005fhas_005fattribute.html @@ -0,0 +1,121 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: __has_attribute</title> + +<meta name="description" content="The C Preprocessor: __has_attribute"> +<meta name="keywords" content="The C Preprocessor: __has_attribute"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Conditional-Syntax.html#Conditional-Syntax" rel="up" title="Conditional Syntax"> +<link href="_005f_005fhas_005fcpp_005fattribute.html#g_t_005f_005fhas_005fcpp_005fattribute" rel="next" title="__has_cpp_attribute"> +<link href="Elif.html#Elif" rel="previous" title="Elif"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="g_t_005f_005fhas_005fattribute"></a> +<div class="header"> +<p> +Next: <a href="_005f_005fhas_005fcpp_005fattribute.html#g_t_005f_005fhas_005fcpp_005fattribute" accesskey="n" rel="next"><code>__has_cpp_attribute</code></a>, Previous: <a href="Elif.html#Elif" accesskey="p" rel="previous">Elif</a>, Up: <a href="Conditional-Syntax.html#Conditional-Syntax" accesskey="u" rel="up">Conditional Syntax</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="g_t_005f_005fhas_005fattribute-1"></a> +<h4 class="subsection">4.2.6 <code>__has_attribute</code></h4> +<a name="index-_005f_005fhas_005fattribute"></a> + +<p>The special operator <code>__has_attribute (<var>operand</var>)</code> may be used +in ‘<samp>#if</samp>’ and ‘<samp>#elif</samp>’ expressions to test whether the attribute +referenced by its <var>operand</var> is recognized by GCC. Using the operator +in other contexts is not valid. In C code, if compiling for strict +conformance to standards before C2x, <var>operand</var> must be +a valid identifier. Otherwise, <var>operand</var> may be optionally +introduced by the <code><var>attribute-scope</var>::</code> prefix. +The <var>attribute-scope</var> prefix identifies the “namespace” within +which the attribute is recognized. The scope of GCC attributes is +‘<samp>gnu</samp>’ or ‘<samp>__gnu__</samp>’. The <code>__has_attribute</code> operator by +itself, without any <var>operand</var> or parentheses, acts as a predefined +macro so that support for it can be tested in portable code. Thus, +the recommended use of the operator is as follows: +</p> +<div class="smallexample"> +<pre class="smallexample">#if defined __has_attribute +# if __has_attribute (nonnull) +# define ATTR_NONNULL __attribute__ ((nonnull)) +# endif +#endif +</pre></div> + +<p>The first ‘<samp>#if</samp>’ test succeeds only when the operator is supported +by the version of GCC (or another compiler) being used. Only when that +test succeeds is it valid to use <code>__has_attribute</code> as a preprocessor +operator. As a result, combining the two tests into a single expression as +shown below would only be valid with a compiler that supports the operator +but not with others that don’t. +</p> +<div class="smallexample"> +<pre class="smallexample">#if defined __has_attribute && __has_attribute (nonnull) /* not portable */ +… +#endif +</pre></div> + + + + +</body> +</html> diff --git a/share/doc/cpp/_005f_005fhas_005fbuiltin.html b/share/doc/cpp/_005f_005fhas_005fbuiltin.html new file mode 100644 index 0000000..a7e3c08 --- /dev/null +++ b/share/doc/cpp/_005f_005fhas_005fbuiltin.html @@ -0,0 +1,109 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: __has_builtin</title> + +<meta name="description" content="The C Preprocessor: __has_builtin"> +<meta name="keywords" content="The C Preprocessor: __has_builtin"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Conditional-Syntax.html#Conditional-Syntax" rel="up" title="Conditional Syntax"> +<link href="_005f_005fhas_005finclude.html#g_t_005f_005fhas_005finclude" rel="next" title="__has_include"> +<link href="_005f_005fhas_005fc_005fattribute.html#g_t_005f_005fhas_005fc_005fattribute" rel="previous" title="__has_c_attribute"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="g_t_005f_005fhas_005fbuiltin"></a> +<div class="header"> +<p> +Next: <a href="_005f_005fhas_005finclude.html#g_t_005f_005fhas_005finclude" accesskey="n" rel="next"><code>__has_include</code></a>, Previous: <a href="_005f_005fhas_005fc_005fattribute.html#g_t_005f_005fhas_005fc_005fattribute" accesskey="p" rel="previous"><code>__has_c_attribute</code></a>, Up: <a href="Conditional-Syntax.html#Conditional-Syntax" accesskey="u" rel="up">Conditional Syntax</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="g_t_005f_005fhas_005fbuiltin-1"></a> +<h4 class="subsection">4.2.9 <code>__has_builtin</code></h4> +<a name="index-_005f_005fhas_005fbuiltin"></a> + +<p>The special operator <code>__has_builtin (<var>operand</var>)</code> may be used in +constant integer contexts and in preprocessor ‘<samp>#if</samp>’ and ‘<samp>#elif</samp>’ +expressions to test whether the symbol named by its <var>operand</var> is +recognized as a built-in function by GCC in the current language and +conformance mode. It evaluates to a constant integer with a nonzero +value if the argument refers to such a function, and to zero otherwise. +The operator may also be used in preprocessor ‘<samp>#if</samp>’ and ‘<samp>#elif</samp>’ +expressions. The <code>__has_builtin</code> operator by itself, without any +<var>operand</var> or parentheses, acts as a predefined macro so that support +for it can be tested in portable code. Thus, the recommended use of +the operator is as follows: +</p> +<div class="smallexample"> +<pre class="smallexample">#if defined __has_builtin +# if __has_builtin (__builtin_object_size) +# define builtin_object_size(ptr) __builtin_object_size (ptr, 2) +# endif +#endif +#ifndef builtin_object_size +# define builtin_object_size(ptr) ((size_t)-1) +#endif +</pre></div> + + + + +</body> +</html> diff --git a/share/doc/cpp/_005f_005fhas_005fc_005fattribute.html b/share/doc/cpp/_005f_005fhas_005fc_005fattribute.html new file mode 100644 index 0000000..90f1126 --- /dev/null +++ b/share/doc/cpp/_005f_005fhas_005fc_005fattribute.html @@ -0,0 +1,97 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: __has_c_attribute</title> + +<meta name="description" content="The C Preprocessor: __has_c_attribute"> +<meta name="keywords" content="The C Preprocessor: __has_c_attribute"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Conditional-Syntax.html#Conditional-Syntax" rel="up" title="Conditional Syntax"> +<link href="_005f_005fhas_005fbuiltin.html#g_t_005f_005fhas_005fbuiltin" rel="next" title="__has_builtin"> +<link href="_005f_005fhas_005fcpp_005fattribute.html#g_t_005f_005fhas_005fcpp_005fattribute" rel="previous" title="__has_cpp_attribute"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="g_t_005f_005fhas_005fc_005fattribute"></a> +<div class="header"> +<p> +Next: <a href="_005f_005fhas_005fbuiltin.html#g_t_005f_005fhas_005fbuiltin" accesskey="n" rel="next"><code>__has_builtin</code></a>, Previous: <a href="_005f_005fhas_005fcpp_005fattribute.html#g_t_005f_005fhas_005fcpp_005fattribute" accesskey="p" rel="previous"><code>__has_cpp_attribute</code></a>, Up: <a href="Conditional-Syntax.html#Conditional-Syntax" accesskey="u" rel="up">Conditional Syntax</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="g_t_005f_005fhas_005fc_005fattribute-1"></a> +<h4 class="subsection">4.2.8 <code>__has_c_attribute</code></h4> +<a name="index-_005f_005fhas_005fc_005fattribute"></a> + +<p>The special operator <code>__has_c_attribute (<var>operand</var>)</code> may be +used in ‘<samp>#if</samp>’ and ‘<samp>#elif</samp>’ expressions in C code to test +whether the attribute referenced by its <var>operand</var> is recognized by +GCC in attributes using the ‘<samp>[[]]</samp>’ syntax. GNU attributes must +be specified with the scope ‘<samp>gnu</samp>’ or ‘<samp>__gnu__</samp>’ with +<code>__has_c_attribute</code>. When <var>operand</var> designates a supported +standard attribute it evaluates to an integer constant of the form +<code>YYYYMM</code> indicating the year and month when the attribute was +first introduced into the C standard, or when the syntax of operands +to the attribute was extended in the C standard. +</p> + + + +</body> +</html> diff --git a/share/doc/cpp/_005f_005fhas_005fcpp_005fattribute.html b/share/doc/cpp/_005f_005fhas_005fcpp_005fattribute.html new file mode 100644 index 0000000..b0d9bb9 --- /dev/null +++ b/share/doc/cpp/_005f_005fhas_005fcpp_005fattribute.html @@ -0,0 +1,97 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: __has_cpp_attribute</title> + +<meta name="description" content="The C Preprocessor: __has_cpp_attribute"> +<meta name="keywords" content="The C Preprocessor: __has_cpp_attribute"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Conditional-Syntax.html#Conditional-Syntax" rel="up" title="Conditional Syntax"> +<link href="_005f_005fhas_005fc_005fattribute.html#g_t_005f_005fhas_005fc_005fattribute" rel="next" title="__has_c_attribute"> +<link href="_005f_005fhas_005fattribute.html#g_t_005f_005fhas_005fattribute" rel="previous" title="__has_attribute"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="g_t_005f_005fhas_005fcpp_005fattribute"></a> +<div class="header"> +<p> +Next: <a href="_005f_005fhas_005fc_005fattribute.html#g_t_005f_005fhas_005fc_005fattribute" accesskey="n" rel="next"><code>__has_c_attribute</code></a>, Previous: <a href="_005f_005fhas_005fattribute.html#g_t_005f_005fhas_005fattribute" accesskey="p" rel="previous"><code>__has_attribute</code></a>, Up: <a href="Conditional-Syntax.html#Conditional-Syntax" accesskey="u" rel="up">Conditional Syntax</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="g_t_005f_005fhas_005fcpp_005fattribute-1"></a> +<h4 class="subsection">4.2.7 <code>__has_cpp_attribute</code></h4> +<a name="index-_005f_005fhas_005fcpp_005fattribute"></a> + +<p>The special operator <code>__has_cpp_attribute (<var>operand</var>)</code> may be used +in ‘<samp>#if</samp>’ and ‘<samp>#elif</samp>’ expressions in C++ code to test whether +the attribute referenced by its <var>operand</var> is recognized by GCC. +<code>__has_cpp_attribute (<var>operand</var>)</code> is equivalent to +<code>__has_attribute (<var>operand</var>)</code> except that when <var>operand</var> +designates a supported standard attribute it evaluates to an integer +constant of the form <code>YYYYMM</code> indicating the year and month when +the attribute was first introduced into the C++ standard. For additional +information including the dates of the introduction of current standard +attributes, see <a href="https://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations/"><span class="nolinebreak">SD-6:</span> SG10 Feature Test Recommendations</a><!-- /@w -->. +</p> + + + +</body> +</html> diff --git a/share/doc/cpp/_005f_005fhas_005finclude.html b/share/doc/cpp/_005f_005fhas_005finclude.html new file mode 100644 index 0000000..f386b51 --- /dev/null +++ b/share/doc/cpp/_005f_005fhas_005finclude.html @@ -0,0 +1,120 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: __has_include</title> + +<meta name="description" content="The C Preprocessor: __has_include"> +<meta name="keywords" content="The C Preprocessor: __has_include"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Conditional-Syntax.html#Conditional-Syntax" rel="up" title="Conditional Syntax"> +<link href="Deleted-Code.html#Deleted-Code" rel="next" title="Deleted Code"> +<link href="_005f_005fhas_005fbuiltin.html#g_t_005f_005fhas_005fbuiltin" rel="previous" title="__has_builtin"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="g_t_005f_005fhas_005finclude"></a> +<div class="header"> +<p> +Previous: <a href="_005f_005fhas_005fbuiltin.html#g_t_005f_005fhas_005fbuiltin" accesskey="p" rel="previous"><code>__has_builtin</code></a>, Up: <a href="Conditional-Syntax.html#Conditional-Syntax" accesskey="u" rel="up">Conditional Syntax</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="g_t_005f_005fhas_005finclude-1"></a> +<h4 class="subsection">4.2.10 <code>__has_include</code></h4> +<a name="index-_005f_005fhas_005finclude"></a> + +<p>The special operator <code>__has_include (<var>operand</var>)</code> may be used in +‘<samp>#if</samp>’ and ‘<samp>#elif</samp>’ expressions to test whether the header referenced +by its <var>operand</var> can be included using the ‘<samp>#include</samp>’ directive. Using +the operator in other contexts is not valid. The <var>operand</var> takes +the same form as the file in the ‘<samp>#include</samp>’ directive (see <a href="Include-Syntax.html#Include-Syntax">Include Syntax</a>) and evaluates to a nonzero value if the header can be included and +to zero otherwise. Note that that the ability to include a header doesn’t +imply that the header doesn’t contain invalid constructs or ‘<samp>#error</samp>’ +directives that would cause the preprocessor to fail. +</p> +<p>The <code>__has_include</code> operator by itself, without any <var>operand</var> or +parentheses, acts as a predefined macro so that support for it can be tested +in portable code. Thus, the recommended use of the operator is as follows: +</p> +<div class="smallexample"> +<pre class="smallexample">#if defined __has_include +# if __has_include (<stdatomic.h>) +# include <stdatomic.h> +# endif +#endif +</pre></div> + +<p>The first ‘<samp>#if</samp>’ test succeeds only when the operator is supported +by the version of GCC (or another compiler) being used. Only when that +test succeeds is it valid to use <code>__has_include</code> as a preprocessor +operator. As a result, combining the two tests into a single expression +as shown below would only be valid with a compiler that supports the operator +but not with others that don’t. +</p> +<div class="smallexample"> +<pre class="smallexample">#if defined __has_include && __has_include ("header.h") /* not portable */ +… +#endif +</pre></div> + + + + +</body> +</html> diff --git a/share/doc/cpp/dashMF.html b/share/doc/cpp/dashMF.html new file mode 100644 index 0000000..1eae254 --- /dev/null +++ b/share/doc/cpp/dashMF.html @@ -0,0 +1,70 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<!-- This file redirects to the location of a node or anchor --> +<head> +<title>The C Preprocessor: dashMF</title> + +<meta name="description" content="The C Preprocessor: dashMF"> +<meta name="keywords" content="The C Preprocessor: dashMF"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + +<meta http-equiv="Refresh" content="0; url=Invocation.html#dashMF"> + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> + +<p>The node you are looking for is at <a href="Invocation.html#dashMF">dashMF</a>.</p> +</body> diff --git a/share/doc/cpp/fdollars_002din_002didentifiers.html b/share/doc/cpp/fdollars_002din_002didentifiers.html new file mode 100644 index 0000000..bfc3a03 --- /dev/null +++ b/share/doc/cpp/fdollars_002din_002didentifiers.html @@ -0,0 +1,70 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<!-- This file redirects to the location of a node or anchor --> +<head> +<title>The C Preprocessor: fdollars-in-identifiers</title> + +<meta name="description" content="The C Preprocessor: fdollars-in-identifiers"> +<meta name="keywords" content="The C Preprocessor: fdollars-in-identifiers"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + +<meta http-equiv="Refresh" content="0; url=Invocation.html#fdollars_002din_002didentifiers"> + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> + +<p>The node you are looking for is at <a href="Invocation.html#fdollars_002din_002didentifiers">fdollars-in-identifiers</a>.</p> +</body> diff --git a/share/doc/cpp/index.html b/share/doc/cpp/index.html new file mode 100644 index 0000000..2231f72 --- /dev/null +++ b/share/doc/cpp/index.html @@ -0,0 +1,390 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Top</title> + +<meta name="description" content="The C Preprocessor: Top"> +<meta name="keywords" content="The C Preprocessor: Top"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="#Top" rel="start" title="Top"> +<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives"> +<link href="#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="../dir/index.html" rel="up" title="(dir)"> +<link href="Overview.html#Overview" rel="next" title="Overview"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<h1 class="settitle" align="center">The C Preprocessor</h1> + + + + + + + + + + + + + + + +<a name="SEC_Contents"></a> +<h2 class="contents-heading">Table of Contents</h2> + +<div class="contents"> + +<ul class="no-bullet"> + <li><a name="toc-Overview-1" href="Overview.html#Overview">1 Overview</a> + <ul class="no-bullet"> + <li><a name="toc-Character-sets-1" href="Character-sets.html#Character-sets">1.1 Character sets</a></li> + <li><a name="toc-Initial-processing-1" href="Initial-processing.html#Initial-processing">1.2 Initial processing</a></li> + <li><a name="toc-Tokenization-1" href="Tokenization.html#Tokenization">1.3 Tokenization</a></li> + <li><a name="toc-The-preprocessing-language-1" href="The-preprocessing-language.html#The-preprocessing-language">1.4 The preprocessing language</a></li> + </ul></li> + <li><a name="toc-Header-Files-1" href="Header-Files.html#Header-Files">2 Header Files</a> + <ul class="no-bullet"> + <li><a name="toc-Include-Syntax-1" href="Include-Syntax.html#Include-Syntax">2.1 Include Syntax</a></li> + <li><a name="toc-Include-Operation-1" href="Include-Operation.html#Include-Operation">2.2 Include Operation</a></li> + <li><a name="toc-Search-Path-1" href="Search-Path.html#Search-Path">2.3 Search Path</a></li> + <li><a name="toc-Once_002dOnly-Headers-1" href="Once_002dOnly-Headers.html#Once_002dOnly-Headers">2.4 Once-Only Headers</a></li> + <li><a name="toc-Alternatives-to-Wrapper-_0023ifndef-1" href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef">2.5 Alternatives to Wrapper #ifndef</a></li> + <li><a name="toc-Computed-Includes-1" href="Computed-Includes.html#Computed-Includes">2.6 Computed Includes</a></li> + <li><a name="toc-Wrapper-Headers-1" href="Wrapper-Headers.html#Wrapper-Headers">2.7 Wrapper Headers</a></li> + <li><a name="toc-System-Headers-1" href="System-Headers.html#System-Headers">2.8 System Headers</a></li> + </ul></li> + <li><a name="toc-Macros-1" href="Macros.html#Macros">3 Macros</a> + <ul class="no-bullet"> + <li><a name="toc-Object_002dlike-Macros-1" href="Object_002dlike-Macros.html#Object_002dlike-Macros">3.1 Object-like Macros</a></li> + <li><a name="toc-Function_002dlike-Macros-1" href="Function_002dlike-Macros.html#Function_002dlike-Macros">3.2 Function-like Macros</a></li> + <li><a name="toc-Macro-Arguments-1" href="Macro-Arguments.html#Macro-Arguments">3.3 Macro Arguments</a></li> + <li><a name="toc-Stringizing-1" href="Stringizing.html#Stringizing">3.4 Stringizing</a></li> + <li><a name="toc-Concatenation-1" href="Concatenation.html#Concatenation">3.5 Concatenation</a></li> + <li><a name="toc-Variadic-Macros-1" href="Variadic-Macros.html#Variadic-Macros">3.6 Variadic Macros</a></li> + <li><a name="toc-Predefined-Macros-1" href="Predefined-Macros.html#Predefined-Macros">3.7 Predefined Macros</a> + <ul class="no-bullet"> + <li><a name="toc-Standard-Predefined-Macros-1" href="Standard-Predefined-Macros.html#Standard-Predefined-Macros">3.7.1 Standard Predefined Macros</a></li> + <li><a name="toc-Common-Predefined-Macros-1" href="Common-Predefined-Macros.html#Common-Predefined-Macros">3.7.2 Common Predefined Macros</a></li> + <li><a name="toc-System_002dspecific-Predefined-Macros-1" href="System_002dspecific-Predefined-Macros.html#System_002dspecific-Predefined-Macros">3.7.3 System-specific Predefined Macros</a></li> + <li><a name="toc-C_002b_002b-Named-Operators-1" href="C_002b_002b-Named-Operators.html#C_002b_002b-Named-Operators">3.7.4 C++ Named Operators</a></li> + </ul></li> + <li><a name="toc-Undefining-and-Redefining-Macros-1" href="Undefining-and-Redefining-Macros.html#Undefining-and-Redefining-Macros">3.8 Undefining and Redefining Macros</a></li> + <li><a name="toc-Directives-Within-Macro-Arguments-1" href="Directives-Within-Macro-Arguments.html#Directives-Within-Macro-Arguments">3.9 Directives Within Macro Arguments</a></li> + <li><a name="toc-Macro-Pitfalls-1" href="Macro-Pitfalls.html#Macro-Pitfalls">3.10 Macro Pitfalls</a> + <ul class="no-bullet"> + <li><a name="toc-Misnesting-1" href="Misnesting.html#Misnesting">3.10.1 Misnesting</a></li> + <li><a name="toc-Operator-Precedence-Problems-1" href="Operator-Precedence-Problems.html#Operator-Precedence-Problems">3.10.2 Operator Precedence Problems</a></li> + <li><a name="toc-Swallowing-the-Semicolon-1" href="Swallowing-the-Semicolon.html#Swallowing-the-Semicolon">3.10.3 Swallowing the Semicolon</a></li> + <li><a name="toc-Duplication-of-Side-Effects-1" href="Duplication-of-Side-Effects.html#Duplication-of-Side-Effects">3.10.4 Duplication of Side Effects</a></li> + <li><a name="toc-Self_002dReferential-Macros-1" href="Self_002dReferential-Macros.html#Self_002dReferential-Macros">3.10.5 Self-Referential Macros</a></li> + <li><a name="toc-Argument-Prescan-1" href="Argument-Prescan.html#Argument-Prescan">3.10.6 Argument Prescan</a></li> + <li><a name="toc-Newlines-in-Arguments-1" href="Newlines-in-Arguments.html#Newlines-in-Arguments">3.10.7 Newlines in Arguments</a></li> + </ul></li> + </ul></li> + <li><a name="toc-Conditionals-1" href="Conditionals.html#Conditionals">4 Conditionals</a> + <ul class="no-bullet"> + <li><a name="toc-Conditional-Uses-1" href="Conditional-Uses.html#Conditional-Uses">4.1 Conditional Uses</a></li> + <li><a name="toc-Conditional-Syntax-1" href="Conditional-Syntax.html#Conditional-Syntax">4.2 Conditional Syntax</a> + <ul class="no-bullet"> + <li><a name="toc-Ifdef-1" href="Ifdef.html#Ifdef">4.2.1 Ifdef</a></li> + <li><a name="toc-If-1" href="If.html#If">4.2.2 If</a></li> + <li><a name="toc-Defined-1" href="Defined.html#Defined">4.2.3 Defined</a></li> + <li><a name="toc-Else-1" href="Else.html#Else">4.2.4 Else</a></li> + <li><a name="toc-Elif-1" href="Elif.html#Elif">4.2.5 Elif</a></li> + <li><a name="toc-_005f_005fhas_005fattribute-1" href="_005f_005fhas_005fattribute.html#g_t_005f_005fhas_005fattribute">4.2.6 <code>__has_attribute</code></a></li> + <li><a name="toc-_005f_005fhas_005fcpp_005fattribute-1" href="_005f_005fhas_005fcpp_005fattribute.html#g_t_005f_005fhas_005fcpp_005fattribute">4.2.7 <code>__has_cpp_attribute</code></a></li> + <li><a name="toc-_005f_005fhas_005fc_005fattribute-1" href="_005f_005fhas_005fc_005fattribute.html#g_t_005f_005fhas_005fc_005fattribute">4.2.8 <code>__has_c_attribute</code></a></li> + <li><a name="toc-_005f_005fhas_005fbuiltin-1" href="_005f_005fhas_005fbuiltin.html#g_t_005f_005fhas_005fbuiltin">4.2.9 <code>__has_builtin</code></a></li> + <li><a name="toc-_005f_005fhas_005finclude-1" href="_005f_005fhas_005finclude.html#g_t_005f_005fhas_005finclude">4.2.10 <code>__has_include</code></a></li> + </ul></li> + <li><a name="toc-Deleted-Code-1" href="Deleted-Code.html#Deleted-Code">4.3 Deleted Code</a></li> + </ul></li> + <li><a name="toc-Diagnostics-1" href="Diagnostics.html#Diagnostics">5 Diagnostics</a></li> + <li><a name="toc-Line-Control-1" href="Line-Control.html#Line-Control">6 Line Control</a></li> + <li><a name="toc-Pragmas-1" href="Pragmas.html#Pragmas">7 Pragmas</a></li> + <li><a name="toc-Other-Directives-1" href="Other-Directives.html#Other-Directives">8 Other Directives</a></li> + <li><a name="toc-Preprocessor-Output-1" href="Preprocessor-Output.html#Preprocessor-Output">9 Preprocessor Output</a></li> + <li><a name="toc-Traditional-Mode-1" href="Traditional-Mode.html#Traditional-Mode">10 Traditional Mode</a> + <ul class="no-bullet"> + <li><a name="toc-Traditional-lexical-analysis-1" href="Traditional-lexical-analysis.html#Traditional-lexical-analysis">10.1 Traditional lexical analysis</a></li> + <li><a name="toc-Traditional-macros-1" href="Traditional-macros.html#Traditional-macros">10.2 Traditional macros</a></li> + <li><a name="toc-Traditional-miscellany-1" href="Traditional-miscellany.html#Traditional-miscellany">10.3 Traditional miscellany</a></li> + <li><a name="toc-Traditional-warnings-1" href="Traditional-warnings.html#Traditional-warnings">10.4 Traditional warnings</a></li> + </ul></li> + <li><a name="toc-Implementation-Details-1" href="Implementation-Details.html#Implementation-Details">11 Implementation Details</a> + <ul class="no-bullet"> + <li><a name="toc-Implementation_002ddefined-behavior-1" href="Implementation_002ddefined-behavior.html#Implementation_002ddefined-behavior">11.1 Implementation-defined behavior</a></li> + <li><a name="toc-Implementation-limits-1" href="Implementation-limits.html#Implementation-limits">11.2 Implementation limits</a></li> + <li><a name="toc-Obsolete-Features-1" href="Obsolete-Features.html#Obsolete-Features">11.3 Obsolete Features</a> + <ul class="no-bullet"> + <li><a name="toc-Assertions" href="Obsolete-Features.html#Assertions">11.3.1 Assertions</a></li> + </ul></li> + </ul></li> + <li><a name="toc-Invocation-1" href="Invocation.html#Invocation">12 Invocation</a></li> + <li><a name="toc-Environment-Variables-1" href="Environment-Variables.html#Environment-Variables">13 Environment Variables</a></li> + <li><a name="toc-GNU-Free-Documentation-License-1" href="GNU-Free-Documentation-License.html#GNU-Free-Documentation-License">GNU Free Documentation License</a> + <ul class="no-bullet"> + <li><a name="toc-ADDENDUM_003a-How-to-use-this-License-for-your-documents" href="GNU-Free-Documentation-License.html#ADDENDUM_003a-How-to-use-this-License-for-your-documents">ADDENDUM: How to use this License for your documents</a></li> + </ul></li> + <li><a name="toc-Index-of-Directives-1" href="Index-of-Directives.html#Index-of-Directives">Index of Directives</a></li> + <li><a name="toc-Option-Index-1" href="Option-Index.html#Option-Index">Option Index</a></li> + <li><a name="toc-Concept-Index-1" href="Concept-Index.html#Concept-Index">Concept Index</a></li> +</ul> +</div> + + +<a name="Top"></a> +<div class="header"> +<p> +Next: <a href="Overview.html#Overview" accesskey="n" rel="next">Overview</a>, Up: <a href="../dir/index.html" accesskey="u" rel="up">(dir)</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="SEC_Top"></a> +<p>The C preprocessor implements the macro language used to transform C, +C++, and Objective-C programs before they are compiled. It can also be +useful on its own. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="Overview.html#Overview" accesskey="1">Overview</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Header-Files.html#Header-Files" accesskey="2">Header Files</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Macros.html#Macros" accesskey="3">Macros</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Conditionals.html#Conditionals" accesskey="4">Conditionals</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Diagnostics.html#Diagnostics" accesskey="5">Diagnostics</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Line-Control.html#Line-Control" accesskey="6">Line Control</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Pragmas.html#Pragmas" accesskey="7">Pragmas</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Other-Directives.html#Other-Directives" accesskey="8">Other Directives</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Preprocessor-Output.html#Preprocessor-Output" accesskey="9">Preprocessor Output</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Traditional-Mode.html#Traditional-Mode">Traditional Mode</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Implementation-Details.html#Implementation-Details">Implementation Details</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Invocation.html#Invocation">Invocation</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Environment-Variables.html#Environment-Variables">Environment Variables</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="GNU-Free-Documentation-License.html#GNU-Free-Documentation-License">GNU Free Documentation License</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Index-of-Directives.html#Index-of-Directives">Index of Directives</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Option-Index.html#Option-Index">Option Index</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Concept-Index.html#Concept-Index">Concept Index</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> +</pre></th></tr><tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> — The Detailed Node Listing — + +Overview + +</pre></th></tr><tr><td align="left" valign="top">• <a href="Character-sets.html#Character-sets">Character sets</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Initial-processing.html#Initial-processing">Initial processing</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Tokenization.html#Tokenization">Tokenization</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="The-preprocessing-language.html#The-preprocessing-language">The preprocessing language</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> +Header Files + +</pre></th></tr><tr><td align="left" valign="top">• <a href="Include-Syntax.html#Include-Syntax">Include Syntax</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Include-Operation.html#Include-Operation">Include Operation</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Search-Path.html#Search-Path">Search Path</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Once_002dOnly-Headers.html#Once_002dOnly-Headers">Once-Only Headers</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef">Alternatives to Wrapper #ifndef</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Computed-Includes.html#Computed-Includes">Computed Includes</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Wrapper-Headers.html#Wrapper-Headers">Wrapper Headers</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="System-Headers.html#System-Headers">System Headers</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> +Macros + +</pre></th></tr><tr><td align="left" valign="top">• <a href="Object_002dlike-Macros.html#Object_002dlike-Macros">Object-like Macros</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Function_002dlike-Macros.html#Function_002dlike-Macros">Function-like Macros</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Macro-Arguments.html#Macro-Arguments">Macro Arguments</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Stringizing.html#Stringizing">Stringizing</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Concatenation.html#Concatenation">Concatenation</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Variadic-Macros.html#Variadic-Macros">Variadic Macros</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Predefined-Macros.html#Predefined-Macros">Predefined Macros</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Undefining-and-Redefining-Macros.html#Undefining-and-Redefining-Macros">Undefining and Redefining Macros</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Directives-Within-Macro-Arguments.html#Directives-Within-Macro-Arguments">Directives Within Macro Arguments</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Macro-Pitfalls.html#Macro-Pitfalls">Macro Pitfalls</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> +Predefined Macros + +</pre></th></tr><tr><td align="left" valign="top">• <a href="Standard-Predefined-Macros.html#Standard-Predefined-Macros">Standard Predefined Macros</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Common-Predefined-Macros.html#Common-Predefined-Macros">Common Predefined Macros</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="System_002dspecific-Predefined-Macros.html#System_002dspecific-Predefined-Macros">System-specific Predefined Macros</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="C_002b_002b-Named-Operators.html#C_002b_002b-Named-Operators">C++ Named Operators</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> +Macro Pitfalls + +</pre></th></tr><tr><td align="left" valign="top">• <a href="Misnesting.html#Misnesting">Misnesting</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Operator-Precedence-Problems.html#Operator-Precedence-Problems">Operator Precedence Problems</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Swallowing-the-Semicolon.html#Swallowing-the-Semicolon">Swallowing the Semicolon</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Duplication-of-Side-Effects.html#Duplication-of-Side-Effects">Duplication of Side Effects</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Self_002dReferential-Macros.html#Self_002dReferential-Macros">Self-Referential Macros</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Argument-Prescan.html#Argument-Prescan">Argument Prescan</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Newlines-in-Arguments.html#Newlines-in-Arguments">Newlines in Arguments</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> +Conditionals + +</pre></th></tr><tr><td align="left" valign="top">• <a href="Conditional-Uses.html#Conditional-Uses">Conditional Uses</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Conditional-Syntax.html#Conditional-Syntax">Conditional Syntax</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Deleted-Code.html#Deleted-Code">Deleted Code</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> +Conditional Syntax + +</pre></th></tr><tr><td align="left" valign="top">• <a href="Ifdef.html#Ifdef">Ifdef</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="If.html#If">If</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Defined.html#Defined">Defined</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Else.html#Else">Else</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Elif.html#Elif">Elif</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> +Implementation Details + +</pre></th></tr><tr><td align="left" valign="top">• <a href="Implementation_002ddefined-behavior.html#Implementation_002ddefined-behavior">Implementation-defined behavior</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Implementation-limits.html#Implementation-limits">Implementation limits</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="Obsolete-Features.html#Obsolete-Features">Obsolete Features</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> +Obsolete Features + +</pre></th></tr><tr><td align="left" valign="top">• <a href="Obsolete-Features.html#Obsolete-Features">Obsolete Features</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> +</pre></th></tr></table> + +<p>Copyright © 1987-2023 Free Software Foundation, Inc. +</p> +<p>Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled “GNU Free Documentation License”. +</p> +<p>This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). +</p> +<p>(a) The FSF’s Front-Cover Text is: +</p> +<p>A GNU Manual +</p> +<p>(b) The FSF’s Back-Cover Text is: +</p> +<p>You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. +</p> + +<hr> +<div class="header"> +<p> +Next: <a href="Overview.html#Overview" accesskey="n" rel="next">Overview</a>, Up: <a href="../dir/index.html" accesskey="u" rel="up">(dir)</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> diff --git a/share/doc/cpp/trigraphs.html b/share/doc/cpp/trigraphs.html new file mode 100644 index 0000000..595d608 --- /dev/null +++ b/share/doc/cpp/trigraphs.html @@ -0,0 +1,70 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +section entitled "GNU Free Documentation License". + +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + +A GNU Manual + +(b) The FSF's Back-Cover Text is: + +You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<!-- This file redirects to the location of a node or anchor --> +<head> +<title>The C Preprocessor: trigraphs</title> + +<meta name="description" content="The C Preprocessor: trigraphs"> +<meta name="keywords" content="The C Preprocessor: trigraphs"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + +<meta http-equiv="Refresh" content="0; url=Initial-processing.html#trigraphs"> + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> + +<p>The node you are looking for is at <a href="Initial-processing.html#trigraphs">trigraphs</a>.</p> +</body> |