| \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-2026 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:: | |
| * Binary Resource Inclusion:: | |
| * 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 | |
| @cindex line endings | |
| @item | |
| 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. | |
| @cindex trigraphs | |
| @item | |
| @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 | |
| @cindex continued lines | |
| @cindex backslash-newline | |
| @item | |
| 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. | |
| @cindex comments | |
| @cindex line comments | |
| @cindex block comments | |
| @item | |
| 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 successfully 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 | |
| @cindex system header files | |
| @item | |
| 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. | |
| @findex #pragma GCC system_header | |
| @item | |
| 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). The value @code{202311L} is used for the | |
| @option{-std=c23} and @option{-std=gnu23} modes. An unspecified value | |
| larger than @code{202311L} is used for the experimental | |
| @option{-std=c2y} and @option{-std=gnu2y} 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, | |
| @code{202302L} for the 2023 C++ standard, | |
| @code{202603L} for the 2026 C++ standard, | |
| or an unspecified value strictly larger than @code{202603L} for the | |
| experimental languages enabled by @option{-std=c++29} and | |
| @option{-std=gnu++29}. | |
| @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 __UNSAFE_MATH_OPTIMIZATIONS__ | |
| This macro is defined if @option{-funsafe-math-optimizations} is used, | |
| or enabled by another option such as @option{-ffast-math}. | |
| @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_feature}:: | |
| * @code{__has_extension}:: | |
| * @code{__has_include}:: @code{__has_include} and | |
| @code{__has_include_next} | |
| * @code{__has_embed}:: | |
| @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{#ifdef} 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 C23, @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_feature} | |
| @subsection @code{__has_feature} | |
| @cindex @code{__has_feature} | |
| The special operator @code{__has_feature (@var{operand})} may be used in | |
| constant integer contexts and in preprocessor @samp{#if} and @samp{#elif} | |
| expressions to test whether the identifier given in @var{operand} is recognized | |
| as a feature supported by GCC given the current options and, in the case of | |
| standard language features, whether the feature is available in the chosen | |
| version of the language standard. | |
| Note that @code{__has_feature} and @code{__has_extension} are not recommended | |
| for use in new code, and are only provided for compatibility with Clang. For | |
| details of which identifiers are accepted by these function-like macros, see | |
| @w{@uref{https://clang.llvm.org/docs/LanguageExtensions.html#has-feature-and-has-extension, | |
| the Clang documentation}}. | |
| @node @code{__has_extension} | |
| @subsection @code{__has_extension} | |
| @cindex @code{__has_extension} | |
| The special operator @code{__has_extension (@var{operand})} may be used in | |
| constant integer contexts and in preprocessor @samp{#if} and @samp{#elif} | |
| expressions to test whether the identifier given in @var{operand} is recognized | |
| as an extension supported by GCC given the current options. In any given | |
| context, the features accepted by @code{__has_extension} are a strict superset | |
| of those accepted by @code{__has_feature}. Unlike @code{__has_feature}, | |
| @code{__has_extension} tests whether a given feature is available regardless of | |
| strict language standards conformance. | |
| If the @option{-pedantic-errors} flag is given, @code{__has_extension} is | |
| equivalent to @code{__has_feature}. | |
| Note that @code{__has_feature} and @code{__has_extension} are not recommended | |
| for use in new code, and are only provided for compatibility with Clang. For | |
| details of which identifiers are accepted by these function-like macros, see | |
| @w{@uref{https://clang.llvm.org/docs/LanguageExtensions.html#has-feature-and-has-extension, | |
| the Clang documentation}}. | |
| @node @code{__has_include} | |
| @subsection @code{__has_include}, @code{__has_include_next} | |
| @cindex @code{__has_include} | |
| @cindex @code{__has_include_next} | |
| The special operators @code{__has_include (@var{operand})} and | |
| @code{__has_include_next (@var{operand})} may be used in @samp{#if} and | |
| @samp{#elif} expressions to test whether the header referenced by their | |
| @var{operand} can be included using the @samp{#include} and | |
| @samp{#include_next} directive, respectively. Using the operators in | |
| other contexts is not valid. The @var{operand} takes the same form as | |
| the file in the @samp{#include} and @samp{#include_next} directives | |
| respectively (@pxref{Include Syntax}) and the operators evaluate 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} and @code{__has_include_next} operators by | |
| themselves, without any @var{operand} or parentheses, act as | |
| predefined macros so that support for them can be tested in portable | |
| code. Thus, the recommended use of the operators 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 | |
| The same holds for @code{__has_include_next}. | |
| @node @code{__has_embed} | |
| @subsection @code{__has_embed} | |
| @cindex @code{__has_embed} | |
| The special operator @code{__has_embed (@var{operands})} may be used in | |
| @samp{#if} and @samp{#elif} expressions to test whether a binary resource | |
| specified by the first operand with optional @samp{#embed} parameters can | |
| be included using the @samp{#embed} directive (@pxref{Binary Resource | |
| Inclusion}) with the same parameters. The operator returns | |
| @code{__STDC_EMBED_NOT_FOUND__} if either the binary resource does not exist | |
| or at least one of the parameters is not supported by the implementation, | |
| @code{__STDC_EMBED_FOUND__} if all the parameters are supported and the | |
| resource is not empty and finally @code{__STDC_EMBED_EMPTY__} if all the | |
| parameters are supported and the resource is empty. | |
| The support of @code{__has_embed} operator can be tested with @samp{#ifdef} | |
| etc. similarly to @code{__has_include} and the same rules on how to | |
| test it apply. @code{__FILE__} can be often used to test if an | |
| implementation supports some implementation defined parameter, e.g.@: | |
| @smallexample | |
| #ifdef __has_embed | |
| #if __has_embed (__FILE__ limit (4) myvendor::myattr (42)) != __STDC_EMBED_NOT_FOUND__ | |
| #embed "foo.dat" limit (4) myvendor::myattr (42) | |
| #endif | |
| #endif | |
| @end smallexample | |
| The @code{__has_embed} operator is not supported in the Traditional Mode | |
| (@pxref{Traditional Mode}). | |
| @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. | |
| @item #pragma region @{tokens@}... | |
| @itemx #pragma endregion @{tokens@}... | |
| These pragmas are accepted, but have no effect. | |
| @end ftable | |
| @node Binary Resource Inclusion | |
| @chapter Binary Resource Inclusion | |
| @cindex embed directive | |
| The @samp{#embed} directive as specified in the C23 standard allows | |
| efficient inclusion of binary data, usually in initializers of arrays. | |
| GCC supports this directive in C23 mode and as an extension in older C | |
| versions and in C++. | |
| Similarly to the @samp{#include} directive (@pxref{Include Syntax}) | |
| the first argument of the directive is a filename in the same forms | |
| as @samp{#include}. | |
| @table @code | |
| @item #embed <@var{file}> | |
| If @var{file} is an absolute filename, this includes the mentioned | |
| file, otherwise searches it in directories specified by the | |
| @option{--embed-dir=} command-line option for the @var{file}. | |
| @item #embed "@var{file}" | |
| This variant searches @var{file} in the same directory as the source | |
| file which uses the @code{#embed} directive and only if not found there | |
| continues searching directories specified by the @option{--embed-dir=} | |
| command-line option. | |
| @end table | |
| The @code{#embed} directive is expanded as if it was a sequence of | |
| integer literals from 0 to @code{UCHAR_MAX} separated by commas, e.g.@: | |
| @code{#embed __FILE__ limit(4)} | |
| could act as if it expanded to | |
| @code{35,101,109,98}. No character set conversion is performed. | |
| Optional embed parameters can be specified after the required filename | |
| argument. There are either standard attributes, specified by an | |
| identifier or identifier prefixed and suffixed by 2 underscores (both | |
| treated the same), followed by parameter argument in parentheses, like | |
| @code{#embed "foo.dat" limit(1) __prefix__(32, ) suffix(, 0)} | |
| with currently supported standard parameters @code{limit}, @code{prefix}, | |
| @code{suffix} and @code{if_empty}, or implementation defined parameters | |
| specified by a unique vendor prefix followed by @code{::} followed by | |
| name of the parameter. GCC uses the @code{gnu} prefix for vendor | |
| parameters and currently supports the @code{gnu::offset} and | |
| @code{gnu::base64} parameters. | |
| The @code{limit} parameter argument is a constant expression which | |
| specifies the maximum number of bytes included by the directive, | |
| @code{prefix} and @code{suffix} arguments are balanced token sequences | |
| which are prepended and appended to the integer literal sequence if | |
| that sequence is not empty and @code{if_empty} argument is balanced token | |
| sequence which is used as expansion for @code{#embed} directive if the | |
| resource is empty. | |
| The @code{gnu::offset} parameter argument is a constant expression | |
| which specifies how many bytes to skip from the start of the resource. | |
| @code{limit} is then counted from that position. | |
| The @code{gnu::base64} parameter argument is a possibly concatenated | |
| character string literal with base64 encoded data. See | |
| @uref{https://datatracker.ietf.org/doc/html/rfc4648#section-4}. There | |
| should be no newlines in the string literal and because this parameter | |
| is meant namely for use by the preprocessor itself, there is no support | |
| for any escape sequences in the string literal argument. If @code{gnu::base64} | |
| parameter is specified, the @code{limit} and @code{gnu::offset} parameters | |
| should not be specified and the filename should be always @code{"."}. | |
| Instead of reading a file the directive will decode the base64 encoded | |
| data and use that as the data to include. | |
| The @code{#embed} directive is not supported in the Traditional Mode | |
| (@pxref{Traditional Mode}). | |
| @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 |