Revert "sphinx: remove texinfo files"

This reverts commit 54ca4eef58661a7d7a511e2bbbe309bde1732abf.

1 files changed, 4600 insertions, 0 deletions

diff --git a/gcc/doc/cpp.texi b/gcc/doc/cpp.texi
new file mode 100644
index 0000000..90b2767
--- /dev/null
+++ b/gcc/doc/cpp.texi
@@ -0,0 +1,4600 @@
+\input texinfo
+@setfilename cpp.info
+@settitle The C Preprocessor
+@setchapternewpage off
+@c @smallbook
+@c @cropmarks
+@c @finalout
+
+@include gcc-common.texi
+
+@copying
+@c man begin COPYRIGHT
+Copyright @copyright{} 1987-2022 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
+@c man end
+section entitled ``GNU Free Documentation License''.
+@ignore
+@c man begin COPYRIGHT
+man page gfdl(7).
+@c man end
+@end ignore
+
+@c man begin COPYRIGHT
+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.
+@c man end
+@end copying
+
+@c Create a separate index for command line options.
+@defcodeindex op
+@syncodeindex vr op
+
+@c Used in cppopts.texi and cppenv.texi.
+@set cppmanual
+
+@ifinfo
+@dircategory Software development
+@direntry
+* Cpp: (cpp).                  The GNU C preprocessor.
+@end direntry
+@end ifinfo
+
+@titlepage
+@title The C Preprocessor
+@versionsubtitle
+@author Richard M. Stallman, Zachary Weinberg
+@page
+@c There is a fill at the bottom of the page, so we need a filll to
+@c override it.
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+@contents
+@page
+
+@ifnottex
+@node Top
+@top
+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.
+
+@menu
+* Overview::
+* Header Files::
+* Macros::
+* Conditionals::
+* Diagnostics::
+* Line Control::
+* Pragmas::
+* Other Directives::
+* Preprocessor Output::
+* Traditional Mode::
+* Implementation Details::
+* Invocation::
+* Environment Variables::
+* GNU Free Documentation License::
+* Index of Directives::
+* Option Index::
+* Concept Index::
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Overview
+
+* Character sets::
+* Initial processing::
+* Tokenization::
+* The preprocessing language::
+
+Header Files
+
+* Include Syntax::
+* Include Operation::
+* Search Path::
+* Once-Only Headers::
+* Alternatives to Wrapper #ifndef::
+* Computed Includes::
+* Wrapper Headers::
+* System Headers::
+
+Macros
+
+* Object-like Macros::
+* Function-like Macros::
+* Macro Arguments::
+* Stringizing::
+* Concatenation::
+* Variadic Macros::
+* Predefined Macros::
+* Undefining and Redefining Macros::
+* Directives Within Macro Arguments::
+* Macro Pitfalls::
+
+Predefined Macros
+
+* Standard Predefined Macros::
+* Common Predefined Macros::
+* System-specific Predefined Macros::
+* C++ Named Operators::
+
+Macro Pitfalls
+
+* Misnesting::
+* Operator Precedence Problems::
+* Swallowing the Semicolon::
+* Duplication of Side Effects::
+* Self-Referential Macros::
+* Argument Prescan::
+* Newlines in Arguments::
+
+Conditionals
+
+* Conditional Uses::
+* Conditional Syntax::
+* Deleted Code::
+
+Conditional Syntax
+
+* Ifdef::
+* If::
+* Defined::
+* Else::
+* Elif::
+
+Implementation Details
+
+* Implementation-defined behavior::
+* Implementation limits::
+* Obsolete Features::
+
+Obsolete Features
+
+* Obsolete Features::
+
+@end detailmenu
+@end menu
+
+@insertcopying
+@end ifnottex
+
+@node Overview
+@chapter Overview
+@c man begin DESCRIPTION
+The C preprocessor, often known as @dfn{cpp}, is a @dfn{macro processor}
+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 @dfn{macros}, which are brief abbreviations for longer
+constructs.
+
+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.
+
+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.  @option{-traditional-cpp}
+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.
+
+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.
+
+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 @option{-std=c90}, @option{-std=c99},
+@option{-std=c11} or @option{-std=c17} options, depending
+on which version of the standard you want.  To get all the mandatory
+diagnostics, you must also use @option{-pedantic}.  @xref{Invocation}.
+
+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 @ref{Traditional
+Mode}.
+
+For clarity, unless noted otherwise, references to @samp{CPP} in this
+manual refer to GNU CPP@.
+@c man end
+
+@menu
+* Character sets::
+* Initial processing::
+* Tokenization::
+* The preprocessing language::
+@end menu
+
+@node Character sets
+@section Character sets
+
+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.
+
+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 @dfn{source}
+character set.  It must be isomorphic with ISO 10646, also known as
+Unicode.  CPP uses the UTF-8 encoding of Unicode.
+
+The character sets of the input files are specified using the
+@option{-finput-charset=} option.
+
+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 @option{-E} option, it will be
+in UTF-8.
+
+After preprocessing is complete, string and character constants are
+converted again, into the @dfn{execution} 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} type, in the target machine's byte
+order.@footnote{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} is enshrined in some system ABIs so we cannot fix
+this.}  Octal and hexadecimal escape sequences do not undergo
+conversion; @t{'\x12'} 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.
+
+In identifiers, characters outside the ASCII range can be specified
+with the @samp{\u} and @samp{\U} escapes or used directly in the input
+encoding.  If strict ISO C90 conformance is specified with an option
+such as @option{-std=c90}, or @option{-fno-extended-identifiers} is
+used, then those constructs are not permitted in identifiers.
+
+@node Initial processing
+@section Initial processing
+
+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.
+
+@enumerate
+@item
+@cindex line endings
+The input file is read into memory and broken into lines.
+
+Different systems use different conventions to indicate the end of a
+line.  GCC accepts the ASCII control sequences @kbd{LF}, @kbd{@w{CR
+LF}} and @kbd{CR} 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.)
+
+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.
+
+@item
+@cindex trigraphs
+@anchor{trigraphs}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 @option{-std}
+option, or you specify the @option{-trigraphs} option, then it
+converts them.
+
+These are nine three-character sequences, all starting with @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{??/} stands for @samp{\}, so @t{'??/n'} is a character
+constant for a newline.
+
+Trigraphs are not popular and many compilers implement them
+incorrectly.  Portable code should not rely on trigraphs being either
+converted or ignored.  With @option{-Wtrigraphs} GCC will warn you
+when a trigraph may change the meaning of your program if it were
+converted.  @xref{Wtrigraphs}.
+
+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.  @t{"(??\?)"}
+is the string @samp{(???)}, not @samp{(?]}.  Traditional C compilers
+do not recognize these idioms.
+
+The nine trigraphs and their replacements are
+
+@smallexample
+Trigraph:       ??(  ??)  ??<  ??>  ??=  ??/  ??'  ??!  ??-
+Replacement:      [    ]    @{    @}    #    \    ^    |    ~
+@end smallexample
+
+@item
+@cindex continued lines
+@cindex backslash-newline
+Continued lines are merged into one long line.
+
+A continued line is a line which ends with a backslash, @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.)
+
+The trailing backslash on a continued line is commonly referred to as a
+@dfn{backslash-newline}.
+
+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.
+
+@item
+@cindex comments
+@cindex line comments
+@cindex block comments
+All comments are replaced with single spaces.
+
+There are two kinds of comments.  @dfn{Block comments} begin with
+@samp{/*} and continue until the next @samp{*/}.  Block comments do not
+nest:
+
+@smallexample
+/* @r{this is} /* @r{one comment} */ @r{text outside comment}
+@end smallexample
+
+@dfn{Line comments} begin with @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.
+
+@smallexample
+// @r{this is} // @r{one comment}
+@r{text outside comment}
+@end smallexample
+@end enumerate
+
+It is safe to put line comments inside block comments, or vice versa.
+
+@smallexample
+@group
+/* @r{block comment}
+   // @r{contains line comment}
+   @r{yet more comment}
+ */ @r{outside comment}
+
+// @r{line comment} /* @r{contains block comment} */
+@end group
+@end smallexample
+
+But beware of commenting out one end of a block comment with a line
+comment.
+
+@smallexample
+@group
+ // @r{l.c.}  /* @r{block comment begins}
+    @r{oops! this isn't a comment anymore} */
+@end group
+@end smallexample
+
+Comments are not recognized within string literals.
+@t{@w{"/* blah */"}} is the string constant @samp{@w{/* blah */}}, not
+an empty string.
+
+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.
+
+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{*/}, and @samp{//} onto multiple lines with backslash-newline.
+For example:
+
+@smallexample
+@group
+/\
+*
+*/ # /*
+*/ defi\
+ne FO\
+O 10\
+20
+@end group
+@end smallexample
+
+@noindent
+is equivalent to @code{@w{#define FOO 1020}}.  All these tricks are
+extremely confusing and should not be used in code intended to be
+readable.
+
+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.
+
+@node Tokenization
+@section Tokenization
+
+@cindex tokens
+@cindex preprocessing tokens
+After the textual transformations are finished, the input file is
+converted into a sequence of @dfn{preprocessing tokens}.  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.
+
+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} is interpreted as
+@code{@w{a ++ ++ + b}}, not as @code{@w{a ++ + ++ b}}, even though the
+latter tokenization could be part of a valid C program and the former
+could not.
+
+Once the input file is broken into tokens, the token boundaries never
+change, except when the @samp{##} preprocessing operator is used to paste
+tokens together.  @xref{Concatenation}.  For example,
+
+@smallexample
+@group
+#define foo() bar
+foo()baz
+     @expansion{} bar baz
+@emph{not}
+     @expansion{} barbaz
+@end group
+@end smallexample
+
+The compiler does not re-tokenize the preprocessor's output.  Each
+preprocessing token becomes one compiler token.
+
+@cindex identifiers
+Preprocessing tokens fall into five broad classes: identifiers,
+preprocessing numbers, string literals, punctuators, and other.  An
+@dfn{identifier} 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}.  @xref{Defined}.
+
+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.  @xref{C++ Named Operators}.
+
+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} and @samp{\U} escape sequences.
+
+As an extension, GCC treats @samp{$} as a letter.  This is for
+compatibility with some systems, such as VMS, where @samp{$} is commonly
+used in system-defined function and object names.  @samp{$} is not a
+letter in strictly conforming mode, or if you specify the @option{-$}
+option.  @xref{Invocation}.
+
+@cindex numbers
+@cindex preprocessing numbers
+A @dfn{preprocessing number} 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{e-}, @samp{E+}, @samp{E-}, @samp{p+}, @samp{p-}, @samp{P+}, and
+@samp{P-}.  (The exponents that begin with @samp{p} or @samp{P} are 
+used for hexadecimal floating-point constants.)
+
+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{##} operator.
+
+It's possible for preprocessing numbers to cause programs to be
+misinterpreted.  For example, @code{0xE+12} is a preprocessing number
+which does not translate to any valid numeric constant, therefore a
+syntax error.  It does not mean @code{@w{0xE + 12}}, which is what you
+might have intended.
+
+@cindex string literals
+@cindex string constants
+@cindex character constants
+@cindex header file names
+@c the @: prevents makeinfo from turning '' into ".
+@dfn{String literals} are string constants, character constants, and
+header file names (the argument of @samp{#include}).@footnote{The C
+standard uses the term @dfn{string literal} to refer only to what we are
+calling @dfn{string constants}.}  String constants and character
+constants are straightforward: @t{"@dots{}"} or @t{'@dots{}'}.  In
+either case embedded quotes should be escaped with a backslash:
+@t{'\'@:'} is the character constant for @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.  @xref{Implementation Details}.
+
+Header file names either look like string constants, @t{"@dots{}"}, or are
+written with angle brackets instead, @t{<@dots{}>}.  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.  @xref{Include
+Operation}.
+
+No string literal may extend past the end of a line.  You may use continued
+lines instead, or string constant concatenation.
+
+@cindex punctuators
+@cindex digraphs
+@cindex alternative tokens
+@dfn{Punctuators} 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{$}, and
+@samp{`}.  In addition, all the two- and three-character operators are
+punctuators.  There are also six @dfn{digraphs}, which the C++ standard
+calls @dfn{alternative tokens}, 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:
+
+@smallexample
+Digraph:        <%  %>  <:  :>  %:  %:%:
+Punctuator:      @{   @}   [   ]   #    ##
+@end smallexample
+
+@cindex other tokens
+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{`}, and control
+characters other than NUL (all bits zero).  (Note that @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.
+
+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.
+
+@smallexample
+#define X^@@1
+#define X 1
+@end smallexample
+
+@noindent
+(where @samp{^@@} is ASCII NUL)@.  Within string or character constants,
+NULs are preserved.  In the latter two cases the preprocessor emits a
+warning message.
+
+@node The preprocessing language
+@section The preprocessing language
+@cindex directives
+@cindex preprocessing directives
+@cindex directive line
+@cindex directive name
+
+After tokenization, the stream of tokens may simply be passed straight
+to the compiler's parser.  However, if it contains any operations in the
+@dfn{preprocessing language}, 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.
+
+The preprocessing language consists of @dfn{directives} to be executed
+and @dfn{macros} to be expanded.  Its primary capabilities are:
+
+@itemize @bullet
+@item
+Inclusion of header files.  These are files of declarations that can be
+substituted into your program.
+
+@item
+Macro expansion.  You can define @dfn{macros}, 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.
+
+@item
+Conditional compilation.  You can include or exclude parts of the
+program according to various conditions.
+
+@item
+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.
+
+@item
+Diagnostics.  You can detect problems at compile time and issue errors
+or warnings.
+@end itemize
+
+There are a few more, less useful, features.
+
+Except for expansion of predefined macros, all these operations are
+triggered with @dfn{preprocessing directives}.  Preprocessing directives
+are lines in your program that start with @samp{#}.  Whitespace is
+allowed before and after the @samp{#}.  The @samp{#} is followed by an
+identifier, the @dfn{directive name}.  It specifies the operation to
+perform.  Directives are commonly referred to as @samp{#@var{name}}
+where @var{name} is the directive name.  For example, @samp{#define} is
+the directive that defines a macro.
+
+The @samp{#} which begins a directive cannot come from a macro
+expansion.  Also, the directive name is not macro expanded.  Thus, if
+@code{foo} is defined as a macro expanding to @code{define}, that does
+not make @samp{#foo} a valid preprocessing directive.
+
+The set of valid directive names is fixed.  Programs cannot define new
+preprocessing directives.
+
+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} must be followed by a macro
+name and the intended expansion of the macro.
+
+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.
+
+@node Header Files
+@chapter Header Files
+
+@cindex header file
+A header file is a file containing C declarations and macro definitions
+(@pxref{Macros}) to be shared between several source files.  You request
+the use of a header file in your program by @dfn{including} it, with the
+C preprocessing directive @samp{#include}.
+
+Header files serve two purposes.
+
+@itemize @bullet
+@item
+@cindex system header files
+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.
+
+@item
+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.
+@end itemize
+
+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.
+
+In C, the usual convention is to give header files names that end with
+@file{.h}.  It is most portable to use only letters, digits, dashes, and
+underscores in header file names, and at most one dot.
+
+@menu
+* Include Syntax::
+* Include Operation::
+* Search Path::
+* Once-Only Headers::
+* Alternatives to Wrapper #ifndef::
+* Computed Includes::
+* Wrapper Headers::
+* System Headers::
+@end menu
+
+@node Include Syntax
+@section Include Syntax
+
+@findex #include
+Both user and system header files are included using the preprocessing
+directive @samp{#include}.  It has two variants:
+
+@table @code
+@item #include <@var{file}>
+This variant is used for system header files.  It searches for a file
+named @var{file} in a standard list of system directories.  You can prepend
+directories to this list with the @option{-I} option (@pxref{Invocation}).
+
+@item #include "@var{file}"
+This variant is used for header files of your own program.  It
+searches for a file named @var{file} first in the directory containing
+the current file, then in the quote directories and then the same
+directories used for @code{<@var{file}>}.  You can prepend directories
+to the list of quote directories with the @option{-iquote} option.
+@end table
+
+The argument of @samp{#include}, 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{@w{#include
+<x/*y>}} specifies inclusion of a system header file named @file{x/*y}.
+
+However, if backslashes occur within @var{file}, 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{@w{#include "x\n\\y"}} specifies a filename containing three
+backslashes.  (Some systems interpret @samp{\} as a pathname separator.
+All of these also interpret @samp{/} the same way.  It is most portable
+to use only @samp{/}.)
+
+It is an error if there is anything (other than comments) on the line
+after the file name.
+
+@node Include Operation
+@section Include Operation
+
+The @samp{#include} 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} directive.  For example, if you have a header file
+@file{header.h} as follows,
+
+@smallexample
+char *test (void);
+@end smallexample
+
+@noindent
+and a main program called @file{program.c} that uses the header file,
+like this,
+
+@smallexample
+int x;
+#include "header.h"
+
+int
+main (void)
+@{
+  puts (test ());
+@}
+@end smallexample
+
+@noindent
+the compiler will see the same token stream as it would if
+@file{program.c} read
+
+@smallexample
+int x;
+char *test (void);
+
+int
+main (void)
+@{
+  puts (test ());
+@}
+@end smallexample
+
+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.
+
+To avoid confusion, it is best if header files contain only complete
+syntactic units---function declarations or definitions, type
+declarations, etc.
+
+The line following the @samp{#include} directive is always treated as a
+separate line by the C preprocessor, even if the included file lacks a
+final newline.
+
+@node Search Path
+@section Search Path
+
+By default, the preprocessor looks for header files included by the quote
+form of the directive @code{@w{#include "@var{file}"}} first relative to
+the directory of the current file, and then in a preconfigured list 
+of standard system directories.  
+For example, if @file{/usr/include/sys/stat.h} contains
+@code{@w{#include "types.h"}}, GCC looks for @file{types.h} first in
+@file{/usr/include/sys}, then in its usual search path.
+
+For the angle-bracket form @code{@w{#include <@var{file}>}}, 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 @option{-v} option.  For example,
+
+@smallexample
+cpp -v /dev/null -o /dev/null
+@end smallexample
+
+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 @option{-I@var{dir}}, which causes 
+@var{dir} 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 @option{-I} options on the command line, 
+in which case the directories are searched in left-to-right order.
+
+If you need separate control over the search paths for the quote and 
+angle-bracket forms of the @samp{#include} directive, you can use the
+@option{-iquote} and/or @option{-isystem} options instead of @option{-I}.
+@xref{Invocation}, for a detailed description of these options, as 
+well as others that are less generally useful.
+
+If you specify other options on the command line, such as @option{-I},
+that affect where the preprocessor searches for header files, the
+directory list printed by the @option{-v} option reflects the actual
+search path used by the preprocessor.
+
+Note that you can also prevent the preprocessor from searching any of
+the default system header directories with the @option{-nostdinc}
+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.
+
+@node Once-Only Headers
+@section Once-Only Headers
+@cindex repeated inclusion
+@cindex including just once
+@cindex wrapper @code{#ifndef}
+
+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.
+
+The standard way to prevent this is to enclose the entire real contents
+of the file in a conditional, like this:
+
+@smallexample
+@group
+/* File foo.  */
+#ifndef FILE_FOO_SEEN
+#define FILE_FOO_SEEN
+
+@var{the entire file}
+
+#endif /* !FILE_FOO_SEEN */
+@end group
+@end smallexample
+
+This construct is commonly known as a @dfn{wrapper #ifndef}.
+When the header is included again, the conditional will be false,
+because @code{FILE_FOO_SEEN} is defined.  The preprocessor will skip
+over the entire contents of the file, and the compiler will not see it
+twice.
+
+CPP optimizes even further.  It remembers when a header file has a
+wrapper @samp{#ifndef}.  If a subsequent @samp{#include} specifies that
+header, and the macro in the @samp{#ifndef} is still defined, it does
+not bother to rescan the file at all.
+
+You can put comments outside the wrapper.  They will not interfere with
+this optimization.
+
+@cindex controlling macro
+@cindex guard macro
+The macro @code{FILE_FOO_SEEN} is called the @dfn{controlling macro} or
+@dfn{guard macro}.  In a user header file, the macro name should not
+begin with @samp{_}.  In a system header file, it should begin with
+@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.
+
+@node Alternatives to Wrapper #ifndef
+@section Alternatives to Wrapper #ifndef
+
+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}
+and we recommend you do not use them in new programs, with the caveat
+that @samp{#import} is standard practice in Objective-C.
+
+@findex #import
+CPP supports a variant of @samp{#include} called @samp{#import} which
+includes a file, but does so at most once.  If you use @samp{#import}
+instead of @samp{#include}, then you don't need the conditionals
+inside the header file to prevent multiple inclusion of the contents.
+@samp{#import} is standard in Objective-C, but is considered a
+deprecated extension in C and C++.
+
+@samp{#import} 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} accomplishes
+this goal.
+
+In the present implementation, a single use of @samp{#import} will
+prevent the file from ever being read again, by either @samp{#import} or
+@samp{#include}.  You should not rely on this; do not use both
+@samp{#import} and @samp{#include} to refer to the same header file.
+
+Another way to prevent a header file from being included more than once
+is with the @samp{#pragma once} directive (@pxref{Pragmas}).  
+@samp{#pragma once} does not have the problems that @samp{#import} does,
+but it is not recognized by all preprocessors, so you cannot rely on it
+in a portable program.
+
+@node Computed Includes
+@section Computed Includes
+@cindex computed includes
+@cindex macros in include
+
+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,
+
+@smallexample
+#if SYSTEM_1
+# include "system_1.h"
+#elif SYSTEM_2
+# include "system_2.h"
+#elif SYSTEM_3
+@dots{}
+#endif
+@end smallexample
+
+That rapidly becomes tedious.  Instead, the preprocessor offers the
+ability to use a macro for the header name.  This is called a
+@dfn{computed include}.  Instead of writing a header name as the direct
+argument of @samp{#include}, you simply put a macro name there instead:
+
+@smallexample
+#define SYSTEM_H "system_1.h"
+@dots{}
+#include SYSTEM_H
+@end smallexample
+
+@noindent
+@code{SYSTEM_H} will be expanded, and the preprocessor will look for
+@file{system_1.h} as if the @samp{#include} had been written that way
+originally.  @code{SYSTEM_H} could be defined by your Makefile with a
+@option{-D} option.
+
+You must be careful when you define the macro.  @samp{#define} saves
+tokens, not text.  The preprocessor has no way of knowing that the macro
+will be used as the argument of @samp{#include}, 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.
+
+The syntax of a computed include is actually a bit more general than the
+above.  If the first non-whitespace character after @samp{#include} is
+not @samp{"} or @samp{<}, then the entire line is macro-expanded
+like running text would be.
+
+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
+
+@smallexample
+#define HEADER "a\"b"
+#include HEADER
+@end smallexample
+
+@noindent
+looks for a file named @file{a\"b}.  CPP searches for the file according
+to the rules for double-quoted includes.
+
+If the line expands to a token stream beginning with a @samp{<} token
+and including a @samp{>} token, then the tokens between the @samp{<} and
+the first @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{<} is retained, but a trailing space
+before the closing @samp{>} is ignored.  CPP searches for the file
+according to the rules for angle-bracket includes.
+
+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.
+
+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.
+
+@node Wrapper Headers
+@section Wrapper Headers
+@cindex wrapper headers
+@cindex overriding a header file
+@findex #include_next
+
+Sometimes it is necessary to adjust the contents of a system-provided
+header file without editing it directly.  GCC's @command{fixincludes}
+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?
+
+You cannot simply include the old header with @samp{#include}.  That
+will start from the beginning, and find your new header again.  If your
+header is not protected from multiple inclusion (@pxref{Once-Only
+Headers}), it will recurse infinitely and cause a fatal error.
+
+You could include the old header with an absolute pathname:
+@smallexample
+#include "/usr/include/old-header.h"
+@end smallexample
+@noindent
+This works, but is not clean; should the system headers ever move, you
+would have to edit the new headers to match.
+
+There is no way to solve this problem within the C standard, but you can
+use the GNU extension @samp{#include_next}.  It means, ``Include the
+@emph{next} file with this name''.  This directive works like
+@samp{#include} except in searching for the specified file: it starts
+searching the list of header file directories @emph{after} the directory
+in which the current file was found.
+
+Suppose you specify @option{-I /usr/local/include}, and the list of
+directories to search also includes @file{/usr/include}; and suppose
+both directories contain @file{signal.h}.  Ordinary @code{@w{#include
+<signal.h>}} finds the file under @file{/usr/local/include}.  If that
+file contains @code{@w{#include_next <signal.h>}}, it starts searching
+after that directory, and finds the file in @file{/usr/include}.
+
+@samp{#include_next} does not distinguish between @code{<@var{file}>}
+and @code{"@var{file}"} 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.
+
+The use of @samp{#include_next} 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 @command{fixincludes}.
+
+@node System Headers
+@section System Headers
+@cindex system header files
+
+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 @dfn{system headers} special
+treatment.  All warnings, other than those generated by @samp{#warning}
+(@pxref{Diagnostics}), 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.
+
+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:
+
+@itemize @bullet
+@item
+Header files found in directories added to the search path with the 
+@option{-isystem} and @option{-idirafter} command-line options are 
+treated as system headers for the purposes of diagnostics.
+
+@item
+@findex #pragma GCC system_header
+There is also a directive, @code{@w{#pragma GCC system_header}}, 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} in the file is not affected.  @code{@w{#pragma GCC
+system_header}} has no effect in the primary source file.
+@end itemize
+
+On some targets, such as RS/6000 AIX, GCC implicitly surrounds all
+system headers with an @samp{extern "C"} block when compiling as C++.
+
+@node Macros
+@chapter Macros
+
+A @dfn{macro} 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.  @dfn{Object-like} macros resemble data objects
+when used, @dfn{function-like} macros resemble function calls.
+
+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} from an
+older compiler that does not understand it.  However, the preprocessor
+operator @code{defined} (@pxref{Defined}) can never be defined as a
+macro, and C++'s named operators (@pxref{C++ Named Operators}) cannot be
+macros when you are compiling C++.
+
+@menu
+* Object-like Macros::
+* Function-like Macros::
+* Macro Arguments::
+* Stringizing::
+* Concatenation::
+* Variadic Macros::
+* Predefined Macros::
+* Undefining and Redefining Macros::
+* Directives Within Macro Arguments::
+* Macro Pitfalls::
+@end menu
+
+@node Object-like Macros
+@section Object-like Macros
+@cindex object-like macro
+@cindex symbolic constants
+@cindex manifest constants
+
+An @dfn{object-like macro} 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.
+
+@findex #define
+You create macros with the @samp{#define} directive.  @samp{#define} 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
+@dfn{body}, @dfn{expansion} or @dfn{replacement list}.  For example,
+
+@smallexample
+#define BUFFER_SIZE 1024
+@end smallexample
+
+@noindent
+defines a macro named @code{BUFFER_SIZE} as an abbreviation for the
+token @code{1024}.  If somewhere after this @samp{#define} directive
+there comes a C statement of the form
+
+@smallexample
+foo = (char *) malloc (BUFFER_SIZE);
+@end smallexample
+
+@noindent
+then the C preprocessor will recognize and @dfn{expand} the macro
+@code{BUFFER_SIZE}.  The C compiler will see the same tokens as it would
+if you had written
+
+@smallexample
+foo = (char *) malloc (1024);
+@end smallexample
+
+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.
+
+The macro's body ends at the end of the @samp{#define} 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,
+
+@smallexample
+#define NUMBERS 1, \
+                2, \
+                3
+int x[] = @{ NUMBERS @};
+     @expansion{} int x[] = @{ 1, 2, 3 @};
+@end smallexample
+
+@noindent
+The most common visible consequence of this is surprising line numbers
+in error messages.
+
+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.)
+
+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
+
+@smallexample
+foo = X;
+#define X 4
+bar = X;
+@end smallexample
+
+@noindent
+produces
+
+@smallexample
+foo = X;
+bar = 4;
+@end smallexample
+
+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,
+
+@smallexample
+@group
+#define TABLESIZE BUFSIZE
+#define BUFSIZE 1024
+TABLESIZE
+     @expansion{} BUFSIZE
+     @expansion{} 1024
+@end group
+@end smallexample
+
+@noindent
+@code{TABLESIZE} is expanded first to produce @code{BUFSIZE}, then that
+macro is expanded to produce the final result, @code{1024}.
+
+Notice that @code{BUFSIZE} was not defined when @code{TABLESIZE} was
+defined.  The @samp{#define} for @code{TABLESIZE} uses exactly the
+expansion you specify---in this case, @code{BUFSIZE}---and does not
+check to see whether it too contains macro names.  Only when you
+@emph{use} @code{TABLESIZE} is the result of its expansion scanned for
+more macro names.
+
+This makes a difference if you change the definition of @code{BUFSIZE}
+at some point in the source file.  @code{TABLESIZE}, defined as shown,
+will always expand using the definition of @code{BUFSIZE} that is
+currently in effect:
+
+@smallexample
+#define BUFSIZE 1020
+#define TABLESIZE BUFSIZE
+#undef BUFSIZE
+#define BUFSIZE 37
+@end smallexample
+
+@noindent
+Now @code{TABLESIZE} expands (in two stages) to @code{37}.
+
+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.
+@xref{Self-Referential Macros}, for the precise details.
+
+@node Function-like Macros
+@section Function-like Macros
+@cindex function-like macros
+
+You can also define macros whose use looks like a function call.  These
+are called @dfn{function-like macros}.  To define a function-like macro,
+you use the same @samp{#define} directive, but you put a pair of
+parentheses immediately after the macro name.  For example,
+
+@smallexample
+#define lang_init()  c_init()
+lang_init()
+     @expansion{} c_init()
+@end smallexample
+
+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.
+
+@smallexample
+extern void foo(void);
+#define foo() /* @r{optimized inline version} */
+@dots{}
+  foo();
+  funcptr = foo;
+@end smallexample
+
+Here the call to @code{foo()} 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.
+
+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.
+
+@smallexample
+#define lang_init ()    c_init()
+lang_init()
+     @expansion{} () c_init()()
+@end smallexample
+
+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} is an object-like macro, it does not
+consume those parentheses.
+
+@node Macro Arguments
+@section Macro Arguments
+@cindex arguments
+@cindex macros with arguments
+@cindex arguments in macro definitions
+
+Function-like macros can take @dfn{arguments}, just like true functions.
+To define a macro that uses arguments, you insert @dfn{parameters}
+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.
+
+To invoke a macro that takes arguments, you write the name of the macro
+followed by a list of @dfn{actual arguments} 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.)
+
+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.
+
+@smallexample
+#define min(X, Y)  ((X) < (Y) ? (X) : (Y))
+  x = min(a, b);          @expansion{}  x = ((a) < (b) ? (a) : (b));
+  y = min(1, 2);          @expansion{}  y = ((1) < (2) ? (1) : (2));
+  z = min(a + 28, *p);    @expansion{}  z = ((a + 28) < (*p) ? (a + 28) : (*p));
+@end smallexample
+
+@noindent
+(In this small example you can already see several of the dangers of
+macro arguments.  @xref{Macro Pitfalls}, for detailed explanations.)
+
+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,
+
+@smallexample
+macro (array[x = y, x + 1])
+@end smallexample
+
+@noindent
+passes two arguments to @code{macro}: @code{array[x = y} and @code{x +
+1]}.  If you want to supply @code{array[x = y, x + 1]} as an argument,
+you can write it as @code{array[(x = y, x + 1)]}, which is equivalent C
+code.
+
+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.  @xref{Argument
+Prescan}, for detailed discussion.
+
+For example, @code{min (min (a, b), c)} is first expanded to
+
+@smallexample
+  min (((a) < (b) ? (a) : (b)), (c))
+@end smallexample
+
+@noindent
+and then to
+
+@smallexample
+@group
+((((a) < (b) ? (a) : (b))) < (c)
+ ? (((a) < (b) ? (a) : (b)))
+ : (c))
+@end group
+@end smallexample
+
+@noindent
+(Line breaks shown here for clarity would not actually be generated.)
+
+@cindex empty macro arguments
+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}:
+
+@smallexample
+min(, b)        @expansion{} ((   ) < (b) ? (   ) : (b))
+min(a, )        @expansion{} ((a  ) < ( ) ? (a  ) : ( ))
+min(,)          @expansion{} ((   ) < ( ) ? (   ) : ( ))
+min((,),)       @expansion{} (((,)) < ( ) ? ((,)) : ( ))
+
+min()      @error{} macro "min" requires 2 arguments, but only 1 given
+min(,,)    @error{} macro "min" passed 3 arguments, but takes just 2
+@end smallexample
+
+Whitespace is not a preprocessing token, so if a macro @code{foo} takes
+one argument, @code{@w{foo ()}} and @code{@w{foo ( )}} 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.
+
+Macro parameters appearing inside string literals are not replaced by
+their corresponding actual arguments.
+
+@smallexample
+#define foo(x) x, "x"
+foo(bar)        @expansion{} bar, "x"
+@end smallexample
+
+@node Stringizing
+@section Stringizing
+@cindex stringizing
+@cindex @samp{#} operator
+
+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{#} preprocessing operator instead.  When a macro
+parameter is used with a leading @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 @dfn{stringizing}.
+
+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.
+
+Here is an example of a macro definition that uses stringizing:
+
+@smallexample
+@group
+#define WARN_IF(EXP) \
+do @{ if (EXP) \
+        fprintf (stderr, "Warning: " #EXP "\n"); @} \
+while (0)
+WARN_IF (x == 0);
+     @expansion{} do @{ if (x == 0)
+           fprintf (stderr, "Warning: " "x == 0" "\n"); @} while (0);
+@end group
+@end smallexample
+
+@noindent
+The argument for @code{EXP} is substituted once, as-is, into the
+@code{if} statement, and once, stringized, into the argument to
+@code{fprintf}.  If @code{x} were a macro, it would be expanded in the
+@code{if} statement, but not in the string.
+
+The @code{do} and @code{while (0)} are a kludge to make it possible to
+write @code{WARN_IF (@var{arg});}, which the resemblance of
+@code{WARN_IF} to a function would make C programmers want to do; see
+@ref{Swallowing the Semicolon}.
+
+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{@w{p = "foo\n";}} results in
+@t{@w{"p = \"foo\\n\";"}}.  However, backslashes that are not inside string
+or character constants are not duplicated: @samp{\n} by itself
+stringizes to @t{"\n"}.
+
+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.
+
+There is no way to convert a macro argument into a character constant.
+
+If you want to stringize the result of expansion of a macro argument,
+you have to use two levels of macros.
+
+@smallexample
+#define xstr(s) str(s)
+#define str(s) #s
+#define foo 4
+str (foo)
+     @expansion{} "foo"
+xstr (foo)
+     @expansion{} xstr (4)
+     @expansion{} str (4)
+     @expansion{} "4"
+@end smallexample
+
+@code{s} is stringized when it is used in @code{str}, so it is not
+macro-expanded first.  But @code{s} is an ordinary argument to
+@code{xstr}, so it is completely macro-expanded before @code{xstr}
+itself is expanded (@pxref{Argument Prescan}).  Therefore, by the time
+@code{str} gets to its argument, it has already been macro-expanded.
+
+@node Concatenation
+@section Concatenation
+@cindex concatenation
+@cindex token pasting
+@cindex token concatenation
+@cindex @samp{##} operator
+
+It is often useful to merge two tokens into one while expanding macros.
+This is called @dfn{token pasting} or @dfn{token concatenation}.  The
+@samp{##} preprocessing operator performs token pasting.  When a macro
+is expanded, the two tokens on either side of each @samp{##} operator
+are combined into a single token, which then replaces the @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} and @code{e3}) into a number.
+Also, multi-character operators such as @code{+=} can be formed by
+token pasting.
+
+However, two tokens that don't together form a valid token cannot be
+pasted together.  For example, you cannot concatenate @code{x} with
+@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{##}
+in complex macros.  If you get this warning, it is likely that you can
+simply remove the @samp{##}.
+
+Both the tokens combined by @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{##} is a
+parameter name, it is replaced by its actual argument before @samp{##}
+executes.  As with stringizing, the actual argument is not
+macro-expanded first.  If the argument is empty, that @samp{##} has no
+effect.
+
+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{/} and @samp{*}.  You can put as much
+whitespace between @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{##} appears at either
+end of a macro body.
+
+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:
+
+@smallexample
+@group
+struct command
+@{
+  char *name;
+  void (*function) (void);
+@};
+@end group
+
+@group
+struct command commands[] =
+@{
+  @{ "quit", quit_command @},
+  @{ "help", help_command @},
+  @dots{}
+@};
+@end group
+@end smallexample
+
+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}.  Here is how it is done:
+
+@smallexample
+#define COMMAND(NAME)  @{ #NAME, NAME ## _command @}
+
+struct command commands[] =
+@{
+  COMMAND (quit),
+  COMMAND (help),
+  @dots{}
+@};
+@end smallexample
+
+@node Variadic Macros
+@section Variadic Macros
+@cindex variable number of arguments
+@cindex macros with variable arguments
+@cindex variadic macros
+
+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:
+
+@smallexample
+#define eprintf(...) fprintf (stderr, __VA_ARGS__)
+@end smallexample
+
+This kind of macro is called @dfn{variadic}.  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 @dfn{variable
+argument}.  This sequence of tokens replaces the identifier
+@code{@w{__VA_ARGS__}} in the macro body wherever it appears.  Thus, we
+have this expansion:
+
+@smallexample
+eprintf ("%s:%d: ", input_file, lineno)
+     @expansion{}  fprintf (stderr, "%s:%d: ", input_file, lineno)
+@end smallexample
+
+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{#} and @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{##}.)
+
+If your macro is complicated, you may want a more descriptive name for
+the variable argument than @code{@w{__VA_ARGS__}}.  CPP permits
+this, as an extension.  You may write an argument name immediately
+before the @samp{...}; that name is used for the variable argument.
+The @code{eprintf} macro above could be written
+
+@smallexample
+#define eprintf(args...) fprintf (stderr, args)
+@end smallexample
+
+@noindent
+using this extension.  You cannot use @code{@w{__VA_ARGS__}} and this
+extension in the same macro.
+
+You can have named arguments as well as variable arguments in a variadic
+macro.  We could define @code{eprintf} like this, instead:
+
+@smallexample
+#define eprintf(format, ...) fprintf (stderr, format, __VA_ARGS__)
+@end smallexample
+
+@noindent
+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.)
+
+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.
+
+@smallexample
+eprintf("success!\n", );
+     @expansion{} fprintf(stderr, "success!\n", );
+@end smallexample
+
+This has been fixed in C++20, and GNU CPP also has a pair of
+extensions which deal with this problem.
+
+First, in GNU CPP, and in C++ beginning in C++20, you are allowed to
+leave the variable argument out entirely:
+
+@smallexample
+eprintf ("success!\n")
+     @expansion{} fprintf(stderr, "success!\n", );
+@end smallexample
+
+@noindent
+Second, C++20 introduces the @code{@w{__VA_OPT__}} function macro.
+This macro may only appear in the definition of a variadic macro.  If
+the variable argument has any tokens, then a @code{@w{__VA_OPT__}}
+invocation expands to its argument; but if the variable argument does
+not have any tokens, the @code{@w{__VA_OPT__}} expands to nothing:
+
+@smallexample
+#define eprintf(format, ...) \
+  fprintf (stderr, format __VA_OPT__(,) __VA_ARGS__)
+@end smallexample
+
+@code{@w{__VA_OPT__}} is also available in GNU C and GNU C++.
+
+Historically, GNU CPP has also had another extension to handle the
+trailing comma: the @samp{##} token paste operator has a special
+meaning when placed between a comma and a variable argument.  Despite
+the introduction of @code{@w{__VA_OPT__}}, this extension remains
+supported in GNU CPP, for backward compatibility.  If you write
+
+@smallexample
+#define eprintf(format, ...) fprintf (stderr, format, ##__VA_ARGS__)
+@end smallexample
+
+@noindent
+and the variable argument is left out when the @code{eprintf} macro is
+used, then the comma before the @samp{##} will be deleted.  This does
+@emph{not} happen if you pass an empty argument, nor does it happen if
+the token preceding @samp{##} is anything other than a comma.
+
+@smallexample
+eprintf ("success!\n")
+     @expansion{} fprintf(stderr, "success!\n");
+@end smallexample
+
+@noindent
+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.
+
+The C standard 
+mandates that the only place the identifier @code{@w{__VA_ARGS__}}
+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.
+
+Likewise, C++ forbids @code{@w{__VA_OPT__}} anywhere outside the
+replacement list of a variadic macro.
+
+Variadic macros became a standard part of the C language with C99.  
+GNU CPP previously supported them
+with a named variable argument
+(@samp{args...}, not @samp{...} and @code{@w{__VA_ARGS__}}), which
+is still supported for backward compatibility.
+
+@node Predefined Macros
+@section Predefined Macros
+
+@cindex predefined macros
+Several object-like macros are predefined; you use them without
+supplying their definitions.  They fall into three classes: standard,
+common, and system-specific.
+
+In C++, there is a fourth category, the named operators.  They act like
+predefined macros, but you cannot undefine them.
+
+@menu
+* Standard Predefined Macros::
+* Common Predefined Macros::
+* System-specific Predefined Macros::
+* C++ Named Operators::
+@end menu
+
+@node Standard Predefined Macros
+@subsection Standard Predefined Macros
+@cindex standard predefined macros.
+
+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.
+
+@table @code
+@item __FILE__
+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} or as the
+input file name argument.  For example,
+@code{"/usr/local/include/myheader.h"} is a possible expansion of this
+macro.
+
+@item __LINE__
+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.
+@end table
+
+@code{__FILE__} and @code{__LINE__} 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,
+
+@smallexample
+fprintf (stderr, "Internal error: "
+                 "negative string length "
+                 "%d at %s, line %d.",
+         length, __FILE__, __LINE__);
+@end smallexample
+
+An @samp{#include} directive changes the expansions of @code{__FILE__}
+and @code{__LINE__} to correspond to the included file.  At the end of
+that file, when processing resumes on the input file that contained
+the @samp{#include} directive, the expansions of @code{__FILE__} and
+@code{__LINE__} revert to the values they had before the
+@samp{#include} (but @code{__LINE__} is then incremented by one as
+processing moves to the line after the @samp{#include}).
+
+A @samp{#line} directive changes @code{__LINE__}, and may change
+@code{__FILE__} as well.  @xref{Line Control}.
+
+C99 introduced @code{__func__}, and GCC has provided @code{__FUNCTION__}
+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__} and @code{__LINE__}, though.
+
+@table @code
+
+@item __DATE__
+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{@w{"Feb 12 1996"}}.  If the day of the
+month is less than 10, it is padded with a space on the left.
+
+If GCC cannot determine the current date, it will emit a warning message
+(once per compilation) and @code{__DATE__} will expand to
+@code{@w{"??? ?? ????"}}.
+
+@item __TIME__
+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"}.
+
+If GCC cannot determine the current time, it will emit a warning message
+(once per compilation) and @code{__TIME__} will expand to
+@code{"??:??:??"}.
+
+@item __STDC__
+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
+@option{-traditional-cpp} option is used.
+
+This macro is not defined if the @option{-traditional-cpp} option is used.
+
+On some hosts, the system compiler uses a different convention, where
+@code{__STDC__} 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__} is always 1.  This has been reported to cause problems;
+for instance, some versions of Solaris provide X Windows headers that
+expect @code{__STDC__} to be either undefined or 1.  @xref{Invocation}.
+
+@item __STDC_VERSION__
+This macro expands to the C Standard's version number, a long integer
+constant of the form @code{@var{yyyy}@var{mm}L} where @var{yyyy} and
+@var{mm} are the year and month of the Standard version.  This signifies
+which version of the C Standard the compiler conforms to.  Like
+@code{__STDC__}, this is not necessarily accurate for the entire
+implementation, unless GNU CPP is being used with GCC@.
+
+The value @code{199409L} signifies the 1989 C standard as amended in
+1994, which is the current default; the value @code{199901L} signifies
+the 1999 revision of the C standard; the value @code{201112L}
+signifies the 2011 revision of the C standard; the value
+@code{201710L} 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} is used for
+the experimental @option{-std=c2x} and @option{-std=gnu2x} modes.
+
+This macro is not defined if the @option{-traditional-cpp} option is
+used, nor when compiling C++ or Objective-C@.
+
+@item __STDC_HOSTED__
+This macro is defined, with value 1, if the compiler's target is a
+@dfn{hosted environment}.  A hosted environment has the complete
+facilities of the standard C library available.
+
+@item __cplusplus
+This macro is defined when the C++ compiler is in use.  You can use
+@code{__cplusplus} to test whether a header is compiled by a C compiler
+or a C++ compiler.  This macro is similar to @code{__STDC_VERSION__}, in
+that it expands to a version number.  Depending on the language standard
+selected, the value of the macro is
+@code{199711L} for the 1998 C++ standard,
+@code{201103L} for the 2011 C++ standard,
+@code{201402L} for the 2014 C++ standard,
+@code{201703L} for the 2017 C++ standard,
+@code{202002L} for the 2020 C++ standard,
+or an unspecified value strictly larger than @code{202002L} for the
+experimental languages enabled by @option{-std=c++23} and
+@option{-std=gnu++23}.
+
+@item __OBJC__
+This macro is defined, with value 1, when the Objective-C compiler is in
+use.  You can use @code{__OBJC__} to test whether a header is compiled
+by a C compiler or an Objective-C compiler.
+
+@item __ASSEMBLER__
+This macro is defined with value 1 when preprocessing assembly
+language.
+
+@end table
+
+@node Common Predefined Macros
+@subsection Common Predefined Macros
+@cindex common predefined macros
+
+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.
+
+@table @code
+
+@item __COUNTER__
+This macro expands to sequential integral values starting from 0.  In
+conjunction with the @code{##} operator, this provides a convenient means to
+generate unique identifiers.  Care must be taken to ensure that
+@code{__COUNTER__} is not expanded prior to inclusion of precompiled headers
+which use it.  Otherwise, the precompiled headers will not be used.
+
+@item __GFORTRAN__
+The GNU Fortran compiler defines this.
+
+@item __GNUC__
+@itemx __GNUC_MINOR__
+@itemx __GNUC_PATCHLEVEL__
+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{y}.@var{z}
+defines @code{__GNUC__} to @var{x}, @code{__GNUC_MINOR__} to @var{y},
+and @code{__GNUC_PATCHLEVEL__} to @var{z}.  These
+macros are also defined if you invoke the preprocessor directly.
+
+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__}.  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:
+
+@smallexample
+/* @r{Test for GCC > 3.2.0} */
+#if __GNUC__ > 3 || \
+    (__GNUC__ == 3 && (__GNUC_MINOR__ > 2 || \
+                       (__GNUC_MINOR__ == 2 && \
+                        __GNUC_PATCHLEVEL__ > 0))
+@end smallexample
+
+@noindent
+Another approach is to use the predefined macros to
+calculate a single number, then compare that against a threshold:
+
+@smallexample
+#define GCC_VERSION (__GNUC__ * 10000 \
+                     + __GNUC_MINOR__ * 100 \
+                     + __GNUC_PATCHLEVEL__)
+@dots{}
+/* @r{Test for GCC > 3.2.0} */
+#if GCC_VERSION > 30200
+@end smallexample
+
+@noindent
+Many people find this form easier to understand.
+
+@item __GNUG__
+The GNU C++ compiler defines this.  Testing it is equivalent to
+testing @code{@w{(__GNUC__ && __cplusplus)}}.
+
+@item __STRICT_ANSI__
+GCC defines this macro if and only if the @option{-ansi} switch, or a
+@option{-std} 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}.
+This macro exists primarily to direct GNU libc's header files to use only
+definitions found in standard C.
+
+@item __BASE_FILE__
+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.
+
+@item __FILE_NAME__
+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"} would set this
+macro to @code{"myheader.h"}.
+
+@item __INCLUDE_LEVEL__
+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} 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.
+
+@item __ELF__
+This macro is defined if the target uses the ELF object format.
+
+@item __VERSION__
+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.
+
+@item __OPTIMIZE__
+@itemx __OPTIMIZE_SIZE__
+@itemx __NO_INLINE__
+These macros describe the compilation mode.  @code{__OPTIMIZE__} is
+defined in all optimizing compilations.  @code{__OPTIMIZE_SIZE__} is
+defined if the compiler is optimizing for size, not speed.
+@code{__NO_INLINE__} is defined if no functions will be inlined into
+their callers (when not optimizing, or when inlining has been
+specifically disabled by @option{-fno-inline}).
+
+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.
+
+@item __GNUC_GNU_INLINE__
+GCC defines this macro if functions declared @code{inline} will be
+handled in GCC's traditional gnu90 mode.  Object files will contain
+externally visible definitions of all functions declared @code{inline}
+without @code{extern} or @code{static}.  They will not contain any
+definitions of any functions declared @code{extern inline}.
+
+@item __GNUC_STDC_INLINE__
+GCC defines this macro if functions declared @code{inline} 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}.  They will not contain definitions of any functions declared
+@code{inline} without @code{extern}.
+
+If this macro is defined, GCC supports the @code{gnu_inline} function
+attribute as a way to always get the gnu90 behavior.
+
+@item __CHAR_UNSIGNED__
+GCC defines this macro if and only if the data type @code{char} is
+unsigned on the target machine.  It exists to cause the standard header
+file @file{limits.h} to work correctly.  You should not use this macro
+yourself; instead, refer to the standard macros defined in @file{limits.h}.
+
+@item __WCHAR_UNSIGNED__
+Like @code{__CHAR_UNSIGNED__}, this macro is defined if and only if the
+data type @code{wchar_t} is unsigned and the front-end is in C++ mode.
+
+@item __REGISTER_PREFIX__
+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} environment it
+expands to nothing, but in the @code{m68k-coff} environment it expands
+to a single @samp{%}.
+
+@item __USER_LABEL_PREFIX__
+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} environment it expands to an @samp{_}, but in the
+@code{m68k-coff} environment it expands to nothing.
+
+This macro will have the correct definition even if
+@option{-f(no-)underscores} is in use, but it will not be correct if
+target-specific options that adjust this prefix are used (e.g.@: the
+OSF/rose @option{-mno-underscores} option).
+
+@item __SIZE_TYPE__
+@itemx __PTRDIFF_TYPE__
+@itemx __WCHAR_TYPE__
+@itemx __WINT_TYPE__
+@itemx __INTMAX_TYPE__
+@itemx __UINTMAX_TYPE__
+@itemx __SIG_ATOMIC_TYPE__
+@itemx __INT8_TYPE__
+@itemx __INT16_TYPE__
+@itemx __INT32_TYPE__
+@itemx __INT64_TYPE__
+@itemx __UINT8_TYPE__
+@itemx __UINT16_TYPE__
+@itemx __UINT32_TYPE__
+@itemx __UINT64_TYPE__
+@itemx __INT_LEAST8_TYPE__
+@itemx __INT_LEAST16_TYPE__
+@itemx __INT_LEAST32_TYPE__
+@itemx __INT_LEAST64_TYPE__
+@itemx __UINT_LEAST8_TYPE__
+@itemx __UINT_LEAST16_TYPE__
+@itemx __UINT_LEAST32_TYPE__
+@itemx __UINT_LEAST64_TYPE__
+@itemx __INT_FAST8_TYPE__
+@itemx __INT_FAST16_TYPE__
+@itemx __INT_FAST32_TYPE__
+@itemx __INT_FAST64_TYPE__
+@itemx __UINT_FAST8_TYPE__
+@itemx __UINT_FAST16_TYPE__
+@itemx __UINT_FAST32_TYPE__
+@itemx __UINT_FAST64_TYPE__
+@itemx __INTPTR_TYPE__
+@itemx __UINTPTR_TYPE__
+These macros are defined to the correct underlying types for the
+@code{size_t}, @code{ptrdiff_t}, @code{wchar_t}, @code{wint_t},
+@code{intmax_t}, @code{uintmax_t}, @code{sig_atomic_t}, @code{int8_t},
+@code{int16_t}, @code{int32_t}, @code{int64_t}, @code{uint8_t},
+@code{uint16_t}, @code{uint32_t}, @code{uint64_t},
+@code{int_least8_t}, @code{int_least16_t}, @code{int_least32_t},
+@code{int_least64_t}, @code{uint_least8_t}, @code{uint_least16_t},
+@code{uint_least32_t}, @code{uint_least64_t}, @code{int_fast8_t},
+@code{int_fast16_t}, @code{int_fast32_t}, @code{int_fast64_t},
+@code{uint_fast8_t}, @code{uint_fast16_t}, @code{uint_fast32_t},
+@code{uint_fast64_t}, @code{intptr_t}, and @code{uintptr_t} typedefs,
+respectively.  They exist to make the standard header files
+@file{stddef.h}, @file{stdint.h}, and @file{wchar.h} 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
+@file{stdint.h} header on those systems.
+
+@item __CHAR_BIT__
+Defined to the number of bits used in the representation of the
+@code{char} 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.
+
+@item __SCHAR_MAX__
+@itemx __WCHAR_MAX__
+@itemx __SHRT_MAX__
+@itemx __INT_MAX__
+@itemx __LONG_MAX__
+@itemx __LONG_LONG_MAX__
+@itemx __WINT_MAX__
+@itemx __SIZE_MAX__
+@itemx __PTRDIFF_MAX__
+@itemx __INTMAX_MAX__
+@itemx __UINTMAX_MAX__
+@itemx __SIG_ATOMIC_MAX__
+@itemx __INT8_MAX__
+@itemx __INT16_MAX__
+@itemx __INT32_MAX__
+@itemx __INT64_MAX__
+@itemx __UINT8_MAX__
+@itemx __UINT16_MAX__
+@itemx __UINT32_MAX__
+@itemx __UINT64_MAX__
+@itemx __INT_LEAST8_MAX__
+@itemx __INT_LEAST16_MAX__
+@itemx __INT_LEAST32_MAX__
+@itemx __INT_LEAST64_MAX__
+@itemx __UINT_LEAST8_MAX__
+@itemx __UINT_LEAST16_MAX__
+@itemx __UINT_LEAST32_MAX__
+@itemx __UINT_LEAST64_MAX__
+@itemx __INT_FAST8_MAX__
+@itemx __INT_FAST16_MAX__
+@itemx __INT_FAST32_MAX__
+@itemx __INT_FAST64_MAX__
+@itemx __UINT_FAST8_MAX__
+@itemx __UINT_FAST16_MAX__
+@itemx __UINT_FAST32_MAX__
+@itemx __UINT_FAST64_MAX__
+@itemx __INTPTR_MAX__
+@itemx __UINTPTR_MAX__
+@itemx __WCHAR_MIN__
+@itemx __WINT_MIN__
+@itemx __SIG_ATOMIC_MIN__
+Defined to the maximum value of the @code{signed char}, @code{wchar_t},
+@code{signed short},
+@code{signed int}, @code{signed long}, @code{signed long long},
+@code{wint_t}, @code{size_t}, @code{ptrdiff_t},
+@code{intmax_t}, @code{uintmax_t}, @code{sig_atomic_t}, @code{int8_t},
+@code{int16_t}, @code{int32_t}, @code{int64_t}, @code{uint8_t},
+@code{uint16_t}, @code{uint32_t}, @code{uint64_t},
+@code{int_least8_t}, @code{int_least16_t}, @code{int_least32_t},
+@code{int_least64_t}, @code{uint_least8_t}, @code{uint_least16_t},
+@code{uint_least32_t}, @code{uint_least64_t}, @code{int_fast8_t},
+@code{int_fast16_t}, @code{int_fast32_t}, @code{int_fast64_t},
+@code{uint_fast8_t}, @code{uint_fast16_t}, @code{uint_fast32_t},
+@code{uint_fast64_t}, @code{intptr_t}, and @code{uintptr_t} types and
+to the minimum value of the @code{wchar_t}, @code{wint_t}, and
+@code{sig_atomic_t} 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 @file{stdint.h} header on those systems.
+
+@item __INT8_C
+@itemx __INT16_C
+@itemx __INT32_C
+@itemx __INT64_C
+@itemx __UINT8_C
+@itemx __UINT16_C
+@itemx __UINT32_C
+@itemx __UINT64_C
+@itemx __INTMAX_C
+@itemx __UINTMAX_C
+Defined to implementations of the standard @file{stdint.h} macros with
+the same names without the leading @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 @file{stdint.h} header on those systems.
+
+@item __SCHAR_WIDTH__
+@itemx __SHRT_WIDTH__
+@itemx __INT_WIDTH__
+@itemx __LONG_WIDTH__
+@itemx __LONG_LONG_WIDTH__
+@itemx __PTRDIFF_WIDTH__
+@itemx __SIG_ATOMIC_WIDTH__
+@itemx __SIZE_WIDTH__
+@itemx __WCHAR_WIDTH__
+@itemx __WINT_WIDTH__
+@itemx __INT_LEAST8_WIDTH__
+@itemx __INT_LEAST16_WIDTH__
+@itemx __INT_LEAST32_WIDTH__
+@itemx __INT_LEAST64_WIDTH__
+@itemx __INT_FAST8_WIDTH__
+@itemx __INT_FAST16_WIDTH__
+@itemx __INT_FAST32_WIDTH__
+@itemx __INT_FAST64_WIDTH__
+@itemx __INTPTR_WIDTH__
+@itemx __INTMAX_WIDTH__
+Defined to the bit widths of the corresponding types.  They exist to
+make the implementations of @file{limits.h} and @file{stdint.h} 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 @file{stdint.h} header on
+those systems.
+
+@item __SIZEOF_INT__
+@itemx __SIZEOF_LONG__
+@itemx __SIZEOF_LONG_LONG__
+@itemx __SIZEOF_SHORT__
+@itemx __SIZEOF_POINTER__
+@itemx __SIZEOF_FLOAT__
+@itemx __SIZEOF_DOUBLE__
+@itemx __SIZEOF_LONG_DOUBLE__
+@itemx __SIZEOF_SIZE_T__
+@itemx __SIZEOF_WCHAR_T__
+@itemx __SIZEOF_WINT_T__
+@itemx __SIZEOF_PTRDIFF_T__
+Defined to the number of bytes of the C standard data types: @code{int},
+@code{long}, @code{long long}, @code{short}, @code{void *}, @code{float},
+@code{double}, @code{long double}, @code{size_t}, @code{wchar_t}, @code{wint_t}
+and @code{ptrdiff_t}.
+
+@item __BYTE_ORDER__
+@itemx __ORDER_LITTLE_ENDIAN__
+@itemx __ORDER_BIG_ENDIAN__
+@itemx __ORDER_PDP_ENDIAN__
+@code{__BYTE_ORDER__} is defined to one of the values
+@code{__ORDER_LITTLE_ENDIAN__}, @code{__ORDER_BIG_ENDIAN__}, or
+@code{__ORDER_PDP_ENDIAN__} to reflect the layout of multi-byte and
+multi-word quantities in memory.  If @code{__BYTE_ORDER__} is equal to
+@code{__ORDER_LITTLE_ENDIAN__} or @code{__ORDER_BIG_ENDIAN__}, 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__} is equal to @code{__ORDER_PDP_ENDIAN__}, 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.
+
+You should use these macros for testing like this:
+
+@smallexample
+/* @r{Test for a little-endian machine} */
+#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
+@end smallexample
+
+@item __FLOAT_WORD_ORDER__
+@code{__FLOAT_WORD_ORDER__} is defined to one of the values
+@code{__ORDER_LITTLE_ENDIAN__} or @code{__ORDER_BIG_ENDIAN__} to reflect
+the layout of the words of multi-word floating-point quantities.
+
+@item __DEPRECATED
+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 @option{-Wno-deprecated}.
+
+@item __EXCEPTIONS
+This macro is defined, with value 1, when compiling a C++ source file
+with exceptions enabled.  If @option{-fno-exceptions} is used when
+compiling the file, then this macro is not defined.
+
+@item __GXX_RTTI
+This macro is defined, with value 1, when compiling a C++ source file
+with runtime type identification enabled.  If @option{-fno-rtti} is
+used when compiling the file, then this macro is not defined.
+
+@item __USING_SJLJ_EXCEPTIONS__
+This macro is defined, with value 1, if the compiler uses the old
+mechanism based on @code{setjmp} and @code{longjmp} for exception
+handling.
+
+@item __GXX_EXPERIMENTAL_CXX0X__
+This macro is defined when compiling a C++ source file with C++11 features
+enabled, i.e., for all C++ language dialects except @option{-std=c++98}
+and @option{-std=gnu++98}. 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} macro is defined correctly, so most
+code should test @code{__cplusplus >= 201103L} instead of using this
+macro.
+
+@item __GXX_WEAK__
+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++.
+
+@item __NEXT_RUNTIME__
+This macro is defined, with value 1, if (and only if) the NeXT runtime
+(as in @option{-fnext-runtime}) 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.
+
+@item __LP64__
+@itemx _LP64
+These macros are defined, with value 1, if (and only if) the compilation
+is for a target where @code{long int} and pointer both use 64-bits and
+@code{int} uses 32-bit.
+
+@item __SSP__
+This macro is defined, with value 1, when @option{-fstack-protector} is in
+use.
+
+@item __SSP_ALL__
+This macro is defined, with value 2, when @option{-fstack-protector-all} is
+in use.
+
+@item __SSP_STRONG__
+This macro is defined, with value 3, when @option{-fstack-protector-strong} is
+in use.
+
+@item __SSP_EXPLICIT__
+This macro is defined, with value 4, when @option{-fstack-protector-explicit} is
+in use.
+
+@item __SANITIZE_ADDRESS__
+This macro is defined, with value 1, when @option{-fsanitize=address}
+or @option{-fsanitize=kernel-address} are in use.
+
+@item __SANITIZE_THREAD__
+This macro is defined, with value 1, when @option{-fsanitize=thread} is in use.
+
+@item __TIMESTAMP__
+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{@w{"Sun Sep 16 01:03:52 1973"}}.
+If the day of the month is less than 10, it is padded with a space on the left.
+
+If GCC cannot determine the current date, it will emit a warning message
+(once per compilation) and @code{__TIMESTAMP__} will expand to
+@code{@w{"??? ??? ?? ??:??:?? ????"}}.
+
+@item __GCC_HAVE_SYNC_COMPARE_AND_SWAP_1
+@itemx __GCC_HAVE_SYNC_COMPARE_AND_SWAP_2
+@itemx __GCC_HAVE_SYNC_COMPARE_AND_SWAP_4
+@itemx __GCC_HAVE_SYNC_COMPARE_AND_SWAP_8
+@itemx __GCC_HAVE_SYNC_COMPARE_AND_SWAP_16
+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.
+
+@item __HAVE_SPECULATION_SAFE_VALUE
+This macro is defined with the value 1 to show that this version of GCC
+supports @code{__builtin_speculation_safe_value}.
+
+@item __GCC_HAVE_DWARF2_CFI_ASM
+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.
+
+@item __FP_FAST_FMA
+@itemx __FP_FAST_FMAF
+@itemx __FP_FAST_FMAL
+These macros are defined with value 1 if the backend supports the
+@code{fma}, @code{fmaf}, and @code{fmal} builtin functions, so that
+the include file @file{math.h} can define the macros
+@code{FP_FAST_FMA}, @code{FP_FAST_FMAF}, and @code{FP_FAST_FMAL}
+for compatibility with the 1999 C standard.
+
+@item __FP_FAST_FMAF16
+@itemx __FP_FAST_FMAF32
+@itemx __FP_FAST_FMAF64
+@itemx __FP_FAST_FMAF128
+@itemx __FP_FAST_FMAF32X
+@itemx __FP_FAST_FMAF64X
+@itemx __FP_FAST_FMAF128X
+These macros are defined with the value 1 if the backend supports the
+@code{fma} functions using the additional @code{_Float@var{n}} and
+@code{_Float@var{n}x} types that are defined in ISO/IEC TS
+18661-3:2015.  The include file @file{math.h} can define the
+@code{FP_FAST_FMAF@var{n}} and @code{FP_FAST_FMAF@var{n}x} macros if
+the user defined @code{__STDC_WANT_IEC_60559_TYPES_EXT__} before
+including @file{math.h}.
+
+@item __GCC_IEC_559
+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} and
+@code{double} 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).
+
+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__}).  It does not indicate support for decimal
+floating point or the IEEE 754 binary16 and binary128 types.
+
+@item __GCC_IEC_559_COMPLEX
+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 @option{-fcx-limited-range}
+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.
+
+@item __NO_MATH_ERRNO__
+This macro is defined if @option{-fno-math-errno} is used, or enabled
+by another option such as @option{-ffast-math} or by default.
+
+@item __RECIPROCAL_MATH__
+This macro is defined if @option{-freciprocal-math} is used, or enabled
+by another option such as @option{-ffast-math} or by default.
+
+@item __NO_SIGNED_ZEROS__
+This macro is defined if @option{-fno-signed-zeros} is used, or enabled
+by another option such as @option{-ffast-math} or by default.
+
+@item __NO_TRAPPING_MATH__
+This macro is defined if @option{-fno-trapping-math} is used.
+
+@item __ASSOCIATIVE_MATH__
+This macro is defined if @option{-fassociative-math} is used, or enabled
+by another option such as @option{-ffast-math} or by default.
+
+@item __ROUNDING_MATH__
+This macro is defined if @option{-frounding-math} is used.
+
+@item __GNUC_EXECUTION_CHARSET_NAME
+@itemx __GNUC_WIDE_EXECUTION_CHARSET_NAME
+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
+@option{-fexec-charset} and @option{-fwide-exec-charset}, or the defaults
+documented for those options (that is, it can expand to something like
+@code{"UTF-8"}).  @xref{Invocation}.
+@end table
+
+@node System-specific Predefined Macros
+@subsection System-specific Predefined Macros
+
+@cindex system-specific predefined macros
+@cindex predefined macros, system-specific
+@cindex reserved namespace
+
+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
+@command{cpp -dM} to see them all.  @xref{Invocation}.  All system-specific
+predefined macros expand to a constant value, so you can test them with
+either @samp{#ifdef} or @samp{#if}.
+
+The C standard requires that all system-specific macros be part of the
+@dfn{reserved namespace}.  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} 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} is defined, @code{__unix__} will be defined
+too.  There will never be more than two underscores; the parallel of
+@code{_mips} is @code{__mips__}.
+
+When the @option{-ansi} option, or any @option{-std} 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.
+
+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
+@command{autoconf}.
+
+@node C++ Named Operators
+@subsection C++ Named Operators
+@cindex named operators
+@cindex C++ named operators
+@cindex @file{iso646.h}
+
+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}, and they cannot be defined as macros or poisoned.  In C, you
+can request that those keywords take their C++ meaning by including
+@file{iso646.h}.  That header defines each one as a normal object-like
+macro expanding to the appropriate punctuator.
+
+These are the named operators and their corresponding punctuators:
+
+@multitable {Named Operator} {Punctuator}
+@item Named Operator @tab Punctuator
+@item @code{and}    @tab @code{&&}
+@item @code{and_eq} @tab @code{&=}
+@item @code{bitand} @tab @code{&}
+@item @code{bitor}  @tab @code{|}
+@item @code{compl}  @tab @code{~}
+@item @code{not}    @tab @code{!}
+@item @code{not_eq} @tab @code{!=}
+@item @code{or}     @tab @code{||}
+@item @code{or_eq}  @tab @code{|=}
+@item @code{xor}    @tab @code{^}
+@item @code{xor_eq} @tab @code{^=}
+@end multitable
+
+@node Undefining and Redefining Macros
+@section Undefining and Redefining Macros
+@cindex undefining macros
+@cindex redefining macros
+@findex #undef
+
+If a macro ceases to be useful, it may be @dfn{undefined} with the
+@samp{#undef} directive.  @samp{#undef} 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} has no effect if the name is not a
+macro.
+
+@smallexample
+#define FOO 4
+x = FOO;        @expansion{} x = 4;
+#undef FOO
+x = FOO;        @expansion{} x = FOO;
+@end smallexample
+
+Once a macro has been undefined, that identifier may be @dfn{redefined}
+as a macro by a subsequent @samp{#define} directive.  The new definition
+need not have any resemblance to the old definition.
+
+However, if an identifier which is currently a macro is redefined, then
+the new definition must be @dfn{effectively the same} as the old one.
+Two macro definitions are effectively the same if:
+@itemize @bullet
+@item Both are the same type of macro (object- or function-like).
+@item All the tokens of the replacement list are the same.
+@item If there are any parameters, they are the same.
+@item 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.
+@end itemize
+
+@noindent
+These definitions are effectively the same:
+@smallexample
+#define FOUR (2 + 2)
+#define FOUR         (2    +    2)
+#define FOUR (2 /* @r{two} */ + 2)
+@end smallexample
+@noindent
+but these are not:
+@smallexample
+#define FOUR (2 + 2)
+#define FOUR ( 2+2 )
+#define FOUR (2 * 2)
+#define FOUR(score,and,seven,years,ago) (2 + 2)
+@end smallexample
+
+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.
+
+@node Directives Within Macro Arguments
+@section Directives Within Macro Arguments
+@cindex macro arguments and directives
+
+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.
+
+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:
+
+@smallexample
+#define f(x) x x
+f (1
+#undef f
+#define f 2
+f)
+@end smallexample
+
+@noindent
+which expands to
+
+@smallexample
+1 2 1 2
+@end smallexample
+
+@noindent
+with the semantics described above.
+
+@node Macro Pitfalls
+@section Macro Pitfalls
+@cindex problems with macros
+@cindex pitfalls of macros
+
+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.
+
+@menu
+* Misnesting::
+* Operator Precedence Problems::
+* Swallowing the Semicolon::
+* Duplication of Side Effects::
+* Self-Referential Macros::
+* Argument Prescan::
+* Newlines in Arguments::
+@end menu
+
+@node Misnesting
+@subsection Misnesting
+
+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,
+
+@smallexample
+#define twice(x) (2*(x))
+#define call_with_1(x) x(1)
+call_with_1 (twice)
+     @expansion{} twice(1)
+     @expansion{} (2*(1))
+@end smallexample
+
+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,
+
+@smallexample
+#define strange(file) fprintf (file, "%s %d",
+@dots{}
+strange(stderr) p, 35)
+     @expansion{} fprintf (stderr, "%s %d", p, 35)
+@end smallexample
+
+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.
+
+@node Operator Precedence Problems
+@subsection Operator Precedence Problems
+@cindex parentheses in macro bodies
+
+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.
+
+Suppose you define a macro as follows,
+
+@smallexample
+#define ceil_div(x, y) (x + y - 1) / y
+@end smallexample
+
+@noindent
+whose purpose is to divide, rounding up.  (One use for this operation is
+to compute how many @code{int} objects are needed to hold a certain
+number of @code{char} objects.)  Then suppose it is used as follows:
+
+@smallexample
+a = ceil_div (b & c, sizeof (int));
+     @expansion{} a = (b & c + sizeof (int) - 1) / sizeof (int);
+@end smallexample
+
+@noindent
+This does not do what is intended.  The operator-precedence rules of
+C make it equivalent to this:
+
+@smallexample
+a = (b & (c + sizeof (int) - 1)) / sizeof (int);
+@end smallexample
+
+@noindent
+What we want is this:
+
+@smallexample
+a = ((b & c) + sizeof (int) - 1)) / sizeof (int);
+@end smallexample
+
+@noindent
+Defining the macro as
+
+@smallexample
+#define ceil_div(x, y) ((x) + (y) - 1) / (y)
+@end smallexample
+
+@noindent
+provides the desired result.
+
+Unintended grouping can result in another way.  Consider @code{sizeof
+ceil_div(1, 2)}.  That has the appearance of a C expression that would
+compute the size of the type of @code{ceil_div (1, 2)}, but in fact it
+means something very different.  Here is what it expands to:
+
+@smallexample
+sizeof ((1) + (2) - 1) / (2)
+@end smallexample
+
+@noindent
+This would take the size of an integer and divide it by two.  The
+precedence rules have put the division outside the @code{sizeof} when it
+was intended to be inside.
+
+Parentheses around the entire macro definition prevent such problems.
+Here, then, is the recommended way to define @code{ceil_div}:
+
+@smallexample
+#define ceil_div(x, y) (((x) + (y) - 1) / (y))
+@end smallexample
+
+@node Swallowing the Semicolon
+@subsection Swallowing the Semicolon
+@cindex semicolons (after macro calls)
+
+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} says where to find it) across whitespace
+characters:
+
+@smallexample
+#define SKIP_SPACES(p, limit)  \
+@{ char *lim = (limit);         \
+  while (p < lim) @{            \
+    if (*p++ != ' ') @{         \
+      p--; break; @}@}@}
+@end smallexample
+
+@noindent
+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.
+
+A call to this macro might be @code{SKIP_SPACES (p, lim)}.  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);}
+
+This can cause trouble before @code{else} statements, because the
+semicolon is actually a null statement.  Suppose you write
+
+@smallexample
+if (*p != 0)
+  SKIP_SPACES (p, lim);
+else @dots{}
+@end smallexample
+
+@noindent
+The presence of two statements---the compound statement and a null
+statement---in between the @code{if} condition and the @code{else}
+makes invalid C code.
+
+The definition of the macro @code{SKIP_SPACES} can be altered to solve
+this problem, using a @code{do @dots{} while} statement.  Here is how:
+
+@smallexample
+#define SKIP_SPACES(p, limit)     \
+do @{ char *lim = (limit);         \
+     while (p < lim) @{            \
+       if (*p++ != ' ') @{         \
+         p--; break; @}@}@}          \
+while (0)
+@end smallexample
+
+Now @code{SKIP_SPACES (p, lim);} expands into
+
+@smallexample
+do @{@dots{}@} while (0);
+@end smallexample
+
+@noindent
+which is one statement.  The loop executes exactly once; most compilers
+generate no extra code for it.
+
+@node Duplication of Side Effects
+@subsection Duplication of Side Effects
+
+@cindex side effects (in macro arguments)
+@cindex unsafe macros
+Many C programs define a macro @code{min}, for ``minimum'', like this:
+
+@smallexample
+#define min(X, Y)  ((X) < (Y) ? (X) : (Y))
+@end smallexample
+
+When you use this macro with an argument containing a side effect,
+as shown here,
+
+@smallexample
+next = min (x + y, foo (z));
+@end smallexample
+
+@noindent
+it expands as follows:
+
+@smallexample
+next = ((x + y) < (foo (z)) ? (x + y) : (foo (z)));
+@end smallexample
+
+@noindent
+where @code{x + y} has been substituted for @code{X} and @code{foo (z)}
+for @code{Y}.
+
+The function @code{foo} is used only once in the statement as it appears
+in the program, but the expression @code{foo (z)} has been substituted
+twice into the macro expansion.  As a result, @code{foo} 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} is an @dfn{unsafe} macro.
+
+The best solution to this problem is to define @code{min} in a way that
+computes the value of @code{foo (z)} only once.  The C language offers
+no standard way to do this, but it can be done with GNU extensions as
+follows:
+
+@smallexample
+#define min(X, Y)                \
+(@{ typeof (X) x_ = (X);          \
+   typeof (Y) y_ = (Y);          \
+   (x_ < y_) ? x_ : y_; @})
+@end smallexample
+
+The @samp{(@{ @dots{} @})} 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.
+
+If you do not wish to use GNU C extensions, the only solution is to be
+careful when @emph{using} the macro @code{min}.  For example, you can
+calculate the value of @code{foo (z)}, save it in a variable, and use
+that variable in @code{min}:
+
+@smallexample
+@group
+#define min(X, Y)  ((X) < (Y) ? (X) : (Y))
+@dots{}
+@{
+  int tem = foo (z);
+  next = min (x + y, tem);
+@}
+@end group
+@end smallexample
+
+@noindent
+(where we assume that @code{foo} returns type @code{int}).
+
+@node Self-Referential Macros
+@subsection Self-Referential Macros
+@cindex self-reference
+
+A @dfn{self-referential} 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:
+
+@smallexample
+#define foo (4 + foo)
+@end smallexample
+
+@noindent
+where @code{foo} is also a variable in your program.
+
+Following the ordinary rules, each reference to @code{foo} will expand
+into @code{(4 + foo)}; then this will be rescanned and will expand into
+@code{(4 + (4 + foo))}; and so on until the computer runs out of memory.
+
+The self-reference rule cuts this process short after one step, at
+@code{(4 + foo)}.  Therefore, this macro definition has the possibly
+useful effect of causing the program to add 4 to the value of @code{foo}
+wherever @code{foo} is referred to.
+
+In most cases, it is a bad idea to take advantage of this feature.  A
+person reading the program who sees that @code{foo} is a variable will
+not expect that it is a macro as well.  The reader will come across the
+identifier @code{foo} in the program and think its value should be that
+of the variable @code{foo}, whereas in fact the value is four greater.
+
+One common, useful use of self-reference is to create a macro which
+expands to itself.  If you write
+
+@smallexample
+#define EPERM EPERM
+@end smallexample
+
+@noindent
+then the macro @code{EPERM} expands to @code{EPERM}.  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}.  You might do this if you
+want to define numeric constants with an @code{enum}, but have
+@samp{#ifdef} be true for each constant.
+
+If a macro @code{x} expands to use a macro @code{y}, and the expansion of
+@code{y} refers to the macro @code{x}, that is an @dfn{indirect
+self-reference} of @code{x}.  @code{x} is not expanded in this case
+either.  Thus, if we have
+
+@smallexample
+#define x (4 + y)
+#define y (2 * x)
+@end smallexample
+
+@noindent
+then @code{x} and @code{y} expand as follows:
+
+@smallexample
+@group
+x    @expansion{} (4 + y)
+     @expansion{} (4 + (2 * x))
+
+y    @expansion{} (2 * x)
+     @expansion{} (2 * (4 + y))
+@end group
+@end smallexample
+
+@noindent
+Each macro is expanded when it appears in the definition of the other
+macro, but not when it indirectly appears in its own definition.
+
+@node Argument Prescan
+@subsection Argument Prescan
+@cindex expansion of arguments
+@cindex macro argument expansion
+@cindex prescan of macro arguments
+
+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 @emph{twice} to expand
+macro calls in them.
+
+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.
+
+You might expect the double scan to change the results when a
+self-referential macro is used in an argument of another macro
+(@pxref{Self-Referential Macros}): 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.
+
+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:
+
+@itemize @bullet
+@item
+Nested calls to a macro.
+
+We say that @dfn{nested} calls to a macro occur when a macro's argument
+contains a call to that very macro.  For example, if @code{f} is a macro
+that expects one argument, @code{f (f (1))} is a nested pair of calls to
+@code{f}.  The desired expansion is made by expanding @code{f (1)} and
+substituting that into the definition of @code{f}.  The prescan causes
+the expected result to happen.  Without the prescan, @code{f (1)} itself
+would be substituted as an argument, and the inner use of @code{f} would
+appear during the main scan as an indirect self-reference and would not
+be expanded.
+
+@item
+Macros that call other macros that stringize or concatenate.
+
+If an argument is stringized or concatenated, the prescan does not
+occur.  If you @emph{want} 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
+
+@smallexample
+#define AFTERX(x) X_ ## x
+#define XAFTERX(x) AFTERX(x)
+#define TABLESIZE 1024
+#define BUFSIZE TABLESIZE
+@end smallexample
+
+then @code{AFTERX(BUFSIZE)} expands to @code{X_BUFSIZE}, and
+@code{XAFTERX(BUFSIZE)} expands to @code{X_1024}.  (Not to
+@code{X_TABLESIZE}.  Prescan always does a complete expansion.)
+
+@item
+Macros used in arguments, whose expansions contain unshielded commas.
+
+This can cause a macro expanded on the second scan to be called with the
+wrong number of arguments.  Here is an example:
+
+@smallexample
+#define foo  a,b
+#define bar(x) lose(x)
+#define lose(x) (1 + (x))
+@end smallexample
+
+We would like @code{bar(foo)} to turn into @code{(1 + (foo))}, which
+would then turn into @code{(1 + (a,b))}.  Instead, @code{bar(foo)}
+expands into @code{lose(a,b)}, and you get an error because @code{lose}
+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:
+
+@smallexample
+#define foo (a,b)
+@exdent or
+#define bar(x) lose((x))
+@end smallexample
+
+The extra pair of parentheses prevents the comma in @code{foo}'s
+definition from being interpreted as an argument separator.
+
+@end itemize
+
+@node Newlines in Arguments
+@subsection Newlines in Arguments
+@cindex newlines in macro arguments
+
+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.
+
+Here is an example illustrating this:
+
+@smallexample
+#define ignore_second_arg(a,b,c) a; c
+
+ignore_second_arg (foo (),
+                   ignored (),
+                   syntax error);
+@end smallexample
+
+@noindent
+The syntax error triggered by the tokens @code{syntax error} results in
+an error message citing line three---the line of ignore_second_arg---
+even though the problematic code comes from line five.
+
+We consider this a bug, and intend to fix it in the near future.
+
+@node Conditionals
+@chapter Conditionals
+@cindex conditionals
+
+A @dfn{conditional} 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} operator.
+
+A conditional in the C preprocessor resembles in some ways an @code{if}
+statement in C, but it is important to understand the difference between
+them.  The condition in an @code{if} 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.
+
+However, the distinction is becoming less clear.  Modern compilers often
+do test @code{if} 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}
+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.
+
+@menu
+* Conditional Uses::
+* Conditional Syntax::
+* Deleted Code::
+@end menu
+
+@node Conditional Uses
+@section Conditional Uses
+
+There are three general reasons to use a conditional.
+
+@itemize @bullet
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+@end itemize
+
+Simple programs that do not need system-specific logic or complex
+debugging hooks generally will not need to use preprocessing
+conditionals.
+
+@node Conditional Syntax
+@section Conditional Syntax
+
+@findex #if
+A conditional in the C preprocessor begins with a @dfn{conditional
+directive}: @samp{#if}, @samp{#ifdef} or @samp{#ifndef}.
+
+@menu
+* Ifdef::
+* If::
+* Defined::
+* Else::
+* Elif::
+* @code{__has_attribute}::
+* @code{__has_cpp_attribute}::
+* @code{__has_c_attribute}::
+* @code{__has_builtin}::
+* @code{__has_include}::
+@end menu
+
+@node Ifdef
+@subsection Ifdef
+@findex #ifdef
+@findex #endif
+
+The simplest sort of conditional is
+
+@smallexample
+@group
+#ifdef @var{MACRO}
+
+@var{controlled text}
+
+#endif /* @var{MACRO} */
+@end group
+@end smallexample
+
+@cindex conditional group
+This block is called a @dfn{conditional group}.  @var{controlled text}
+will be included in the output of the preprocessor if and only if
+@var{MACRO} is defined.  We say that the conditional @dfn{succeeds} if
+@var{MACRO} is defined, @dfn{fails} if it is not.
+
+The @var{controlled text} 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} always matches the nearest @samp{#ifdef} (or
+@samp{#ifndef}, or @samp{#if}).  Also, you cannot start a conditional
+group in one file and end it in another.
+
+Even if a conditional fails, the @var{controlled text} 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.
+
+The comment following the @samp{#endif} is not required, but it is a
+good practice if there is a lot of @var{controlled text}, because it
+helps people match the @samp{#endif} to the corresponding @samp{#ifdef}.
+Older programs sometimes put @var{MACRO} directly after the
+@samp{#endif} 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} the @samp{#endif} matches.
+
+@findex #ifndef
+Sometimes you wish to use some code if a macro is @emph{not} defined.
+You can do this by writing @samp{#ifndef} instead of @samp{#ifdef}.
+One common use of @samp{#ifndef} is to include code only the first
+time a header file is included.  @xref{Once-Only Headers}.
+
+Macro definitions can vary between compilations for several reasons.
+Here are some samples.
+
+@itemize @bullet
+@item
+Some macros are predefined on each kind of machine
+(@pxref{System-specific Predefined Macros}).  This allows you to provide
+code specially tuned for a particular machine.
+
+@item
+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.
+
+@item
+Macros can be defined or undefined with the @option{-D} and @option{-U}
+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.  @xref{Invocation}.
+
+@item
+Your program might have a special header file (often called
+@file{config.h}) 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 @command{autoconf}, or done by hand.
+@end itemize
+
+@node If
+@subsection If
+
+The @samp{#if} directive allows you to test the value of an arithmetic
+expression, rather than the mere existence of one macro.  Its syntax is
+
+@smallexample
+@group
+#if @var{expression}
+
+@var{controlled text}
+
+#endif /* @var{expression} */
+@end group
+@end smallexample
+
+@var{expression} is a C expression of integer type, subject to stringent
+restrictions.  It may contain
+
+@itemize @bullet
+@item
+Integer constants.
+
+@item
+Character constants, which are interpreted as they would be in normal
+code.
+
+@item
+Arithmetic operators for addition, subtraction, multiplication,
+division, bitwise operations, shifts, comparisons, and logical
+operations (@code{&&} and @code{||}).  The latter two obey the usual
+short-circuiting rules of standard C@.
+
+@item
+Macros.  All macros in the expression are expanded before actual
+computation of the expression's value begins.
+
+@item
+Uses of the @code{defined} operator, which lets you check whether macros
+are defined in the middle of an @samp{#if}.
+
+@item
+Identifiers that are not macros, which are all considered to be the
+number zero.  This allows you to write @code{@w{#if MACRO}} instead of
+@code{@w{#ifdef MACRO}}, 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.
+
+In some contexts this shortcut is undesirable.  The @option{-Wundef}
+option causes GCC to warn whenever it encounters an identifier which is
+not a macro in an @samp{#if}.
+@end itemize
+
+The preprocessor does not know anything about types in the language.
+Therefore, @code{sizeof} operators are not recognized in @samp{#if}, and
+neither are @code{enum} constants.  They will be taken as identifiers
+which are not macros, and replaced by zero.  In the case of
+@code{sizeof}, this is likely to cause the expression to be invalid.
+
+The preprocessor calculates the value of @var{expression}.  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} succeeds and the @var{controlled
+text} is included; otherwise it is skipped.
+
+@node Defined
+@subsection Defined
+
+@cindex @code{defined}
+The special operator @code{defined} is used in @samp{#if} and
+@samp{#elif} expressions to test whether a certain name is defined as a
+macro.  @code{defined @var{name}} and @code{defined (@var{name})} are
+both expressions whose value is 1 if @var{name} is defined as a macro at
+the current point in the program, and 0 otherwise.  Thus,  @code{@w{#if
+defined MACRO}} is precisely equivalent to @code{@w{#ifdef MACRO}}.
+
+@code{defined} is useful when you wish to test more than one macro for
+existence at once.  For example,
+
+@smallexample
+#if defined (__vax__) || defined (__ns16000__)
+@end smallexample
+
+@noindent
+would succeed if either of the names @code{__vax__} or
+@code{__ns16000__} is defined as a macro.
+
+Conditionals written like this:
+
+@smallexample
+#if defined BUFSIZE && BUFSIZE >= 1024
+@end smallexample
+
+@noindent
+can generally be simplified to just @code{@w{#if BUFSIZE >= 1024}},
+since if @code{BUFSIZE} is not defined, it will be interpreted as having
+the value zero.
+
+If the @code{defined} 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} operator and evaluates it normally.  It will warn
+wherever your code uses this feature if you use the command-line option
+@option{-Wpedantic}, since other compilers may handle it differently.  The
+warning is also enabled by @option{-Wextra}, and can also be enabled
+individually with @option{-Wexpansion-to-defined}.
+
+@node Else
+@subsection Else
+
+@findex #else
+The @samp{#else} directive can be added to a conditional to provide
+alternative text to be used if the condition fails.  This is what it
+looks like:
+
+@smallexample
+@group
+#if @var{expression}
+@var{text-if-true}
+#else /* Not @var{expression} */
+@var{text-if-false}
+#endif /* Not @var{expression} */
+@end group
+@end smallexample
+
+@noindent
+If @var{expression} is nonzero, the @var{text-if-true} is included and
+the @var{text-if-false} is skipped.  If @var{expression} is zero, the
+opposite happens.
+
+You can use @samp{#else} with @samp{#ifdef} and @samp{#ifndef}, too.
+
+@node Elif
+@subsection Elif
+
+@findex #elif
+One common case of nested conditionals is used to check for more than two
+possible alternatives.  For example, you might have
+
+@smallexample
+#if X == 1
+@dots{}
+#else /* X != 1 */
+#if X == 2
+@dots{}
+#else /* X != 2 */
+@dots{}
+#endif /* X != 2 */
+#endif /* X != 1 */
+@end smallexample
+
+Another conditional directive, @samp{#elif}, allows this to be
+abbreviated as follows:
+
+@smallexample
+#if X == 1
+@dots{}
+#elif X == 2
+@dots{}
+#else /* X != 2 and X != 1*/
+@dots{}
+#endif /* X != 2 and X != 1*/
+@end smallexample
+
+@samp{#elif} stands for ``else if''.  Like @samp{#else}, it goes in the
+middle of a conditional group and subdivides it; it does not require a
+matching @samp{#endif} of its own.  Like @samp{#if}, the @samp{#elif}
+directive includes an expression to be tested.  The text following the
+@samp{#elif} is processed only if the original @samp{#if}-condition
+failed and the @samp{#elif} condition succeeds.
+
+More than one @samp{#elif} can go in the same conditional group.  Then
+the text after each @samp{#elif} is processed only if the @samp{#elif}
+condition succeeds after the original @samp{#if} and all previous
+@samp{#elif} directives within it have failed.
+
+@samp{#else} is allowed after any number of @samp{#elif} directives, but
+@samp{#elif} may not follow @samp{#else}.
+
+@node @code{__has_attribute}
+@subsection @code{__has_attribute}
+@cindex @code{__has_attribute}
+
+The special operator @code{__has_attribute (@var{operand})} may be used
+in @samp{#if} and @samp{#elif} expressions to test whether the attribute
+referenced by its @var{operand} 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} must be
+a valid identifier.  Otherwise, @var{operand} may be optionally
+introduced by the @code{@var{attribute-scope}::} prefix.
+The @var{attribute-scope} prefix identifies the ``namespace'' within
+which the attribute is recognized.  The scope of GCC attributes is
+@samp{gnu} or @samp{__gnu__}.  The @code{__has_attribute} operator by
+itself, without any @var{operand} 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:
+
+@smallexample
+#if defined __has_attribute
+#  if __has_attribute (nonnull)
+#    define ATTR_NONNULL __attribute__ ((nonnull))
+#  endif
+#endif
+@end smallexample
+
+The first @samp{#if} 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} 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.
+
+@smallexample
+#if defined __has_attribute && __has_attribute (nonnull)   /* not portable */
+@dots{}
+#endif
+@end smallexample
+
+@node @code{__has_cpp_attribute}
+@subsection @code{__has_cpp_attribute}
+@cindex @code{__has_cpp_attribute}
+
+The special operator @code{__has_cpp_attribute (@var{operand})} may be used
+in @samp{#if} and @samp{#elif} expressions in C++ code to test whether
+the attribute referenced by its @var{operand} is recognized by GCC.
+@code{__has_cpp_attribute (@var{operand})} is equivalent to
+@code{__has_attribute (@var{operand})} except that when @var{operand}
+designates a supported standard attribute it evaluates to an integer
+constant of the form @code{YYYYMM} 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 @w{@uref{https://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations/,
+SD-6: SG10 Feature Test Recommendations}}.
+
+@node @code{__has_c_attribute}
+@subsection @code{__has_c_attribute}
+@cindex @code{__has_c_attribute}
+
+The special operator @code{__has_c_attribute (@var{operand})} may be
+used in @samp{#if} and @samp{#elif} expressions in C code to test
+whether the attribute referenced by its @var{operand} is recognized by
+GCC in attributes using the @samp{[[]]} syntax.  GNU attributes must
+be specified with the scope @samp{gnu} or @samp{__gnu__} with
+@code{__has_c_attribute}.  When @var{operand} designates a supported
+standard attribute it evaluates to an integer constant of the form
+@code{YYYYMM} 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.
+
+@node @code{__has_builtin}
+@subsection @code{__has_builtin}
+@cindex @code{__has_builtin}
+
+The special operator @code{__has_builtin (@var{operand})} may be used in
+constant integer contexts and in preprocessor @samp{#if} and @samp{#elif}
+expressions to test whether the symbol named by its @var{operand} 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} and @samp{#elif}
+expressions.  The @code{__has_builtin} operator by itself, without any
+@var{operand} 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:
+
+@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
+@end smallexample
+
+@node @code{__has_include}
+@subsection @code{__has_include}
+@cindex @code{__has_include}
+
+The special operator @code{__has_include (@var{operand})} may be used in
+@samp{#if} and @samp{#elif} expressions to test whether the header referenced
+by its @var{operand} can be included using the @samp{#include} directive.  Using
+the operator in other contexts is not valid.  The @var{operand} takes
+the same form as the file in the @samp{#include} directive (@pxref{Include
+Syntax}) 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}
+directives that would cause the preprocessor to fail.
+
+The @code{__has_include} operator by itself, without any @var{operand} 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:
+
+@smallexample
+#if defined __has_include
+#  if __has_include (<stdatomic.h>)
+#    include <stdatomic.h>
+#  endif
+#endif
+@end smallexample
+
+The first @samp{#if} 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} 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.
+
+@smallexample
+#if defined __has_include && __has_include ("header.h")   /* not portable */
+@dots{}
+#endif
+@end smallexample
+
+@node Deleted Code
+@section Deleted Code
+@cindex commenting out code
+
+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.
+
+One way to avoid this problem is to use an always-false conditional
+instead.  For instance, put @code{#if 0} before the deleted code and
+@code{#endif} after it.  This works even if the code being turned
+off contains conditionals, but they must be entire conditionals
+(balanced @samp{#if} and @samp{#endif}).
+
+Some people use @code{#ifdef notdef} instead.  This is risky, because
+@code{notdef} might be accidentally defined as a macro, and then the
+conditional would succeed.  @code{#if 0} can be counted on to fail.
+
+Do not use @code{#if 0} for comments which are not C code.  Use a real
+comment, instead.  The interior of @code{#if 0} 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}.  They don't confuse
+@samp{/*}.
+
+@node Diagnostics
+@chapter Diagnostics
+@cindex diagnostic
+@cindex reporting errors
+@cindex reporting warnings
+
+@findex #error
+The directive @samp{#error} causes the preprocessor to report a fatal
+error.  The tokens forming the rest of the line following @samp{#error}
+are used as the error message.
+
+You would use @samp{#error} 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
+
+@smallexample
+@group
+#ifdef __vax__
+#error "Won't work on VAXen.  See comments at get_last_object."
+#endif
+@end group
+@end smallexample
+
+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}.  For example,
+
+@smallexample
+#if !defined(FOO) && defined(BAR)
+#error "BAR requires FOO."
+#endif
+@end smallexample
+
+@findex #warning
+The directive @samp{#warning} is like @samp{#error}, but causes the
+preprocessor to issue a warning and continue preprocessing.  The tokens
+following @samp{#warning} are used as the warning message.
+
+You might use @samp{#warning} in obsolete header files, with a message
+directing the user to the header file which should be used instead.
+
+Neither @samp{#error} nor @samp{#warning} 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.
+
+@node Line Control
+@chapter Line Control
+@cindex line control
+
+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.
+
+If you write a program which generates source code, such as the
+@command{bison} 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 @command{bison} are generated from scratch, other parts come
+from a standard parser file.  The rest are copied verbatim from
+@command{bison}'s input.  You would like compiler error messages and
+symbolic debuggers to be able to refer to @code{bison}'s input file.
+
+@findex #line
+@command{bison} or any such program can arrange this by writing
+@samp{#line} directives into the output file.  @samp{#line} is a
+directive that specifies the original line number and source file name
+for subsequent input in the current preprocessor input file.
+@samp{#line} has three variants:
+
+@table @code
+@item #line @var{linenum}
+@var{linenum} 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}.
+
+@item #line @var{linenum} @var{filename}
+@var{linenum} is the same as for the first form, and has the same
+effect.  In addition, @var{filename} 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} is interpreted according to the normal rules for a string
+constant: backslash escapes are interpreted.  This is different from
+@samp{#include}.
+
+@item #line @var{anything else}
+@var{anything else} is checked for macro calls, which are expanded.
+The result should match one of the above two forms.
+@end table
+
+@samp{#line} directives alter the results of the @code{__FILE__} and
+@code{__LINE__} predefined macros from that point on.  @xref{Standard
+Predefined Macros}.  They do not have any effect on @samp{#include}'s
+idea of the directory containing the current file.
+
+@node Pragmas
+@chapter Pragmas
+
+@cindex pragma directive
+
+The @samp{#pragma} 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 @dfn{pragmas}) specified by C standard are prefixed with 
+@code{STDC}.  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} prefix.
+
+@cindex @code{_Pragma}
+C99 introduced the @code{@w{_Pragma}} operator.  This feature addresses a
+major problem with @samp{#pragma}: being a directive, it cannot be
+produced as the result of macro expansion.  @code{@w{_Pragma}} is an
+operator, much like @code{sizeof} or @code{defined}, and can be embedded
+in a macro.
+
+Its syntax is @code{@w{_Pragma (@var{string-literal})}}, where
+@var{string-literal} can be either a normal or wide-character string
+literal.  It is destringized, by replacing all @samp{\\} with a single
+@samp{\} and all @samp{\"} with a @samp{"}.  The result is then
+processed as if it had appeared as the right hand side of a
+@samp{#pragma} directive.  For example,
+
+@smallexample
+_Pragma ("GCC dependency \"parse.y\"")
+@end smallexample
+
+@noindent
+has the same effect as @code{#pragma GCC dependency "parse.y"}.  The
+same effect could be achieved using macros, for example
+
+@smallexample
+#define DO_PRAGMA(x) _Pragma (#x)
+DO_PRAGMA (GCC dependency "parse.y")
+@end smallexample
+
+The standard is unclear on where a @code{_Pragma} operator can appear.
+The preprocessor does not accept it within a preprocessing conditional
+directive like @samp{#if}.  To be safe, you are probably best keeping it
+out of directives other than @samp{#define}, and putting it on a line of
+its own.
+
+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.
+
+GCC plugins may provide their own pragmas.
+
+@ftable @code
+@item #pragma GCC dependency
+@code{#pragma GCC dependency} 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.
+
+@smallexample
+#pragma GCC dependency "parse.y"
+#pragma GCC dependency "/usr/include/time.h" rerun fixincludes
+@end smallexample
+
+@item #pragma GCC poison
+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 @dfn{poison} the identifier with this pragma.
+@code{#pragma GCC poison} 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,
+
+@smallexample
+#pragma GCC poison printf sprintf fprintf
+sprintf(some_string, "hello");
+@end smallexample
+
+@noindent
+will produce an error.
+
+If a poisoned identifier appears as part of the expansion of a macro
+which was defined before the identifier was poisoned, it will @emph{not}
+cause an error.  This lets you poison an identifier without worrying
+about system headers defining macros that use it.
+
+For example,
+
+@smallexample
+#define strrchr rindex
+#pragma GCC poison rindex
+strrchr(some_string, 'h');
+@end smallexample
+
+@noindent
+will not produce an error.
+
+@item #pragma GCC system_header
+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.
+@xref{System Headers}.
+
+@item #pragma GCC warning
+@itemx #pragma GCC error
+@code{#pragma GCC warning "message"} causes the preprocessor to issue
+a warning diagnostic with the text @samp{message}.  The message
+contained in the pragma must be a single string literal.  Similarly,
+@code{#pragma GCC error "message"} issues an error message.  Unlike
+the @samp{#warning} and @samp{#error} directives, these pragmas can be
+embedded in preprocessor macros using @samp{_Pragma}.
+
+@item #pragma once
+If @code{#pragma once} 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} to guard the contents of header files
+against multiple inclusions.
+
+@end ftable
+
+@node Other Directives
+@chapter Other Directives
+
+@findex #ident
+@findex #sccs
+The @samp{#ident} 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} directive is a synonym for @samp{#ident}.
+
+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@.
+
+@cindex null directive
+The @dfn{null directive} consists of a @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{#} will
+produce no output, rather than a line of output containing just a
+@samp{#}.  Supposedly some old C programs contain such lines.
+
+@node Preprocessor Output
+@chapter Preprocessor Output
+
+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.
+@c FIXME: Document the library interface.
+
+@cindex output format
+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.
+
+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.
+
+@cindex linemarkers
+Source file name and line number information is conveyed by lines
+of the form
+
+@smallexample
+# @var{linenum} @var{filename} @var{flags}
+@end smallexample
+
+@noindent
+These are called @dfn{linemarkers}.  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} at line
+@var{linenum}.  @var{filename} will never contain any non-printing
+characters; they are replaced with octal escape sequences.
+
+After the file name comes zero or more flags, which are @samp{1},
+@samp{2}, @samp{3}, or @samp{4}.  If there are multiple flags, spaces
+separate them.  Here is what the flags mean:
+
+@table @samp
+@item 1
+This indicates the start of a new file.
+@item 2
+This indicates returning to a file (after having included another file).
+@item 3
+This indicates that the following text comes from a system header file,
+so certain warnings should be suppressed.
+@item 4
+This indicates that the following text should be treated as being
+wrapped in an implicit @code{extern "C"} block.
+@c maybe cross reference SYSTEM_IMPLICIT_EXTERN_C
+@end table
+
+As an extension, the preprocessor accepts linemarkers in non-assembler
+input files.  They are treated like the corresponding @samp{#line}
+directive, (@pxref{Line Control}), 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.
+
+Some directives may be duplicated in the output of the preprocessor.
+These are @samp{#ident} (always), @samp{#pragma} (only if the
+preprocessor does not handle the pragma itself), and @samp{#define} and
+@samp{#undef} (with certain debugging options).  If this happens, the
+@samp{#} of the directive will always be in the first column, and there
+will be no space between the @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{#} and
+the directive name.
+
+@node Traditional Mode
+@chapter Traditional Mode
+
+Traditional (pre-standard) C preprocessing is rather different from
+the preprocessing specified by the standard.  When the preprocessor 
+is invoked with the 
+@option{-traditional-cpp} option, it attempts to emulate a traditional
+preprocessor.  
+
+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.
+
+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.
+
+@menu
+* Traditional lexical analysis::
+* Traditional macros::
+* Traditional miscellany::
+* Traditional warnings::
+@end menu
+
+@node Traditional lexical analysis
+@section Traditional lexical analysis
+
+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.
+
+This implementation does not treat trigraphs (@pxref{trigraphs})
+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.
+
+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.
+
+Traditional CPP only recognizes C-style block comments, and treats the
+@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{<} in a @code{#include}
+directive.
+
+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
+
+@smallexample
+#if foo/**/bar
+@end smallexample
+
+@noindent
+@samp{foo} and @samp{bar} are distinct identifiers and expanded
+separately if they happen to be macros.  In other words, this
+directive is equivalent to
+
+@smallexample
+#if foo bar
+@end smallexample
+
+@noindent
+rather than
+
+@smallexample
+#if foobar
+@end smallexample
+
+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.
+
+However, all preprocessing directives other than @code{#define}
+require matching quotes.  For example:
+
+@smallexample
+#define m This macro's fine and has an unmatched quote
+"/* This is not a comment.  */
+/* @r{This is a comment.  The following #include directive
+   is ill-formed.}  */
+#include <stdio.h
+@end smallexample
+
+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.
+
+@node Traditional macros
+@section Traditional macros
+
+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.
+
+One consequence is that it is legitimate for the replacement text to
+contain an unmatched quote (@pxref{Traditional lexical analysis}).  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.
+
+Normally comments are removed from the replacement text after the
+macro is expanded, but if the @option{-CC} 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.)
+
+The ISO stringizing operator @samp{#} and token paste operator
+@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.
+
+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 @emph{ad infinitum}.  GCC detects when it is expanding
+recursive macros, emits an error message, and continues after the
+offending macro invocation.
+
+@smallexample
+#define PLUS +
+#define INC(x) PLUS+x
+INC(foo);
+     @expansion{} ++foo;
+@end smallexample
+
+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.
+
+This implementation removes all comments from macro arguments, unless
+the @option{-C} option is given.  The form of all other horizontal
+whitespace in arguments is preserved, including leading and trailing
+whitespace.  In particular
+
+@smallexample
+f( )
+@end smallexample
+
+@noindent
+is treated as an invocation of the macro @samp{f} 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.
+
+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.
+
+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
+
+@smallexample
+#define str(x) "x"
+str(/* @r{A comment} */some text )
+     @expansion{} "some text "
+@end smallexample
+
+@noindent
+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.
+
+@smallexample
+#define suffix(x) foo_/**/x
+suffix(bar)
+     @expansion{} foo_bar
+@end smallexample
+
+@node Traditional miscellany
+@section Traditional miscellany
+
+Here are some things to be aware of when using the traditional
+preprocessor.
+
+@itemize @bullet
+@item
+Preprocessing directives are recognized only when their leading
+@samp{#} appears in the first column.  There can be no whitespace
+between the beginning of the line and the @samp{#}, but whitespace can
+follow the @samp{#}.
+
+@item
+A true traditional C preprocessor does not recognize @samp{#error} or
+@samp{#pragma}, and may not recognize @samp{#elif}.  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} are undefined.
+
+@item
+__STDC__ is not defined.
+
+@item
+If you use digraphs the behavior is undefined.
+
+@item
+If a line that looks like a directive appears within macro arguments,
+the behavior is undefined.
+
+@end itemize
+
+@node Traditional warnings
+@section Traditional warnings
+You can request warnings about features that did not exist, or worked
+differently, in traditional C with the @option{-Wtraditional} 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{#} and @samp{##}
+operators.
+
+Presently @option{-Wtraditional} warns about:
+
+@itemize @bullet
+@item
+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@.
+
+@item
+In traditional C, some preprocessor directives did not exist.
+Traditional preprocessors would only consider a line to be a directive
+if the @samp{#} appeared in column 1 on the line.  Therefore
+@option{-Wtraditional} warns about directives that traditional C
+understands but would ignore because the @samp{#} does not appear as the
+first character on the line.  It also suggests you hide directives like
+@samp{#pragma} not understood by traditional C by indenting them.  Some
+traditional implementations would not recognize @samp{#elif}, so it
+suggests avoiding it altogether.
+
+@item
+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.
+
+@item
+The unary plus operator.  This did not exist in traditional C@.
+
+@item
+The @samp{U} and @samp{LL} integer constant suffixes, which were not
+available in traditional C@.  (Traditional C does support the @samp{L}
+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} may well be defined as @code{4294967295U}, but
+you will not be warned if you use @code{UINT_MAX}.
+
+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.
+@end itemize
+
+@node Implementation Details
+@chapter Implementation Details
+
+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.
+
+Also documented here are obsolete features still supported by CPP@.
+
+@menu
+* Implementation-defined behavior::
+* Implementation limits::
+* Obsolete Features::
+@end menu
+
+@node Implementation-defined behavior
+@section Implementation-defined behavior
+@cindex implementation-defined behavior
+
+This is how CPP behaves in all the cases which the C standard
+describes as @dfn{implementation-defined}.  This term means that the
+implementation is free to do what it likes, but must document its choice
+and stick to it.
+@c FIXME: Check the C++ standard for more implementation-defined stuff.
+
+@itemize @bullet
+@need 1000
+@item The mapping of physical source file multi-byte characters to the
+execution character set.
+
+The input character set can be specified using the
+@option{-finput-charset} option, while the execution character set may
+be controlled using the @option{-fexec-charset} and
+@option{-fwide-exec-charset} options.
+
+@item Identifier characters.
+@anchor{Identifier characters}
+
+The C and C++ standards allow identifiers to be composed of @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.
+
+GCC allows the @samp{$} character in identifiers as an extension for
+most targets.  This is true regardless of the @option{std=} switch,
+since this extension cannot conflict with standards-conforming
+programs.  When preprocessing assembler, however, dollars are not
+identifier characters by default.
+
+Currently the targets that by default do not permit @samp{$} are AVR,
+IP2K, MMIX, MIPS Irix 3, ARM aout, and PowerPC targets for the AIX
+operating system.
+
+You can override the default with @option{-fdollars-in-identifiers} or
+@option{-fno-dollars-in-identifiers}.  @xref{fdollars-in-identifiers}.
+
+@item Non-empty sequences of whitespace characters.
+
+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.
+
+@item The numeric value of character constants in preprocessor expressions.
+
+The preprocessor and compiler interpret character constants in the
+same way; i.e.@: escape sequences such as @samp{\a} are given the
+values they would have on the target machine.
+
+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}, 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} the
+compiler issues a warning, and the excess leading characters are
+ignored.
+
+For example, @code{'ab'} for a target with an 8-bit @code{char} would be
+interpreted as @w{@samp{(int) ((unsigned char) 'a' * 256 + (unsigned char)
+'b')}}, and @code{'\234a'} as @w{@samp{(int) ((unsigned char) '\234' *
+256 + (unsigned char) 'a')}}.
+
+@item Source file inclusion.
+
+For a discussion on how the preprocessor locates header files,
+@ref{Include Operation}.
+
+@item Interpretation of the filename resulting from a macro-expanded
+@samp{#include} directive.
+
+@xref{Computed Includes}.
+
+@item Treatment of a @samp{#pragma} directive that after macro-expansion
+results in a standard pragma.
+
+No macro expansion occurs on any @samp{#pragma} directive line, so the
+question does not arise.
+
+Note that GCC does not yet implement any of the standard
+pragmas.
+
+@end itemize
+
+@node Implementation limits
+@section Implementation limits
+@cindex implementation limits
+
+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.  @xref{Bugs, , Reporting Bugs, gcc, Using
+the GNU Compiler Collection (GCC)}.
+
+Where we say something is limited @dfn{only by available memory}, that
+means that internal data structures impose no intrinsic limit, and space
+is allocated with @code{malloc} 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.
+
+@itemize @bullet
+
+@item Nesting levels of @samp{#include} files.
+
+We impose an arbitrary limit of 200 levels, to avoid runaway recursion.
+The standard requires at least 15 levels.
+
+@item Nesting levels of conditional inclusion.
+
+The C standard mandates this be at least 63.  CPP is limited only by
+available memory.
+
+@item Levels of parenthesized expressions within a full expression.
+
+The C standard requires this to be at least 63.  In preprocessor
+conditional expressions, it is limited only by available memory.
+
+@item Significant initial characters in an identifier or macro name.
+
+The preprocessor treats all characters as significant.  The C standard
+requires only that the first 63 be significant.
+
+@item Number of macros simultaneously defined in a single translation unit.
+
+The standard requires at least 4095 be possible.  CPP is limited only
+by available memory.
+
+@item Number of parameters in a macro definition and arguments in a macro call.
+
+We allow @code{USHRT_MAX}, which is no smaller than 65,535.  The minimum
+required by the standard is 127.
+
+@item Number of characters on a logical source line.
+
+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.
+
+@item Maximum size of a source file.
+
+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.
+
+@end itemize
+
+@node Obsolete Features
+@section Obsolete Features
+
+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@.
+
+@subsection Assertions
+@cindex assertions
+
+@dfn{Assertions} 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.
+
+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} portable than the use
+of system-specific predefined macros.  We recommend you do not use them at
+all.
+
+@cindex predicates
+An assertion looks like this:
+
+@smallexample
+#@var{predicate} (@var{answer})
+@end smallexample
+
+@noindent
+@var{predicate} must be a single identifier.  @var{answer} 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)} is different from @code{(x+y)} but
+equivalent to @code{@w{( x + y )}}.  Parentheses do not nest inside an
+answer.
+
+@cindex testing predicates
+To test an assertion, you write it in an @samp{#if}.  For example, this
+conditional succeeds if either @code{vax} or @code{ns16000} has been
+asserted as an answer for @code{machine}.
+
+@smallexample
+#if #machine (vax) || #machine (ns16000)
+@end smallexample
+
+@noindent
+You can test whether @emph{any} answer is asserted for a predicate by
+omitting the answer in the conditional:
+
+@smallexample
+#if #machine
+@end smallexample
+
+@findex #assert
+Assertions are made with the @samp{#assert} directive.  Its sole
+argument is the assertion to make, without the leading @samp{#} that
+identifies assertions in conditionals.
+
+@smallexample
+#assert @var{predicate} (@var{answer})
+@end smallexample
+
+@noindent
+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.
+
+@cindex assertions, canceling
+@findex #unassert
+Assertions can be canceled with the @samp{#unassert} directive.  It
+has the same syntax as @samp{#assert}.  In that form it cancels only the
+answer which was specified on the @samp{#unassert} line; other answers
+for that predicate remain true.  You can cancel an entire predicate by
+leaving out the answer:
+
+@smallexample
+#unassert @var{predicate}
+@end smallexample
+
+@noindent
+In either form, if no such assertion has been made, @samp{#unassert} has
+no effect.
+
+You can also make or cancel assertions using command-line options.
+@xref{Invocation}.
+
+@node Invocation
+@chapter Invocation
+@cindex invocation
+@cindex command line
+
+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 @command{cpp} command, or via @command{gcc -E}.
+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.
+
+The @command{cpp} options listed here are also accepted by
+@command{gcc} and have the same meaning.  Likewise the @command{cpp}
+command accepts all the usual @command{gcc} driver options, although those
+pertaining to compilation phases after preprocessing are ignored.
+
+Only options specific to preprocessing behavior are documented here.
+Refer to the GCC manual for full documentation of other driver options.
+
+@ignore
+@c man begin SYNOPSIS
+cpp [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
+    [@option{-I}@var{dir}@dots{}] [@option{-iquote}@var{dir}@dots{}]
+    [@option{-M}|@option{-MM}] [@option{-MG}] [@option{-MF} @var{filename}]
+    [@option{-MP}] [@option{-MQ} @var{target}@dots{}]
+    [@option{-MT} @var{target}@dots{}]
+    @var{infile} [[@option{-o}] @var{outfile}]
+
+Only the most useful options are given above; see below for a more
+complete list of preprocessor-specific options.  
+In addition, @command{cpp} accepts most @command{gcc} driver options, which
+are not listed here.  Refer to the GCC documentation for details.
+@c man end
+@c man begin SEEALSO
+gpl(7), gfdl(7), fsf-funding(7),
+gcc(1), and the Info entries for @file{cpp} and @file{gcc}.
+@c man end
+@end ignore
+
+@c man begin OPTIONS
+The @command{cpp} command expects two file names as arguments, @var{infile} and
+@var{outfile}.  The preprocessor reads @var{infile} together with any
+other files it specifies with @samp{#include}.  All the output generated
+by the combined input files is written in @var{outfile}.
+
+Either @var{infile} or @var{outfile} may be @option{-}, which as
+@var{infile} means to read from standard input and as @var{outfile}
+means to write to standard output.  If either file is omitted, it
+means the same as if @option{-} had been specified for that file.
+You can also use the @option{-o @var{outfile}} option to specify the 
+output file.
+
+Unless otherwise noted, or the option ends in @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:
+@option{-Ifoo} and @option{-I foo} have the same effect.
+
+@cindex grouping options
+@cindex options, grouping
+Many options have multi-letter names; therefore multiple single-letter
+options may @emph{not} be grouped: @option{-dM} is very different from
+@w{@samp{-d -M}}.
+
+@cindex options
+
+@table @gcctabopt
+@include cppopts.texi
+@include cppdiropts.texi
+@include cppwarnopts.texi
+@end table
+@c man end
+
+@node Environment Variables
+@chapter Environment Variables
+@cindex environment variables
+@c man begin ENVIRONMENT
+
+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.
+
+Note that you can also specify places to search using options such as
+@option{-I}, and control dependency output with options like
+@option{-M} (@pxref{Invocation}).  These take precedence over
+environment variables, which in turn take precedence over the
+configuration of GCC@.
+
+@include cppenv.texi
+@c man end
+
+@page
+@include fdl.texi
+
+@page
+@node Index of Directives
+@unnumbered Index of Directives
+@printindex fn
+
+@node Option Index
+@unnumbered Option Index
+@noindent
+CPP's command-line options and environment variables are indexed here
+without any initial @samp{-} or @samp{--}.
+@printindex op
+
+@page
+@node Concept Index
+@unnumbered Concept Index
+@printindex cp
+
+@bye