110d565efSmrg\input texinfo 210d565efSmrg@setfilename cpp.info 310d565efSmrg@settitle The C Preprocessor 410d565efSmrg@setchapternewpage off 510d565efSmrg@c @smallbook 610d565efSmrg@c @cropmarks 710d565efSmrg@c @finalout 810d565efSmrg 910d565efSmrg@include gcc-common.texi 1010d565efSmrg 1110d565efSmrg@copying 1210d565efSmrg@c man begin COPYRIGHT 13*ec02198aSmrgCopyright @copyright{} 1987-2020 Free Software Foundation, Inc. 1410d565efSmrg 1510d565efSmrgPermission is granted to copy, distribute and/or modify this document 1610d565efSmrgunder the terms of the GNU Free Documentation License, Version 1.3 or 1710d565efSmrgany later version published by the Free Software Foundation. A copy of 1810d565efSmrgthe license is included in the 1910d565efSmrg@c man end 2010d565efSmrgsection entitled ``GNU Free Documentation License''. 2110d565efSmrg@ignore 2210d565efSmrg@c man begin COPYRIGHT 2310d565efSmrgman page gfdl(7). 2410d565efSmrg@c man end 2510d565efSmrg@end ignore 2610d565efSmrg 2710d565efSmrg@c man begin COPYRIGHT 2810d565efSmrgThis manual contains no Invariant Sections. The Front-Cover Texts are 2910d565efSmrg(a) (see below), and the Back-Cover Texts are (b) (see below). 3010d565efSmrg 3110d565efSmrg(a) The FSF's Front-Cover Text is: 3210d565efSmrg 3310d565efSmrg A GNU Manual 3410d565efSmrg 3510d565efSmrg(b) The FSF's Back-Cover Text is: 3610d565efSmrg 3710d565efSmrg You have freedom to copy and modify this GNU Manual, like GNU 3810d565efSmrg software. Copies published by the Free Software Foundation raise 3910d565efSmrg funds for GNU development. 4010d565efSmrg@c man end 4110d565efSmrg@end copying 4210d565efSmrg 4310d565efSmrg@c Create a separate index for command line options. 4410d565efSmrg@defcodeindex op 4510d565efSmrg@syncodeindex vr op 4610d565efSmrg 4710d565efSmrg@c Used in cppopts.texi and cppenv.texi. 4810d565efSmrg@set cppmanual 4910d565efSmrg 5010d565efSmrg@ifinfo 5110d565efSmrg@dircategory Software development 5210d565efSmrg@direntry 5310d565efSmrg* Cpp: (cpp). The GNU C preprocessor. 5410d565efSmrg@end direntry 5510d565efSmrg@end ifinfo 5610d565efSmrg 5710d565efSmrg@titlepage 5810d565efSmrg@title The C Preprocessor 5910d565efSmrg@versionsubtitle 6010d565efSmrg@author Richard M. Stallman, Zachary Weinberg 6110d565efSmrg@page 6210d565efSmrg@c There is a fill at the bottom of the page, so we need a filll to 6310d565efSmrg@c override it. 6410d565efSmrg@vskip 0pt plus 1filll 6510d565efSmrg@insertcopying 6610d565efSmrg@end titlepage 6710d565efSmrg@contents 6810d565efSmrg@page 6910d565efSmrg 7010d565efSmrg@ifnottex 7110d565efSmrg@node Top 7210d565efSmrg@top 7310d565efSmrgThe C preprocessor implements the macro language used to transform C, 7410d565efSmrgC++, and Objective-C programs before they are compiled. It can also be 7510d565efSmrguseful on its own. 7610d565efSmrg 7710d565efSmrg@menu 7810d565efSmrg* Overview:: 7910d565efSmrg* Header Files:: 8010d565efSmrg* Macros:: 8110d565efSmrg* Conditionals:: 8210d565efSmrg* Diagnostics:: 8310d565efSmrg* Line Control:: 8410d565efSmrg* Pragmas:: 8510d565efSmrg* Other Directives:: 8610d565efSmrg* Preprocessor Output:: 8710d565efSmrg* Traditional Mode:: 8810d565efSmrg* Implementation Details:: 8910d565efSmrg* Invocation:: 9010d565efSmrg* Environment Variables:: 9110d565efSmrg* GNU Free Documentation License:: 9210d565efSmrg* Index of Directives:: 9310d565efSmrg* Option Index:: 9410d565efSmrg* Concept Index:: 9510d565efSmrg 9610d565efSmrg@detailmenu 9710d565efSmrg --- The Detailed Node Listing --- 9810d565efSmrg 9910d565efSmrgOverview 10010d565efSmrg 10110d565efSmrg* Character sets:: 10210d565efSmrg* Initial processing:: 10310d565efSmrg* Tokenization:: 10410d565efSmrg* The preprocessing language:: 10510d565efSmrg 10610d565efSmrgHeader Files 10710d565efSmrg 10810d565efSmrg* Include Syntax:: 10910d565efSmrg* Include Operation:: 11010d565efSmrg* Search Path:: 11110d565efSmrg* Once-Only Headers:: 11210d565efSmrg* Alternatives to Wrapper #ifndef:: 11310d565efSmrg* Computed Includes:: 11410d565efSmrg* Wrapper Headers:: 11510d565efSmrg* System Headers:: 11610d565efSmrg 11710d565efSmrgMacros 11810d565efSmrg 11910d565efSmrg* Object-like Macros:: 12010d565efSmrg* Function-like Macros:: 12110d565efSmrg* Macro Arguments:: 12210d565efSmrg* Stringizing:: 12310d565efSmrg* Concatenation:: 12410d565efSmrg* Variadic Macros:: 12510d565efSmrg* Predefined Macros:: 12610d565efSmrg* Undefining and Redefining Macros:: 12710d565efSmrg* Directives Within Macro Arguments:: 12810d565efSmrg* Macro Pitfalls:: 12910d565efSmrg 13010d565efSmrgPredefined Macros 13110d565efSmrg 13210d565efSmrg* Standard Predefined Macros:: 13310d565efSmrg* Common Predefined Macros:: 13410d565efSmrg* System-specific Predefined Macros:: 13510d565efSmrg* C++ Named Operators:: 13610d565efSmrg 13710d565efSmrgMacro Pitfalls 13810d565efSmrg 13910d565efSmrg* Misnesting:: 14010d565efSmrg* Operator Precedence Problems:: 14110d565efSmrg* Swallowing the Semicolon:: 14210d565efSmrg* Duplication of Side Effects:: 14310d565efSmrg* Self-Referential Macros:: 14410d565efSmrg* Argument Prescan:: 14510d565efSmrg* Newlines in Arguments:: 14610d565efSmrg 14710d565efSmrgConditionals 14810d565efSmrg 14910d565efSmrg* Conditional Uses:: 15010d565efSmrg* Conditional Syntax:: 15110d565efSmrg* Deleted Code:: 15210d565efSmrg 15310d565efSmrgConditional Syntax 15410d565efSmrg 15510d565efSmrg* Ifdef:: 15610d565efSmrg* If:: 15710d565efSmrg* Defined:: 15810d565efSmrg* Else:: 15910d565efSmrg* Elif:: 16010d565efSmrg 16110d565efSmrgImplementation Details 16210d565efSmrg 16310d565efSmrg* Implementation-defined behavior:: 16410d565efSmrg* Implementation limits:: 16510d565efSmrg* Obsolete Features:: 16610d565efSmrg 16710d565efSmrgObsolete Features 16810d565efSmrg 16910d565efSmrg* Obsolete Features:: 17010d565efSmrg 17110d565efSmrg@end detailmenu 17210d565efSmrg@end menu 17310d565efSmrg 17410d565efSmrg@insertcopying 17510d565efSmrg@end ifnottex 17610d565efSmrg 17710d565efSmrg@node Overview 17810d565efSmrg@chapter Overview 17910d565efSmrg@c man begin DESCRIPTION 18010d565efSmrgThe C preprocessor, often known as @dfn{cpp}, is a @dfn{macro processor} 18110d565efSmrgthat is used automatically by the C compiler to transform your program 18210d565efSmrgbefore compilation. It is called a macro processor because it allows 18310d565efSmrgyou to define @dfn{macros}, which are brief abbreviations for longer 18410d565efSmrgconstructs. 18510d565efSmrg 18610d565efSmrgThe C preprocessor is intended to be used only with C, C++, and 18710d565efSmrgObjective-C source code. In the past, it has been abused as a general 18810d565efSmrgtext processor. It will choke on input which does not obey C's lexical 18910d565efSmrgrules. For example, apostrophes will be interpreted as the beginning of 19010d565efSmrgcharacter constants, and cause errors. Also, you cannot rely on it 19110d565efSmrgpreserving characteristics of the input which are not significant to 19210d565efSmrgC-family languages. If a Makefile is preprocessed, all the hard tabs 19310d565efSmrgwill be removed, and the Makefile will not work. 19410d565efSmrg 19510d565efSmrgHaving said that, you can often get away with using cpp on things which 19610d565efSmrgare not C@. Other Algol-ish programming languages are often safe 1970fc04c29Smrg(Ada, etc.) So is assembly, with caution. @option{-traditional-cpp} 19810d565efSmrgmode preserves more white space, and is otherwise more permissive. Many 19910d565efSmrgof the problems can be avoided by writing C or C++ style comments 20010d565efSmrginstead of native language comments, and keeping macros simple. 20110d565efSmrg 20210d565efSmrgWherever possible, you should use a preprocessor geared to the language 20310d565efSmrgyou are writing in. Modern versions of the GNU assembler have macro 20410d565efSmrgfacilities. Most high level programming languages have their own 20510d565efSmrgconditional compilation and inclusion mechanism. If all else fails, 20610d565efSmrgtry a true general text processor, such as GNU M4. 20710d565efSmrg 20810d565efSmrgC preprocessors vary in some details. This manual discusses the GNU C 20910d565efSmrgpreprocessor, which provides a small superset of the features of ISO 21010d565efSmrgStandard C@. In its default mode, the GNU C preprocessor does not do a 21110d565efSmrgfew things required by the standard. These are features which are 21210d565efSmrgrarely, if ever, used, and may cause surprising changes to the meaning 21310d565efSmrgof a program which does not expect them. To get strict ISO Standard C, 214c7a68eb7Smrgyou should use the @option{-std=c90}, @option{-std=c99}, 215c7a68eb7Smrg@option{-std=c11} or @option{-std=c17} options, depending 21610d565efSmrgon which version of the standard you want. To get all the mandatory 21710d565efSmrgdiagnostics, you must also use @option{-pedantic}. @xref{Invocation}. 21810d565efSmrg 21910d565efSmrgThis manual describes the behavior of the ISO preprocessor. To 22010d565efSmrgminimize gratuitous differences, where the ISO preprocessor's 22110d565efSmrgbehavior does not conflict with traditional semantics, the 22210d565efSmrgtraditional preprocessor should behave the same way. The various 22310d565efSmrgdifferences that do exist are detailed in the section @ref{Traditional 22410d565efSmrgMode}. 22510d565efSmrg 22610d565efSmrgFor clarity, unless noted otherwise, references to @samp{CPP} in this 22710d565efSmrgmanual refer to GNU CPP@. 22810d565efSmrg@c man end 22910d565efSmrg 23010d565efSmrg@menu 23110d565efSmrg* Character sets:: 23210d565efSmrg* Initial processing:: 23310d565efSmrg* Tokenization:: 23410d565efSmrg* The preprocessing language:: 23510d565efSmrg@end menu 23610d565efSmrg 23710d565efSmrg@node Character sets 23810d565efSmrg@section Character sets 23910d565efSmrg 24010d565efSmrgSource code character set processing in C and related languages is 24110d565efSmrgrather complicated. The C standard discusses two character sets, but 24210d565efSmrgthere are really at least four. 24310d565efSmrg 24410d565efSmrgThe files input to CPP might be in any character set at all. CPP's 24510d565efSmrgvery first action, before it even looks for line boundaries, is to 24610d565efSmrgconvert the file into the character set it uses for internal 24710d565efSmrgprocessing. That set is what the C standard calls the @dfn{source} 24810d565efSmrgcharacter set. It must be isomorphic with ISO 10646, also known as 24910d565efSmrgUnicode. CPP uses the UTF-8 encoding of Unicode. 25010d565efSmrg 25110d565efSmrgThe character sets of the input files are specified using the 25210d565efSmrg@option{-finput-charset=} option. 25310d565efSmrg 25410d565efSmrgAll preprocessing work (the subject of the rest of this manual) is 25510d565efSmrgcarried out in the source character set. If you request textual 25610d565efSmrgoutput from the preprocessor with the @option{-E} option, it will be 25710d565efSmrgin UTF-8. 25810d565efSmrg 25910d565efSmrgAfter preprocessing is complete, string and character constants are 26010d565efSmrgconverted again, into the @dfn{execution} character set. This 26110d565efSmrgcharacter set is under control of the user; the default is UTF-8, 26210d565efSmrgmatching the source character set. Wide string and character 26310d565efSmrgconstants have their own character set, which is not called out 26410d565efSmrgspecifically in the standard. Again, it is under control of the user. 26510d565efSmrgThe default is UTF-16 or UTF-32, whichever fits in the target's 26610d565efSmrg@code{wchar_t} type, in the target machine's byte 26710d565efSmrgorder.@footnote{UTF-16 does not meet the requirements of the C 26810d565efSmrgstandard for a wide character set, but the choice of 16-bit 26910d565efSmrg@code{wchar_t} is enshrined in some system ABIs so we cannot fix 27010d565efSmrgthis.} Octal and hexadecimal escape sequences do not undergo 27110d565efSmrgconversion; @t{'\x12'} has the value 0x12 regardless of the currently 27210d565efSmrgselected execution character set. All other escapes are replaced by 27310d565efSmrgthe character in the source character set that they represent, then 27410d565efSmrgconverted to the execution character set, just like unescaped 27510d565efSmrgcharacters. 27610d565efSmrg 277*ec02198aSmrgIn identifiers, characters outside the ASCII range can be specified 278*ec02198aSmrgwith the @samp{\u} and @samp{\U} escapes or used directly in the input 279*ec02198aSmrgencoding. If strict ISO C90 conformance is specified with an option 28010d565efSmrgsuch as @option{-std=c90}, or @option{-fno-extended-identifiers} is 281*ec02198aSmrgused, then those constructs are not permitted in identifiers. 28210d565efSmrg 28310d565efSmrg@node Initial processing 28410d565efSmrg@section Initial processing 28510d565efSmrg 28610d565efSmrgThe preprocessor performs a series of textual transformations on its 28710d565efSmrginput. These happen before all other processing. Conceptually, they 28810d565efSmrghappen in a rigid order, and the entire file is run through each 28910d565efSmrgtransformation before the next one begins. CPP actually does them 29010d565efSmrgall at once, for performance reasons. These transformations correspond 29110d565efSmrgroughly to the first three ``phases of translation'' described in the C 29210d565efSmrgstandard. 29310d565efSmrg 29410d565efSmrg@enumerate 29510d565efSmrg@item 29610d565efSmrg@cindex line endings 29710d565efSmrgThe input file is read into memory and broken into lines. 29810d565efSmrg 29910d565efSmrgDifferent systems use different conventions to indicate the end of a 30010d565efSmrgline. GCC accepts the ASCII control sequences @kbd{LF}, @kbd{@w{CR 30110d565efSmrgLF}} and @kbd{CR} as end-of-line markers. These are the canonical 30210d565efSmrgsequences used by Unix, DOS and VMS, and the classic Mac OS (before 30310d565efSmrgOSX) respectively. You may therefore safely copy source code written 30410d565efSmrgon any of those systems to a different one and use it without 30510d565efSmrgconversion. (GCC may lose track of the current line number if a file 30610d565efSmrgdoesn't consistently use one convention, as sometimes happens when it 30710d565efSmrgis edited on computers with different conventions that share a network 30810d565efSmrgfile system.) 30910d565efSmrg 31010d565efSmrgIf the last line of any input file lacks an end-of-line marker, the end 31110d565efSmrgof the file is considered to implicitly supply one. The C standard says 31210d565efSmrgthat this condition provokes undefined behavior, so GCC will emit a 31310d565efSmrgwarning message. 31410d565efSmrg 31510d565efSmrg@item 31610d565efSmrg@cindex trigraphs 31710d565efSmrg@anchor{trigraphs}If trigraphs are enabled, they are replaced by their 31810d565efSmrgcorresponding single characters. By default GCC ignores trigraphs, 31910d565efSmrgbut if you request a strictly conforming mode with the @option{-std} 32010d565efSmrgoption, or you specify the @option{-trigraphs} option, then it 32110d565efSmrgconverts them. 32210d565efSmrg 32310d565efSmrgThese are nine three-character sequences, all starting with @samp{??}, 32410d565efSmrgthat are defined by ISO C to stand for single characters. They permit 32510d565efSmrgobsolete systems that lack some of C's punctuation to use C@. For 32610d565efSmrgexample, @samp{??/} stands for @samp{\}, so @t{'??/n'} is a character 32710d565efSmrgconstant for a newline. 32810d565efSmrg 32910d565efSmrgTrigraphs are not popular and many compilers implement them 33010d565efSmrgincorrectly. Portable code should not rely on trigraphs being either 33110d565efSmrgconverted or ignored. With @option{-Wtrigraphs} GCC will warn you 33210d565efSmrgwhen a trigraph may change the meaning of your program if it were 33310d565efSmrgconverted. @xref{Wtrigraphs}. 33410d565efSmrg 33510d565efSmrgIn a string constant, you can prevent a sequence of question marks 33610d565efSmrgfrom being confused with a trigraph by inserting a backslash between 33710d565efSmrgthe question marks, or by separating the string literal at the 33810d565efSmrgtrigraph and making use of string literal concatenation. @t{"(??\?)"} 33910d565efSmrgis the string @samp{(???)}, not @samp{(?]}. Traditional C compilers 34010d565efSmrgdo not recognize these idioms. 34110d565efSmrg 34210d565efSmrgThe nine trigraphs and their replacements are 34310d565efSmrg 34410d565efSmrg@smallexample 34510d565efSmrgTrigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??- 34610d565efSmrgReplacement: [ ] @{ @} # \ ^ | ~ 34710d565efSmrg@end smallexample 34810d565efSmrg 34910d565efSmrg@item 35010d565efSmrg@cindex continued lines 35110d565efSmrg@cindex backslash-newline 35210d565efSmrgContinued lines are merged into one long line. 35310d565efSmrg 35410d565efSmrgA continued line is a line which ends with a backslash, @samp{\}. The 35510d565efSmrgbackslash is removed and the following line is joined with the current 35610d565efSmrgone. No space is inserted, so you may split a line anywhere, even in 35710d565efSmrgthe middle of a word. (It is generally more readable to split lines 35810d565efSmrgonly at white space.) 35910d565efSmrg 36010d565efSmrgThe trailing backslash on a continued line is commonly referred to as a 36110d565efSmrg@dfn{backslash-newline}. 36210d565efSmrg 36310d565efSmrgIf there is white space between a backslash and the end of a line, that 36410d565efSmrgis still a continued line. However, as this is usually the result of an 36510d565efSmrgediting mistake, and many compilers will not accept it as a continued 36610d565efSmrgline, GCC will warn you about it. 36710d565efSmrg 36810d565efSmrg@item 36910d565efSmrg@cindex comments 37010d565efSmrg@cindex line comments 37110d565efSmrg@cindex block comments 37210d565efSmrgAll comments are replaced with single spaces. 37310d565efSmrg 37410d565efSmrgThere are two kinds of comments. @dfn{Block comments} begin with 37510d565efSmrg@samp{/*} and continue until the next @samp{*/}. Block comments do not 37610d565efSmrgnest: 37710d565efSmrg 37810d565efSmrg@smallexample 37910d565efSmrg/* @r{this is} /* @r{one comment} */ @r{text outside comment} 38010d565efSmrg@end smallexample 38110d565efSmrg 38210d565efSmrg@dfn{Line comments} begin with @samp{//} and continue to the end of the 38310d565efSmrgcurrent line. Line comments do not nest either, but it does not matter, 38410d565efSmrgbecause they would end in the same place anyway. 38510d565efSmrg 38610d565efSmrg@smallexample 38710d565efSmrg// @r{this is} // @r{one comment} 38810d565efSmrg@r{text outside comment} 38910d565efSmrg@end smallexample 39010d565efSmrg@end enumerate 39110d565efSmrg 39210d565efSmrgIt is safe to put line comments inside block comments, or vice versa. 39310d565efSmrg 39410d565efSmrg@smallexample 39510d565efSmrg@group 39610d565efSmrg/* @r{block comment} 39710d565efSmrg // @r{contains line comment} 39810d565efSmrg @r{yet more comment} 39910d565efSmrg */ @r{outside comment} 40010d565efSmrg 40110d565efSmrg// @r{line comment} /* @r{contains block comment} */ 40210d565efSmrg@end group 40310d565efSmrg@end smallexample 40410d565efSmrg 40510d565efSmrgBut beware of commenting out one end of a block comment with a line 40610d565efSmrgcomment. 40710d565efSmrg 40810d565efSmrg@smallexample 40910d565efSmrg@group 41010d565efSmrg // @r{l.c.} /* @r{block comment begins} 41110d565efSmrg @r{oops! this isn't a comment anymore} */ 41210d565efSmrg@end group 41310d565efSmrg@end smallexample 41410d565efSmrg 41510d565efSmrgComments are not recognized within string literals. 41610d565efSmrg@t{@w{"/* blah */"}} is the string constant @samp{@w{/* blah */}}, not 41710d565efSmrgan empty string. 41810d565efSmrg 41910d565efSmrgLine comments are not in the 1989 edition of the C standard, but they 42010d565efSmrgare recognized by GCC as an extension. In C++ and in the 1999 edition 42110d565efSmrgof the C standard, they are an official part of the language. 42210d565efSmrg 42310d565efSmrgSince these transformations happen before all other processing, you can 42410d565efSmrgsplit a line mechanically with backslash-newline anywhere. You can 42510d565efSmrgcomment out the end of a line. You can continue a line comment onto the 42610d565efSmrgnext line with backslash-newline. You can even split @samp{/*}, 42710d565efSmrg@samp{*/}, and @samp{//} onto multiple lines with backslash-newline. 42810d565efSmrgFor example: 42910d565efSmrg 43010d565efSmrg@smallexample 43110d565efSmrg@group 43210d565efSmrg/\ 43310d565efSmrg* 43410d565efSmrg*/ # /* 43510d565efSmrg*/ defi\ 43610d565efSmrgne FO\ 43710d565efSmrgO 10\ 43810d565efSmrg20 43910d565efSmrg@end group 44010d565efSmrg@end smallexample 44110d565efSmrg 44210d565efSmrg@noindent 44310d565efSmrgis equivalent to @code{@w{#define FOO 1020}}. All these tricks are 44410d565efSmrgextremely confusing and should not be used in code intended to be 44510d565efSmrgreadable. 44610d565efSmrg 44710d565efSmrgThere is no way to prevent a backslash at the end of a line from being 44810d565efSmrginterpreted as a backslash-newline. This cannot affect any correct 44910d565efSmrgprogram, however. 45010d565efSmrg 45110d565efSmrg@node Tokenization 45210d565efSmrg@section Tokenization 45310d565efSmrg 45410d565efSmrg@cindex tokens 45510d565efSmrg@cindex preprocessing tokens 45610d565efSmrgAfter the textual transformations are finished, the input file is 45710d565efSmrgconverted into a sequence of @dfn{preprocessing tokens}. These mostly 45810d565efSmrgcorrespond to the syntactic tokens used by the C compiler, but there are 45910d565efSmrga few differences. White space separates tokens; it is not itself a 46010d565efSmrgtoken of any kind. Tokens do not have to be separated by white space, 46110d565efSmrgbut it is often necessary to avoid ambiguities. 46210d565efSmrg 46310d565efSmrgWhen faced with a sequence of characters that has more than one possible 46410d565efSmrgtokenization, the preprocessor is greedy. It always makes each token, 46510d565efSmrgstarting from the left, as big as possible before moving on to the next 46610d565efSmrgtoken. For instance, @code{a+++++b} is interpreted as 46710d565efSmrg@code{@w{a ++ ++ + b}}, not as @code{@w{a ++ + ++ b}}, even though the 46810d565efSmrglatter tokenization could be part of a valid C program and the former 46910d565efSmrgcould not. 47010d565efSmrg 47110d565efSmrgOnce the input file is broken into tokens, the token boundaries never 47210d565efSmrgchange, except when the @samp{##} preprocessing operator is used to paste 47310d565efSmrgtokens together. @xref{Concatenation}. For example, 47410d565efSmrg 47510d565efSmrg@smallexample 47610d565efSmrg@group 47710d565efSmrg#define foo() bar 47810d565efSmrgfoo()baz 47910d565efSmrg @expansion{} bar baz 48010d565efSmrg@emph{not} 48110d565efSmrg @expansion{} barbaz 48210d565efSmrg@end group 48310d565efSmrg@end smallexample 48410d565efSmrg 48510d565efSmrgThe compiler does not re-tokenize the preprocessor's output. Each 48610d565efSmrgpreprocessing token becomes one compiler token. 48710d565efSmrg 48810d565efSmrg@cindex identifiers 48910d565efSmrgPreprocessing tokens fall into five broad classes: identifiers, 49010d565efSmrgpreprocessing numbers, string literals, punctuators, and other. An 49110d565efSmrg@dfn{identifier} is the same as an identifier in C: any sequence of 49210d565efSmrgletters, digits, or underscores, which begins with a letter or 49310d565efSmrgunderscore. Keywords of C have no significance to the preprocessor; 49410d565efSmrgthey are ordinary identifiers. You can define a macro whose name is a 49510d565efSmrgkeyword, for instance. The only identifier which can be considered a 49610d565efSmrgpreprocessing keyword is @code{defined}. @xref{Defined}. 49710d565efSmrg 49810d565efSmrgThis is mostly true of other languages which use the C preprocessor. 49910d565efSmrgHowever, a few of the keywords of C++ are significant even in the 50010d565efSmrgpreprocessor. @xref{C++ Named Operators}. 50110d565efSmrg 50210d565efSmrgIn the 1999 C standard, identifiers may contain letters which are not 50310d565efSmrgpart of the ``basic source character set'', at the implementation's 50410d565efSmrgdiscretion (such as accented Latin letters, Greek letters, or Chinese 50510d565efSmrgideograms). This may be done with an extended character set, or the 506*ec02198aSmrg@samp{\u} and @samp{\U} escape sequences. 50710d565efSmrg 50810d565efSmrgAs an extension, GCC treats @samp{$} as a letter. This is for 50910d565efSmrgcompatibility with some systems, such as VMS, where @samp{$} is commonly 51010d565efSmrgused in system-defined function and object names. @samp{$} is not a 51110d565efSmrgletter in strictly conforming mode, or if you specify the @option{-$} 51210d565efSmrgoption. @xref{Invocation}. 51310d565efSmrg 51410d565efSmrg@cindex numbers 51510d565efSmrg@cindex preprocessing numbers 51610d565efSmrgA @dfn{preprocessing number} has a rather bizarre definition. The 51710d565efSmrgcategory includes all the normal integer and floating point constants 51810d565efSmrgone expects of C, but also a number of other things one might not 51910d565efSmrginitially recognize as a number. Formally, preprocessing numbers begin 52010d565efSmrgwith an optional period, a required decimal digit, and then continue 52110d565efSmrgwith any sequence of letters, digits, underscores, periods, and 52210d565efSmrgexponents. Exponents are the two-character sequences @samp{e+}, 52310d565efSmrg@samp{e-}, @samp{E+}, @samp{E-}, @samp{p+}, @samp{p-}, @samp{P+}, and 52410d565efSmrg@samp{P-}. (The exponents that begin with @samp{p} or @samp{P} are 52510d565efSmrgused for hexadecimal floating-point constants.) 52610d565efSmrg 52710d565efSmrgThe purpose of this unusual definition is to isolate the preprocessor 52810d565efSmrgfrom the full complexity of numeric constants. It does not have to 52910d565efSmrgdistinguish between lexically valid and invalid floating-point numbers, 53010d565efSmrgwhich is complicated. The definition also permits you to split an 53110d565efSmrgidentifier at any position and get exactly two tokens, which can then be 53210d565efSmrgpasted back together with the @samp{##} operator. 53310d565efSmrg 53410d565efSmrgIt's possible for preprocessing numbers to cause programs to be 53510d565efSmrgmisinterpreted. For example, @code{0xE+12} is a preprocessing number 53610d565efSmrgwhich does not translate to any valid numeric constant, therefore a 53710d565efSmrgsyntax error. It does not mean @code{@w{0xE + 12}}, which is what you 53810d565efSmrgmight have intended. 53910d565efSmrg 54010d565efSmrg@cindex string literals 54110d565efSmrg@cindex string constants 54210d565efSmrg@cindex character constants 54310d565efSmrg@cindex header file names 54410d565efSmrg@c the @: prevents makeinfo from turning '' into ". 54510d565efSmrg@dfn{String literals} are string constants, character constants, and 54610d565efSmrgheader file names (the argument of @samp{#include}).@footnote{The C 54710d565efSmrgstandard uses the term @dfn{string literal} to refer only to what we are 54810d565efSmrgcalling @dfn{string constants}.} String constants and character 54910d565efSmrgconstants are straightforward: @t{"@dots{}"} or @t{'@dots{}'}. In 55010d565efSmrgeither case embedded quotes should be escaped with a backslash: 55110d565efSmrg@t{'\'@:'} is the character constant for @samp{'}. There is no limit on 55210d565efSmrgthe length of a character constant, but the value of a character 55310d565efSmrgconstant that contains more than one character is 55410d565efSmrgimplementation-defined. @xref{Implementation Details}. 55510d565efSmrg 55610d565efSmrgHeader file names either look like string constants, @t{"@dots{}"}, or are 55710d565efSmrgwritten with angle brackets instead, @t{<@dots{}>}. In either case, 55810d565efSmrgbackslash is an ordinary character. There is no way to escape the 55910d565efSmrgclosing quote or angle bracket. The preprocessor looks for the header 56010d565efSmrgfile in different places depending on which form you use. @xref{Include 56110d565efSmrgOperation}. 56210d565efSmrg 56310d565efSmrgNo string literal may extend past the end of a line. You may use continued 56410d565efSmrglines instead, or string constant concatenation. 56510d565efSmrg 56610d565efSmrg@cindex punctuators 56710d565efSmrg@cindex digraphs 56810d565efSmrg@cindex alternative tokens 56910d565efSmrg@dfn{Punctuators} are all the usual bits of punctuation which are 57010d565efSmrgmeaningful to C and C++. All but three of the punctuation characters in 57110d565efSmrgASCII are C punctuators. The exceptions are @samp{@@}, @samp{$}, and 57210d565efSmrg@samp{`}. In addition, all the two- and three-character operators are 57310d565efSmrgpunctuators. There are also six @dfn{digraphs}, which the C++ standard 57410d565efSmrgcalls @dfn{alternative tokens}, which are merely alternate ways to spell 57510d565efSmrgother punctuators. This is a second attempt to work around missing 57610d565efSmrgpunctuation in obsolete systems. It has no negative side effects, 57710d565efSmrgunlike trigraphs, but does not cover as much ground. The digraphs and 57810d565efSmrgtheir corresponding normal punctuators are: 57910d565efSmrg 58010d565efSmrg@smallexample 58110d565efSmrgDigraph: <% %> <: :> %: %:%: 58210d565efSmrgPunctuator: @{ @} [ ] # ## 58310d565efSmrg@end smallexample 58410d565efSmrg 58510d565efSmrg@cindex other tokens 586*ec02198aSmrgAny other single byte is considered ``other'' and passed on to the 587*ec02198aSmrgpreprocessor's output unchanged. The C compiler will almost certainly 588*ec02198aSmrgreject source code containing ``other'' tokens. In ASCII, the only 589*ec02198aSmrg``other'' characters are @samp{@@}, @samp{$}, @samp{`}, and control 59010d565efSmrgcharacters other than NUL (all bits zero). (Note that @samp{$} is 591*ec02198aSmrgnormally considered a letter.) All bytes with the high bit set 592*ec02198aSmrg(numeric range 0x7F--0xFF) that were not succesfully interpreted as 593*ec02198aSmrgpart of an extended character in the input encoding are also ``other'' 594*ec02198aSmrgin the present implementation. 59510d565efSmrg 59610d565efSmrgNUL is a special case because of the high probability that its 59710d565efSmrgappearance is accidental, and because it may be invisible to the user 59810d565efSmrg(many terminals do not display NUL at all). Within comments, NULs are 59910d565efSmrgsilently ignored, just as any other character would be. In running 60010d565efSmrgtext, NUL is considered white space. For example, these two directives 60110d565efSmrghave the same meaning. 60210d565efSmrg 60310d565efSmrg@smallexample 60410d565efSmrg#define X^@@1 60510d565efSmrg#define X 1 60610d565efSmrg@end smallexample 60710d565efSmrg 60810d565efSmrg@noindent 60910d565efSmrg(where @samp{^@@} is ASCII NUL)@. Within string or character constants, 61010d565efSmrgNULs are preserved. In the latter two cases the preprocessor emits a 61110d565efSmrgwarning message. 61210d565efSmrg 61310d565efSmrg@node The preprocessing language 61410d565efSmrg@section The preprocessing language 61510d565efSmrg@cindex directives 61610d565efSmrg@cindex preprocessing directives 61710d565efSmrg@cindex directive line 61810d565efSmrg@cindex directive name 61910d565efSmrg 62010d565efSmrgAfter tokenization, the stream of tokens may simply be passed straight 62110d565efSmrgto the compiler's parser. However, if it contains any operations in the 62210d565efSmrg@dfn{preprocessing language}, it will be transformed first. This stage 62310d565efSmrgcorresponds roughly to the standard's ``translation phase 4'' and is 62410d565efSmrgwhat most people think of as the preprocessor's job. 62510d565efSmrg 62610d565efSmrgThe preprocessing language consists of @dfn{directives} to be executed 62710d565efSmrgand @dfn{macros} to be expanded. Its primary capabilities are: 62810d565efSmrg 62910d565efSmrg@itemize @bullet 63010d565efSmrg@item 63110d565efSmrgInclusion of header files. These are files of declarations that can be 63210d565efSmrgsubstituted into your program. 63310d565efSmrg 63410d565efSmrg@item 63510d565efSmrgMacro expansion. You can define @dfn{macros}, which are abbreviations 63610d565efSmrgfor arbitrary fragments of C code. The preprocessor will replace the 63710d565efSmrgmacros with their definitions throughout the program. Some macros are 63810d565efSmrgautomatically defined for you. 63910d565efSmrg 64010d565efSmrg@item 64110d565efSmrgConditional compilation. You can include or exclude parts of the 64210d565efSmrgprogram according to various conditions. 64310d565efSmrg 64410d565efSmrg@item 64510d565efSmrgLine control. If you use a program to combine or rearrange source files 64610d565efSmrginto an intermediate file which is then compiled, you can use line 64710d565efSmrgcontrol to inform the compiler where each source line originally came 64810d565efSmrgfrom. 64910d565efSmrg 65010d565efSmrg@item 65110d565efSmrgDiagnostics. You can detect problems at compile time and issue errors 65210d565efSmrgor warnings. 65310d565efSmrg@end itemize 65410d565efSmrg 65510d565efSmrgThere are a few more, less useful, features. 65610d565efSmrg 65710d565efSmrgExcept for expansion of predefined macros, all these operations are 65810d565efSmrgtriggered with @dfn{preprocessing directives}. Preprocessing directives 65910d565efSmrgare lines in your program that start with @samp{#}. Whitespace is 66010d565efSmrgallowed before and after the @samp{#}. The @samp{#} is followed by an 66110d565efSmrgidentifier, the @dfn{directive name}. It specifies the operation to 66210d565efSmrgperform. Directives are commonly referred to as @samp{#@var{name}} 66310d565efSmrgwhere @var{name} is the directive name. For example, @samp{#define} is 66410d565efSmrgthe directive that defines a macro. 66510d565efSmrg 66610d565efSmrgThe @samp{#} which begins a directive cannot come from a macro 66710d565efSmrgexpansion. Also, the directive name is not macro expanded. Thus, if 66810d565efSmrg@code{foo} is defined as a macro expanding to @code{define}, that does 66910d565efSmrgnot make @samp{#foo} a valid preprocessing directive. 67010d565efSmrg 67110d565efSmrgThe set of valid directive names is fixed. Programs cannot define new 67210d565efSmrgpreprocessing directives. 67310d565efSmrg 67410d565efSmrgSome directives require arguments; these make up the rest of the 67510d565efSmrgdirective line and must be separated from the directive name by 67610d565efSmrgwhitespace. For example, @samp{#define} must be followed by a macro 67710d565efSmrgname and the intended expansion of the macro. 67810d565efSmrg 67910d565efSmrgA preprocessing directive cannot cover more than one line. The line 68010d565efSmrgmay, however, be continued with backslash-newline, or by a block comment 68110d565efSmrgwhich extends past the end of the line. In either case, when the 68210d565efSmrgdirective is processed, the continuations have already been merged with 68310d565efSmrgthe first line to make one long line. 68410d565efSmrg 68510d565efSmrg@node Header Files 68610d565efSmrg@chapter Header Files 68710d565efSmrg 68810d565efSmrg@cindex header file 68910d565efSmrgA header file is a file containing C declarations and macro definitions 69010d565efSmrg(@pxref{Macros}) to be shared between several source files. You request 69110d565efSmrgthe use of a header file in your program by @dfn{including} it, with the 69210d565efSmrgC preprocessing directive @samp{#include}. 69310d565efSmrg 69410d565efSmrgHeader files serve two purposes. 69510d565efSmrg 69610d565efSmrg@itemize @bullet 69710d565efSmrg@item 69810d565efSmrg@cindex system header files 69910d565efSmrgSystem header files declare the interfaces to parts of the operating 70010d565efSmrgsystem. You include them in your program to supply the definitions and 70110d565efSmrgdeclarations you need to invoke system calls and libraries. 70210d565efSmrg 70310d565efSmrg@item 70410d565efSmrgYour own header files contain declarations for interfaces between the 70510d565efSmrgsource files of your program. Each time you have a group of related 70610d565efSmrgdeclarations and macro definitions all or most of which are needed in 70710d565efSmrgseveral different source files, it is a good idea to create a header 70810d565efSmrgfile for them. 70910d565efSmrg@end itemize 71010d565efSmrg 71110d565efSmrgIncluding a header file produces the same results as copying the header 71210d565efSmrgfile into each source file that needs it. Such copying would be 71310d565efSmrgtime-consuming and error-prone. With a header file, the related 71410d565efSmrgdeclarations appear in only one place. If they need to be changed, they 71510d565efSmrgcan be changed in one place, and programs that include the header file 71610d565efSmrgwill automatically use the new version when next recompiled. The header 71710d565efSmrgfile eliminates the labor of finding and changing all the copies as well 71810d565efSmrgas the risk that a failure to find one copy will result in 71910d565efSmrginconsistencies within a program. 72010d565efSmrg 72110d565efSmrgIn C, the usual convention is to give header files names that end with 72210d565efSmrg@file{.h}. It is most portable to use only letters, digits, dashes, and 72310d565efSmrgunderscores in header file names, and at most one dot. 72410d565efSmrg 72510d565efSmrg@menu 72610d565efSmrg* Include Syntax:: 72710d565efSmrg* Include Operation:: 72810d565efSmrg* Search Path:: 72910d565efSmrg* Once-Only Headers:: 73010d565efSmrg* Alternatives to Wrapper #ifndef:: 73110d565efSmrg* Computed Includes:: 73210d565efSmrg* Wrapper Headers:: 73310d565efSmrg* System Headers:: 73410d565efSmrg@end menu 73510d565efSmrg 73610d565efSmrg@node Include Syntax 73710d565efSmrg@section Include Syntax 73810d565efSmrg 73910d565efSmrg@findex #include 74010d565efSmrgBoth user and system header files are included using the preprocessing 74110d565efSmrgdirective @samp{#include}. It has two variants: 74210d565efSmrg 74310d565efSmrg@table @code 74410d565efSmrg@item #include <@var{file}> 74510d565efSmrgThis variant is used for system header files. It searches for a file 74610d565efSmrgnamed @var{file} in a standard list of system directories. You can prepend 74710d565efSmrgdirectories to this list with the @option{-I} option (@pxref{Invocation}). 74810d565efSmrg 74910d565efSmrg@item #include "@var{file}" 75010d565efSmrgThis variant is used for header files of your own program. It 75110d565efSmrgsearches for a file named @var{file} first in the directory containing 75210d565efSmrgthe current file, then in the quote directories and then the same 75310d565efSmrgdirectories used for @code{<@var{file}>}. You can prepend directories 75410d565efSmrgto the list of quote directories with the @option{-iquote} option. 75510d565efSmrg@end table 75610d565efSmrg 75710d565efSmrgThe argument of @samp{#include}, whether delimited with quote marks or 75810d565efSmrgangle brackets, behaves like a string constant in that comments are not 75910d565efSmrgrecognized, and macro names are not expanded. Thus, @code{@w{#include 76010d565efSmrg<x/*y>}} specifies inclusion of a system header file named @file{x/*y}. 76110d565efSmrg 76210d565efSmrgHowever, if backslashes occur within @var{file}, they are considered 76310d565efSmrgordinary text characters, not escape characters. None of the character 76410d565efSmrgescape sequences appropriate to string constants in C are processed. 76510d565efSmrgThus, @code{@w{#include "x\n\\y"}} specifies a filename containing three 76610d565efSmrgbackslashes. (Some systems interpret @samp{\} as a pathname separator. 76710d565efSmrgAll of these also interpret @samp{/} the same way. It is most portable 76810d565efSmrgto use only @samp{/}.) 76910d565efSmrg 77010d565efSmrgIt is an error if there is anything (other than comments) on the line 77110d565efSmrgafter the file name. 77210d565efSmrg 77310d565efSmrg@node Include Operation 77410d565efSmrg@section Include Operation 77510d565efSmrg 77610d565efSmrgThe @samp{#include} directive works by directing the C preprocessor to 77710d565efSmrgscan the specified file as input before continuing with the rest of the 77810d565efSmrgcurrent file. The output from the preprocessor contains the output 77910d565efSmrgalready generated, followed by the output resulting from the included 78010d565efSmrgfile, followed by the output that comes from the text after the 78110d565efSmrg@samp{#include} directive. For example, if you have a header file 78210d565efSmrg@file{header.h} as follows, 78310d565efSmrg 78410d565efSmrg@smallexample 78510d565efSmrgchar *test (void); 78610d565efSmrg@end smallexample 78710d565efSmrg 78810d565efSmrg@noindent 78910d565efSmrgand a main program called @file{program.c} that uses the header file, 79010d565efSmrglike this, 79110d565efSmrg 79210d565efSmrg@smallexample 79310d565efSmrgint x; 79410d565efSmrg#include "header.h" 79510d565efSmrg 79610d565efSmrgint 79710d565efSmrgmain (void) 79810d565efSmrg@{ 79910d565efSmrg puts (test ()); 80010d565efSmrg@} 80110d565efSmrg@end smallexample 80210d565efSmrg 80310d565efSmrg@noindent 80410d565efSmrgthe compiler will see the same token stream as it would if 80510d565efSmrg@file{program.c} read 80610d565efSmrg 80710d565efSmrg@smallexample 80810d565efSmrgint x; 80910d565efSmrgchar *test (void); 81010d565efSmrg 81110d565efSmrgint 81210d565efSmrgmain (void) 81310d565efSmrg@{ 81410d565efSmrg puts (test ()); 81510d565efSmrg@} 81610d565efSmrg@end smallexample 81710d565efSmrg 81810d565efSmrgIncluded files are not limited to declarations and macro definitions; 81910d565efSmrgthose are merely the typical uses. Any fragment of a C program can be 82010d565efSmrgincluded from another file. The include file could even contain the 82110d565efSmrgbeginning of a statement that is concluded in the containing file, or 82210d565efSmrgthe end of a statement that was started in the including file. However, 82310d565efSmrgan included file must consist of complete tokens. Comments and string 82410d565efSmrgliterals which have not been closed by the end of an included file are 82510d565efSmrginvalid. For error recovery, they are considered to end at the end of 82610d565efSmrgthe file. 82710d565efSmrg 82810d565efSmrgTo avoid confusion, it is best if header files contain only complete 82910d565efSmrgsyntactic units---function declarations or definitions, type 83010d565efSmrgdeclarations, etc. 83110d565efSmrg 83210d565efSmrgThe line following the @samp{#include} directive is always treated as a 83310d565efSmrgseparate line by the C preprocessor, even if the included file lacks a 83410d565efSmrgfinal newline. 83510d565efSmrg 83610d565efSmrg@node Search Path 83710d565efSmrg@section Search Path 83810d565efSmrg 83910d565efSmrgBy default, the preprocessor looks for header files included by the quote 84010d565efSmrgform of the directive @code{@w{#include "@var{file}"}} first relative to 84110d565efSmrgthe directory of the current file, and then in a preconfigured list 84210d565efSmrgof standard system directories. 84310d565efSmrgFor example, if @file{/usr/include/sys/stat.h} contains 84410d565efSmrg@code{@w{#include "types.h"}}, GCC looks for @file{types.h} first in 84510d565efSmrg@file{/usr/include/sys}, then in its usual search path. 84610d565efSmrg 84710d565efSmrgFor the angle-bracket form @code{@w{#include <@var{file}>}}, the 84810d565efSmrgpreprocessor's default behavior is to look only in the standard system 84910d565efSmrgdirectories. The exact search directory list depends on the target 85010d565efSmrgsystem, how GCC is configured, and where it is installed. You can 85110d565efSmrgfind the default search directory list for your version of CPP by 85210d565efSmrginvoking it with the @option{-v} option. For example, 85310d565efSmrg 85410d565efSmrg@smallexample 85510d565efSmrgcpp -v /dev/null -o /dev/null 85610d565efSmrg@end smallexample 85710d565efSmrg 85810d565efSmrgThere are a number of command-line options you can use to add 85910d565efSmrgadditional directories to the search path. 86010d565efSmrgThe most commonly-used option is @option{-I@var{dir}}, which causes 86110d565efSmrg@var{dir} to be searched after the current directory (for the quote 86210d565efSmrgform of the directive) and ahead of the standard system directories. 86310d565efSmrgYou can specify multiple @option{-I} options on the command line, 86410d565efSmrgin which case the directories are searched in left-to-right order. 86510d565efSmrg 86610d565efSmrgIf you need separate control over the search paths for the quote and 86710d565efSmrgangle-bracket forms of the @samp{#include} directive, you can use the 86810d565efSmrg@option{-iquote} and/or @option{-isystem} options instead of @option{-I}. 86910d565efSmrg@xref{Invocation}, for a detailed description of these options, as 87010d565efSmrgwell as others that are less generally useful. 87110d565efSmrg 87210d565efSmrgIf you specify other options on the command line, such as @option{-I}, 87310d565efSmrgthat affect where the preprocessor searches for header files, the 87410d565efSmrgdirectory list printed by the @option{-v} option reflects the actual 87510d565efSmrgsearch path used by the preprocessor. 87610d565efSmrg 87710d565efSmrgNote that you can also prevent the preprocessor from searching any of 87810d565efSmrgthe default system header directories with the @option{-nostdinc} 87910d565efSmrgoption. This is useful when you are compiling an operating system 88010d565efSmrgkernel or some other program that does not use the standard C library 88110d565efSmrgfacilities, or the standard C library itself. 88210d565efSmrg 88310d565efSmrg@node Once-Only Headers 88410d565efSmrg@section Once-Only Headers 88510d565efSmrg@cindex repeated inclusion 88610d565efSmrg@cindex including just once 88710d565efSmrg@cindex wrapper @code{#ifndef} 88810d565efSmrg 88910d565efSmrgIf a header file happens to be included twice, the compiler will process 89010d565efSmrgits contents twice. This is very likely to cause an error, e.g.@: when the 89110d565efSmrgcompiler sees the same structure definition twice. Even if it does not, 89210d565efSmrgit will certainly waste time. 89310d565efSmrg 89410d565efSmrgThe standard way to prevent this is to enclose the entire real contents 89510d565efSmrgof the file in a conditional, like this: 89610d565efSmrg 89710d565efSmrg@smallexample 89810d565efSmrg@group 89910d565efSmrg/* File foo. */ 90010d565efSmrg#ifndef FILE_FOO_SEEN 90110d565efSmrg#define FILE_FOO_SEEN 90210d565efSmrg 90310d565efSmrg@var{the entire file} 90410d565efSmrg 90510d565efSmrg#endif /* !FILE_FOO_SEEN */ 90610d565efSmrg@end group 90710d565efSmrg@end smallexample 90810d565efSmrg 90910d565efSmrgThis construct is commonly known as a @dfn{wrapper #ifndef}. 91010d565efSmrgWhen the header is included again, the conditional will be false, 91110d565efSmrgbecause @code{FILE_FOO_SEEN} is defined. The preprocessor will skip 91210d565efSmrgover the entire contents of the file, and the compiler will not see it 91310d565efSmrgtwice. 91410d565efSmrg 91510d565efSmrgCPP optimizes even further. It remembers when a header file has a 91610d565efSmrgwrapper @samp{#ifndef}. If a subsequent @samp{#include} specifies that 91710d565efSmrgheader, and the macro in the @samp{#ifndef} is still defined, it does 91810d565efSmrgnot bother to rescan the file at all. 91910d565efSmrg 92010d565efSmrgYou can put comments outside the wrapper. They will not interfere with 92110d565efSmrgthis optimization. 92210d565efSmrg 92310d565efSmrg@cindex controlling macro 92410d565efSmrg@cindex guard macro 92510d565efSmrgThe macro @code{FILE_FOO_SEEN} is called the @dfn{controlling macro} or 92610d565efSmrg@dfn{guard macro}. In a user header file, the macro name should not 92710d565efSmrgbegin with @samp{_}. In a system header file, it should begin with 92810d565efSmrg@samp{__} to avoid conflicts with user programs. In any kind of header 92910d565efSmrgfile, the macro name should contain the name of the file and some 93010d565efSmrgadditional text, to avoid conflicts with other header files. 93110d565efSmrg 93210d565efSmrg@node Alternatives to Wrapper #ifndef 93310d565efSmrg@section Alternatives to Wrapper #ifndef 93410d565efSmrg 93510d565efSmrgCPP supports two more ways of indicating that a header file should be 93610d565efSmrgread only once. Neither one is as portable as a wrapper @samp{#ifndef} 93710d565efSmrgand we recommend you do not use them in new programs, with the caveat 93810d565efSmrgthat @samp{#import} is standard practice in Objective-C. 93910d565efSmrg 94010d565efSmrg@findex #import 94110d565efSmrgCPP supports a variant of @samp{#include} called @samp{#import} which 94210d565efSmrgincludes a file, but does so at most once. If you use @samp{#import} 94310d565efSmrginstead of @samp{#include}, then you don't need the conditionals 94410d565efSmrginside the header file to prevent multiple inclusion of the contents. 94510d565efSmrg@samp{#import} is standard in Objective-C, but is considered a 94610d565efSmrgdeprecated extension in C and C++. 94710d565efSmrg 94810d565efSmrg@samp{#import} is not a well designed feature. It requires the users of 94910d565efSmrga header file to know that it should only be included once. It is much 95010d565efSmrgbetter for the header file's implementor to write the file so that users 95110d565efSmrgdon't need to know this. Using a wrapper @samp{#ifndef} accomplishes 95210d565efSmrgthis goal. 95310d565efSmrg 95410d565efSmrgIn the present implementation, a single use of @samp{#import} will 95510d565efSmrgprevent the file from ever being read again, by either @samp{#import} or 95610d565efSmrg@samp{#include}. You should not rely on this; do not use both 95710d565efSmrg@samp{#import} and @samp{#include} to refer to the same header file. 95810d565efSmrg 95910d565efSmrgAnother way to prevent a header file from being included more than once 9600fc04c29Smrgis with the @samp{#pragma once} directive (@pxref{Pragmas}). 96110d565efSmrg@samp{#pragma once} does not have the problems that @samp{#import} does, 96210d565efSmrgbut it is not recognized by all preprocessors, so you cannot rely on it 96310d565efSmrgin a portable program. 96410d565efSmrg 96510d565efSmrg@node Computed Includes 96610d565efSmrg@section Computed Includes 96710d565efSmrg@cindex computed includes 96810d565efSmrg@cindex macros in include 96910d565efSmrg 97010d565efSmrgSometimes it is necessary to select one of several different header 97110d565efSmrgfiles to be included into your program. They might specify 97210d565efSmrgconfiguration parameters to be used on different sorts of operating 97310d565efSmrgsystems, for instance. You could do this with a series of conditionals, 97410d565efSmrg 97510d565efSmrg@smallexample 97610d565efSmrg#if SYSTEM_1 97710d565efSmrg# include "system_1.h" 97810d565efSmrg#elif SYSTEM_2 97910d565efSmrg# include "system_2.h" 98010d565efSmrg#elif SYSTEM_3 98110d565efSmrg@dots{} 98210d565efSmrg#endif 98310d565efSmrg@end smallexample 98410d565efSmrg 98510d565efSmrgThat rapidly becomes tedious. Instead, the preprocessor offers the 98610d565efSmrgability to use a macro for the header name. This is called a 98710d565efSmrg@dfn{computed include}. Instead of writing a header name as the direct 98810d565efSmrgargument of @samp{#include}, you simply put a macro name there instead: 98910d565efSmrg 99010d565efSmrg@smallexample 99110d565efSmrg#define SYSTEM_H "system_1.h" 99210d565efSmrg@dots{} 99310d565efSmrg#include SYSTEM_H 99410d565efSmrg@end smallexample 99510d565efSmrg 99610d565efSmrg@noindent 99710d565efSmrg@code{SYSTEM_H} will be expanded, and the preprocessor will look for 99810d565efSmrg@file{system_1.h} as if the @samp{#include} had been written that way 99910d565efSmrgoriginally. @code{SYSTEM_H} could be defined by your Makefile with a 100010d565efSmrg@option{-D} option. 100110d565efSmrg 100210d565efSmrgYou must be careful when you define the macro. @samp{#define} saves 100310d565efSmrgtokens, not text. The preprocessor has no way of knowing that the macro 100410d565efSmrgwill be used as the argument of @samp{#include}, so it generates 100510d565efSmrgordinary tokens, not a header name. This is unlikely to cause problems 100610d565efSmrgif you use double-quote includes, which are close enough to string 100710d565efSmrgconstants. If you use angle brackets, however, you may have trouble. 100810d565efSmrg 100910d565efSmrgThe syntax of a computed include is actually a bit more general than the 101010d565efSmrgabove. If the first non-whitespace character after @samp{#include} is 101110d565efSmrgnot @samp{"} or @samp{<}, then the entire line is macro-expanded 101210d565efSmrglike running text would be. 101310d565efSmrg 101410d565efSmrgIf the line expands to a single string constant, the contents of that 101510d565efSmrgstring constant are the file to be included. CPP does not re-examine the 101610d565efSmrgstring for embedded quotes, but neither does it process backslash 101710d565efSmrgescapes in the string. Therefore 101810d565efSmrg 101910d565efSmrg@smallexample 102010d565efSmrg#define HEADER "a\"b" 102110d565efSmrg#include HEADER 102210d565efSmrg@end smallexample 102310d565efSmrg 102410d565efSmrg@noindent 102510d565efSmrglooks for a file named @file{a\"b}. CPP searches for the file according 102610d565efSmrgto the rules for double-quoted includes. 102710d565efSmrg 102810d565efSmrgIf the line expands to a token stream beginning with a @samp{<} token 102910d565efSmrgand including a @samp{>} token, then the tokens between the @samp{<} and 103010d565efSmrgthe first @samp{>} are combined to form the filename to be included. 103110d565efSmrgAny whitespace between tokens is reduced to a single space; then any 103210d565efSmrgspace after the initial @samp{<} is retained, but a trailing space 103310d565efSmrgbefore the closing @samp{>} is ignored. CPP searches for the file 103410d565efSmrgaccording to the rules for angle-bracket includes. 103510d565efSmrg 103610d565efSmrgIn either case, if there are any tokens on the line after the file name, 103710d565efSmrgan error occurs and the directive is not processed. It is also an error 103810d565efSmrgif the result of expansion does not match either of the two expected 103910d565efSmrgforms. 104010d565efSmrg 104110d565efSmrgThese rules are implementation-defined behavior according to the C 104210d565efSmrgstandard. To minimize the risk of different compilers interpreting your 104310d565efSmrgcomputed includes differently, we recommend you use only a single 104410d565efSmrgobject-like macro which expands to a string constant. This will also 104510d565efSmrgminimize confusion for people reading your program. 104610d565efSmrg 104710d565efSmrg@node Wrapper Headers 104810d565efSmrg@section Wrapper Headers 104910d565efSmrg@cindex wrapper headers 105010d565efSmrg@cindex overriding a header file 105110d565efSmrg@findex #include_next 105210d565efSmrg 105310d565efSmrgSometimes it is necessary to adjust the contents of a system-provided 105410d565efSmrgheader file without editing it directly. GCC's @command{fixincludes} 105510d565efSmrgoperation does this, for example. One way to do that would be to create 105610d565efSmrga new header file with the same name and insert it in the search path 105710d565efSmrgbefore the original header. That works fine as long as you're willing 105810d565efSmrgto replace the old header entirely. But what if you want to refer to 105910d565efSmrgthe old header from the new one? 106010d565efSmrg 106110d565efSmrgYou cannot simply include the old header with @samp{#include}. That 106210d565efSmrgwill start from the beginning, and find your new header again. If your 106310d565efSmrgheader is not protected from multiple inclusion (@pxref{Once-Only 106410d565efSmrgHeaders}), it will recurse infinitely and cause a fatal error. 106510d565efSmrg 106610d565efSmrgYou could include the old header with an absolute pathname: 106710d565efSmrg@smallexample 106810d565efSmrg#include "/usr/include/old-header.h" 106910d565efSmrg@end smallexample 107010d565efSmrg@noindent 107110d565efSmrgThis works, but is not clean; should the system headers ever move, you 107210d565efSmrgwould have to edit the new headers to match. 107310d565efSmrg 107410d565efSmrgThere is no way to solve this problem within the C standard, but you can 107510d565efSmrguse the GNU extension @samp{#include_next}. It means, ``Include the 107610d565efSmrg@emph{next} file with this name''. This directive works like 107710d565efSmrg@samp{#include} except in searching for the specified file: it starts 107810d565efSmrgsearching the list of header file directories @emph{after} the directory 107910d565efSmrgin which the current file was found. 108010d565efSmrg 108110d565efSmrgSuppose you specify @option{-I /usr/local/include}, and the list of 108210d565efSmrgdirectories to search also includes @file{/usr/include}; and suppose 108310d565efSmrgboth directories contain @file{signal.h}. Ordinary @code{@w{#include 108410d565efSmrg<signal.h>}} finds the file under @file{/usr/local/include}. If that 108510d565efSmrgfile contains @code{@w{#include_next <signal.h>}}, it starts searching 108610d565efSmrgafter that directory, and finds the file in @file{/usr/include}. 108710d565efSmrg 108810d565efSmrg@samp{#include_next} does not distinguish between @code{<@var{file}>} 108910d565efSmrgand @code{"@var{file}"} inclusion, nor does it check that the file you 109010d565efSmrgspecify has the same name as the current file. It simply looks for the 109110d565efSmrgfile named, starting with the directory in the search path after the one 109210d565efSmrgwhere the current file was found. 109310d565efSmrg 109410d565efSmrgThe use of @samp{#include_next} can lead to great confusion. We 109510d565efSmrgrecommend it be used only when there is no other alternative. In 109610d565efSmrgparticular, it should not be used in the headers belonging to a specific 109710d565efSmrgprogram; it should be used only to make global corrections along the 109810d565efSmrglines of @command{fixincludes}. 109910d565efSmrg 110010d565efSmrg@node System Headers 110110d565efSmrg@section System Headers 110210d565efSmrg@cindex system header files 110310d565efSmrg 110410d565efSmrgThe header files declaring interfaces to the operating system and 110510d565efSmrgruntime libraries often cannot be written in strictly conforming C@. 110610d565efSmrgTherefore, GCC gives code found in @dfn{system headers} special 110710d565efSmrgtreatment. All warnings, other than those generated by @samp{#warning} 110810d565efSmrg(@pxref{Diagnostics}), are suppressed while GCC is processing a system 110910d565efSmrgheader. Macros defined in a system header are immune to a few warnings 111010d565efSmrgwherever they are expanded. This immunity is granted on an ad-hoc 111110d565efSmrgbasis, when we find that a warning generates lots of false positives 111210d565efSmrgbecause of code in macros defined in system headers. 111310d565efSmrg 111410d565efSmrgNormally, only the headers found in specific directories are considered 111510d565efSmrgsystem headers. These directories are determined when GCC is compiled. 111610d565efSmrgThere are, however, two ways to make normal headers into system headers: 111710d565efSmrg 111810d565efSmrg@itemize @bullet 111910d565efSmrg@item 112010d565efSmrgHeader files found in directories added to the search path with the 112110d565efSmrg@option{-isystem} and @option{-idirafter} command-line options are 112210d565efSmrgtreated as system headers for the purposes of diagnostics. 112310d565efSmrg 112410d565efSmrgThe @option{-cxx-isystem} command line option adds its argument to the 112510d565efSmrglist of C++ system headers, similar to @option{-isystem} for C headers. 112610d565efSmrg 112710d565efSmrg@item 112810d565efSmrg@findex #pragma GCC system_header 112910d565efSmrgThere is also a directive, @code{@w{#pragma GCC system_header}}, which 113010d565efSmrgtells GCC to consider the rest of the current include file a system 113110d565efSmrgheader, no matter where it was found. Code that comes before the 113210d565efSmrg@samp{#pragma} in the file is not affected. @code{@w{#pragma GCC 113310d565efSmrgsystem_header}} has no effect in the primary source file. 113410d565efSmrg@end itemize 113510d565efSmrg 11360fc04c29SmrgOn some targets, such as RS/6000 AIX, GCC implicitly surrounds all 11370fc04c29Smrgsystem headers with an @samp{extern "C"} block when compiling as C++. 11380fc04c29Smrg 113910d565efSmrg@node Macros 114010d565efSmrg@chapter Macros 114110d565efSmrg 114210d565efSmrgA @dfn{macro} is a fragment of code which has been given a name. 114310d565efSmrgWhenever the name is used, it is replaced by the contents of the macro. 114410d565efSmrgThere are two kinds of macros. They differ mostly in what they look 114510d565efSmrglike when they are used. @dfn{Object-like} macros resemble data objects 114610d565efSmrgwhen used, @dfn{function-like} macros resemble function calls. 114710d565efSmrg 114810d565efSmrgYou may define any valid identifier as a macro, even if it is a C 114910d565efSmrgkeyword. The preprocessor does not know anything about keywords. This 115010d565efSmrgcan be useful if you wish to hide a keyword such as @code{const} from an 115110d565efSmrgolder compiler that does not understand it. However, the preprocessor 115210d565efSmrgoperator @code{defined} (@pxref{Defined}) can never be defined as a 115310d565efSmrgmacro, and C++'s named operators (@pxref{C++ Named Operators}) cannot be 115410d565efSmrgmacros when you are compiling C++. 115510d565efSmrg 115610d565efSmrg@menu 115710d565efSmrg* Object-like Macros:: 115810d565efSmrg* Function-like Macros:: 115910d565efSmrg* Macro Arguments:: 116010d565efSmrg* Stringizing:: 116110d565efSmrg* Concatenation:: 116210d565efSmrg* Variadic Macros:: 116310d565efSmrg* Predefined Macros:: 116410d565efSmrg* Undefining and Redefining Macros:: 116510d565efSmrg* Directives Within Macro Arguments:: 116610d565efSmrg* Macro Pitfalls:: 116710d565efSmrg@end menu 116810d565efSmrg 116910d565efSmrg@node Object-like Macros 117010d565efSmrg@section Object-like Macros 117110d565efSmrg@cindex object-like macro 117210d565efSmrg@cindex symbolic constants 117310d565efSmrg@cindex manifest constants 117410d565efSmrg 117510d565efSmrgAn @dfn{object-like macro} is a simple identifier which will be replaced 117610d565efSmrgby a code fragment. It is called object-like because it looks like a 117710d565efSmrgdata object in code that uses it. They are most commonly used to give 117810d565efSmrgsymbolic names to numeric constants. 117910d565efSmrg 118010d565efSmrg@findex #define 118110d565efSmrgYou create macros with the @samp{#define} directive. @samp{#define} is 118210d565efSmrgfollowed by the name of the macro and then the token sequence it should 118310d565efSmrgbe an abbreviation for, which is variously referred to as the macro's 118410d565efSmrg@dfn{body}, @dfn{expansion} or @dfn{replacement list}. For example, 118510d565efSmrg 118610d565efSmrg@smallexample 118710d565efSmrg#define BUFFER_SIZE 1024 118810d565efSmrg@end smallexample 118910d565efSmrg 119010d565efSmrg@noindent 119110d565efSmrgdefines a macro named @code{BUFFER_SIZE} as an abbreviation for the 119210d565efSmrgtoken @code{1024}. If somewhere after this @samp{#define} directive 119310d565efSmrgthere comes a C statement of the form 119410d565efSmrg 119510d565efSmrg@smallexample 119610d565efSmrgfoo = (char *) malloc (BUFFER_SIZE); 119710d565efSmrg@end smallexample 119810d565efSmrg 119910d565efSmrg@noindent 120010d565efSmrgthen the C preprocessor will recognize and @dfn{expand} the macro 120110d565efSmrg@code{BUFFER_SIZE}. The C compiler will see the same tokens as it would 120210d565efSmrgif you had written 120310d565efSmrg 120410d565efSmrg@smallexample 120510d565efSmrgfoo = (char *) malloc (1024); 120610d565efSmrg@end smallexample 120710d565efSmrg 120810d565efSmrgBy convention, macro names are written in uppercase. Programs are 120910d565efSmrgeasier to read when it is possible to tell at a glance which names are 121010d565efSmrgmacros. 121110d565efSmrg 121210d565efSmrgThe macro's body ends at the end of the @samp{#define} line. You may 121310d565efSmrgcontinue the definition onto multiple lines, if necessary, using 121410d565efSmrgbackslash-newline. When the macro is expanded, however, it will all 121510d565efSmrgcome out on one line. For example, 121610d565efSmrg 121710d565efSmrg@smallexample 121810d565efSmrg#define NUMBERS 1, \ 121910d565efSmrg 2, \ 122010d565efSmrg 3 122110d565efSmrgint x[] = @{ NUMBERS @}; 122210d565efSmrg @expansion{} int x[] = @{ 1, 2, 3 @}; 122310d565efSmrg@end smallexample 122410d565efSmrg 122510d565efSmrg@noindent 122610d565efSmrgThe most common visible consequence of this is surprising line numbers 122710d565efSmrgin error messages. 122810d565efSmrg 122910d565efSmrgThere is no restriction on what can go in a macro body provided it 123010d565efSmrgdecomposes into valid preprocessing tokens. Parentheses need not 123110d565efSmrgbalance, and the body need not resemble valid C code. (If it does not, 123210d565efSmrgyou may get error messages from the C compiler when you use the macro.) 123310d565efSmrg 123410d565efSmrgThe C preprocessor scans your program sequentially. Macro definitions 123510d565efSmrgtake effect at the place you write them. Therefore, the following input 123610d565efSmrgto the C preprocessor 123710d565efSmrg 123810d565efSmrg@smallexample 123910d565efSmrgfoo = X; 124010d565efSmrg#define X 4 124110d565efSmrgbar = X; 124210d565efSmrg@end smallexample 124310d565efSmrg 124410d565efSmrg@noindent 124510d565efSmrgproduces 124610d565efSmrg 124710d565efSmrg@smallexample 124810d565efSmrgfoo = X; 124910d565efSmrgbar = 4; 125010d565efSmrg@end smallexample 125110d565efSmrg 125210d565efSmrgWhen the preprocessor expands a macro name, the macro's expansion 125310d565efSmrgreplaces the macro invocation, then the expansion is examined for more 125410d565efSmrgmacros to expand. For example, 125510d565efSmrg 125610d565efSmrg@smallexample 125710d565efSmrg@group 125810d565efSmrg#define TABLESIZE BUFSIZE 125910d565efSmrg#define BUFSIZE 1024 126010d565efSmrgTABLESIZE 126110d565efSmrg @expansion{} BUFSIZE 126210d565efSmrg @expansion{} 1024 126310d565efSmrg@end group 126410d565efSmrg@end smallexample 126510d565efSmrg 126610d565efSmrg@noindent 126710d565efSmrg@code{TABLESIZE} is expanded first to produce @code{BUFSIZE}, then that 126810d565efSmrgmacro is expanded to produce the final result, @code{1024}. 126910d565efSmrg 127010d565efSmrgNotice that @code{BUFSIZE} was not defined when @code{TABLESIZE} was 127110d565efSmrgdefined. The @samp{#define} for @code{TABLESIZE} uses exactly the 127210d565efSmrgexpansion you specify---in this case, @code{BUFSIZE}---and does not 127310d565efSmrgcheck to see whether it too contains macro names. Only when you 127410d565efSmrg@emph{use} @code{TABLESIZE} is the result of its expansion scanned for 127510d565efSmrgmore macro names. 127610d565efSmrg 127710d565efSmrgThis makes a difference if you change the definition of @code{BUFSIZE} 127810d565efSmrgat some point in the source file. @code{TABLESIZE}, defined as shown, 127910d565efSmrgwill always expand using the definition of @code{BUFSIZE} that is 128010d565efSmrgcurrently in effect: 128110d565efSmrg 128210d565efSmrg@smallexample 128310d565efSmrg#define BUFSIZE 1020 128410d565efSmrg#define TABLESIZE BUFSIZE 128510d565efSmrg#undef BUFSIZE 128610d565efSmrg#define BUFSIZE 37 128710d565efSmrg@end smallexample 128810d565efSmrg 128910d565efSmrg@noindent 129010d565efSmrgNow @code{TABLESIZE} expands (in two stages) to @code{37}. 129110d565efSmrg 129210d565efSmrgIf the expansion of a macro contains its own name, either directly or 129310d565efSmrgvia intermediate macros, it is not expanded again when the expansion is 129410d565efSmrgexamined for more macros. This prevents infinite recursion. 129510d565efSmrg@xref{Self-Referential Macros}, for the precise details. 129610d565efSmrg 129710d565efSmrg@node Function-like Macros 129810d565efSmrg@section Function-like Macros 129910d565efSmrg@cindex function-like macros 130010d565efSmrg 130110d565efSmrgYou can also define macros whose use looks like a function call. These 130210d565efSmrgare called @dfn{function-like macros}. To define a function-like macro, 130310d565efSmrgyou use the same @samp{#define} directive, but you put a pair of 130410d565efSmrgparentheses immediately after the macro name. For example, 130510d565efSmrg 130610d565efSmrg@smallexample 130710d565efSmrg#define lang_init() c_init() 130810d565efSmrglang_init() 130910d565efSmrg @expansion{} c_init() 131010d565efSmrg@end smallexample 131110d565efSmrg 131210d565efSmrgA function-like macro is only expanded if its name appears with a pair 131310d565efSmrgof parentheses after it. If you write just the name, it is left alone. 131410d565efSmrgThis can be useful when you have a function and a macro of the same 131510d565efSmrgname, and you wish to use the function sometimes. 131610d565efSmrg 131710d565efSmrg@smallexample 131810d565efSmrgextern void foo(void); 131910d565efSmrg#define foo() /* @r{optimized inline version} */ 132010d565efSmrg@dots{} 132110d565efSmrg foo(); 132210d565efSmrg funcptr = foo; 132310d565efSmrg@end smallexample 132410d565efSmrg 132510d565efSmrgHere the call to @code{foo()} will use the macro, but the function 132610d565efSmrgpointer will get the address of the real function. If the macro were to 132710d565efSmrgbe expanded, it would cause a syntax error. 132810d565efSmrg 132910d565efSmrgIf you put spaces between the macro name and the parentheses in the 133010d565efSmrgmacro definition, that does not define a function-like macro, it defines 133110d565efSmrgan object-like macro whose expansion happens to begin with a pair of 133210d565efSmrgparentheses. 133310d565efSmrg 133410d565efSmrg@smallexample 133510d565efSmrg#define lang_init () c_init() 133610d565efSmrglang_init() 133710d565efSmrg @expansion{} () c_init()() 133810d565efSmrg@end smallexample 133910d565efSmrg 134010d565efSmrgThe first two pairs of parentheses in this expansion come from the 134110d565efSmrgmacro. The third is the pair that was originally after the macro 134210d565efSmrginvocation. Since @code{lang_init} is an object-like macro, it does not 134310d565efSmrgconsume those parentheses. 134410d565efSmrg 134510d565efSmrg@node Macro Arguments 134610d565efSmrg@section Macro Arguments 134710d565efSmrg@cindex arguments 134810d565efSmrg@cindex macros with arguments 134910d565efSmrg@cindex arguments in macro definitions 135010d565efSmrg 135110d565efSmrgFunction-like macros can take @dfn{arguments}, just like true functions. 135210d565efSmrgTo define a macro that uses arguments, you insert @dfn{parameters} 135310d565efSmrgbetween the pair of parentheses in the macro definition that make the 135410d565efSmrgmacro function-like. The parameters must be valid C identifiers, 135510d565efSmrgseparated by commas and optionally whitespace. 135610d565efSmrg 135710d565efSmrgTo invoke a macro that takes arguments, you write the name of the macro 135810d565efSmrgfollowed by a list of @dfn{actual arguments} in parentheses, separated 135910d565efSmrgby commas. The invocation of the macro need not be restricted to a 136010d565efSmrgsingle logical line---it can cross as many lines in the source file as 136110d565efSmrgyou wish. The number of arguments you give must match the number of 136210d565efSmrgparameters in the macro definition. When the macro is expanded, each 136310d565efSmrguse of a parameter in its body is replaced by the tokens of the 136410d565efSmrgcorresponding argument. (You need not use all of the parameters in the 136510d565efSmrgmacro body.) 136610d565efSmrg 136710d565efSmrgAs an example, here is a macro that computes the minimum of two numeric 136810d565efSmrgvalues, as it is defined in many C programs, and some uses. 136910d565efSmrg 137010d565efSmrg@smallexample 137110d565efSmrg#define min(X, Y) ((X) < (Y) ? (X) : (Y)) 137210d565efSmrg x = min(a, b); @expansion{} x = ((a) < (b) ? (a) : (b)); 137310d565efSmrg y = min(1, 2); @expansion{} y = ((1) < (2) ? (1) : (2)); 137410d565efSmrg z = min(a + 28, *p); @expansion{} z = ((a + 28) < (*p) ? (a + 28) : (*p)); 137510d565efSmrg@end smallexample 137610d565efSmrg 137710d565efSmrg@noindent 137810d565efSmrg(In this small example you can already see several of the dangers of 137910d565efSmrgmacro arguments. @xref{Macro Pitfalls}, for detailed explanations.) 138010d565efSmrg 138110d565efSmrgLeading and trailing whitespace in each argument is dropped, and all 138210d565efSmrgwhitespace between the tokens of an argument is reduced to a single 138310d565efSmrgspace. Parentheses within each argument must balance; a comma within 138410d565efSmrgsuch parentheses does not end the argument. However, there is no 138510d565efSmrgrequirement for square brackets or braces to balance, and they do not 138610d565efSmrgprevent a comma from separating arguments. Thus, 138710d565efSmrg 138810d565efSmrg@smallexample 138910d565efSmrgmacro (array[x = y, x + 1]) 139010d565efSmrg@end smallexample 139110d565efSmrg 139210d565efSmrg@noindent 139310d565efSmrgpasses two arguments to @code{macro}: @code{array[x = y} and @code{x + 139410d565efSmrg1]}. If you want to supply @code{array[x = y, x + 1]} as an argument, 139510d565efSmrgyou can write it as @code{array[(x = y, x + 1)]}, which is equivalent C 139610d565efSmrgcode. 139710d565efSmrg 139810d565efSmrgAll arguments to a macro are completely macro-expanded before they are 139910d565efSmrgsubstituted into the macro body. After substitution, the complete text 140010d565efSmrgis scanned again for macros to expand, including the arguments. This rule 140110d565efSmrgmay seem strange, but it is carefully designed so you need not worry 140210d565efSmrgabout whether any function call is actually a macro invocation. You can 140310d565efSmrgrun into trouble if you try to be too clever, though. @xref{Argument 140410d565efSmrgPrescan}, for detailed discussion. 140510d565efSmrg 140610d565efSmrgFor example, @code{min (min (a, b), c)} is first expanded to 140710d565efSmrg 140810d565efSmrg@smallexample 140910d565efSmrg min (((a) < (b) ? (a) : (b)), (c)) 141010d565efSmrg@end smallexample 141110d565efSmrg 141210d565efSmrg@noindent 141310d565efSmrgand then to 141410d565efSmrg 141510d565efSmrg@smallexample 141610d565efSmrg@group 141710d565efSmrg((((a) < (b) ? (a) : (b))) < (c) 141810d565efSmrg ? (((a) < (b) ? (a) : (b))) 141910d565efSmrg : (c)) 142010d565efSmrg@end group 142110d565efSmrg@end smallexample 142210d565efSmrg 142310d565efSmrg@noindent 142410d565efSmrg(Line breaks shown here for clarity would not actually be generated.) 142510d565efSmrg 142610d565efSmrg@cindex empty macro arguments 142710d565efSmrgYou can leave macro arguments empty; this is not an error to the 142810d565efSmrgpreprocessor (but many macros will then expand to invalid code). 142910d565efSmrgYou cannot leave out arguments entirely; if a macro takes two arguments, 143010d565efSmrgthere must be exactly one comma at the top level of its argument list. 143110d565efSmrgHere are some silly examples using @code{min}: 143210d565efSmrg 143310d565efSmrg@smallexample 143410d565efSmrgmin(, b) @expansion{} (( ) < (b) ? ( ) : (b)) 143510d565efSmrgmin(a, ) @expansion{} ((a ) < ( ) ? (a ) : ( )) 143610d565efSmrgmin(,) @expansion{} (( ) < ( ) ? ( ) : ( )) 143710d565efSmrgmin((,),) @expansion{} (((,)) < ( ) ? ((,)) : ( )) 143810d565efSmrg 143910d565efSmrgmin() @error{} macro "min" requires 2 arguments, but only 1 given 144010d565efSmrgmin(,,) @error{} macro "min" passed 3 arguments, but takes just 2 144110d565efSmrg@end smallexample 144210d565efSmrg 144310d565efSmrgWhitespace is not a preprocessing token, so if a macro @code{foo} takes 144410d565efSmrgone argument, @code{@w{foo ()}} and @code{@w{foo ( )}} both supply it an 144510d565efSmrgempty argument. Previous GNU preprocessor implementations and 144610d565efSmrgdocumentation were incorrect on this point, insisting that a 144710d565efSmrgfunction-like macro that takes a single argument be passed a space if an 144810d565efSmrgempty argument was required. 144910d565efSmrg 145010d565efSmrgMacro parameters appearing inside string literals are not replaced by 145110d565efSmrgtheir corresponding actual arguments. 145210d565efSmrg 145310d565efSmrg@smallexample 145410d565efSmrg#define foo(x) x, "x" 145510d565efSmrgfoo(bar) @expansion{} bar, "x" 145610d565efSmrg@end smallexample 145710d565efSmrg 145810d565efSmrg@node Stringizing 145910d565efSmrg@section Stringizing 146010d565efSmrg@cindex stringizing 146110d565efSmrg@cindex @samp{#} operator 146210d565efSmrg 146310d565efSmrgSometimes you may want to convert a macro argument into a string 146410d565efSmrgconstant. Parameters are not replaced inside string constants, but you 146510d565efSmrgcan use the @samp{#} preprocessing operator instead. When a macro 146610d565efSmrgparameter is used with a leading @samp{#}, the preprocessor replaces it 146710d565efSmrgwith the literal text of the actual argument, converted to a string 146810d565efSmrgconstant. Unlike normal parameter replacement, the argument is not 146910d565efSmrgmacro-expanded first. This is called @dfn{stringizing}. 147010d565efSmrg 147110d565efSmrgThere is no way to combine an argument with surrounding text and 147210d565efSmrgstringize it all together. Instead, you can write a series of adjacent 147310d565efSmrgstring constants and stringized arguments. The preprocessor 147410d565efSmrgreplaces the stringized arguments with string constants. The C 147510d565efSmrgcompiler then combines all the adjacent string constants into one 147610d565efSmrglong string. 147710d565efSmrg 147810d565efSmrgHere is an example of a macro definition that uses stringizing: 147910d565efSmrg 148010d565efSmrg@smallexample 148110d565efSmrg@group 148210d565efSmrg#define WARN_IF(EXP) \ 148310d565efSmrgdo @{ if (EXP) \ 148410d565efSmrg fprintf (stderr, "Warning: " #EXP "\n"); @} \ 148510d565efSmrgwhile (0) 148610d565efSmrgWARN_IF (x == 0); 148710d565efSmrg @expansion{} do @{ if (x == 0) 148810d565efSmrg fprintf (stderr, "Warning: " "x == 0" "\n"); @} while (0); 148910d565efSmrg@end group 149010d565efSmrg@end smallexample 149110d565efSmrg 149210d565efSmrg@noindent 149310d565efSmrgThe argument for @code{EXP} is substituted once, as-is, into the 149410d565efSmrg@code{if} statement, and once, stringized, into the argument to 149510d565efSmrg@code{fprintf}. If @code{x} were a macro, it would be expanded in the 149610d565efSmrg@code{if} statement, but not in the string. 149710d565efSmrg 149810d565efSmrgThe @code{do} and @code{while (0)} are a kludge to make it possible to 149910d565efSmrgwrite @code{WARN_IF (@var{arg});}, which the resemblance of 150010d565efSmrg@code{WARN_IF} to a function would make C programmers want to do; see 150110d565efSmrg@ref{Swallowing the Semicolon}. 150210d565efSmrg 150310d565efSmrgStringizing in C involves more than putting double-quote characters 150410d565efSmrgaround the fragment. The preprocessor backslash-escapes the quotes 150510d565efSmrgsurrounding embedded string constants, and all backslashes within string and 150610d565efSmrgcharacter constants, in order to get a valid C string constant with the 150710d565efSmrgproper contents. Thus, stringizing @code{@w{p = "foo\n";}} results in 150810d565efSmrg@t{@w{"p = \"foo\\n\";"}}. However, backslashes that are not inside string 150910d565efSmrgor character constants are not duplicated: @samp{\n} by itself 151010d565efSmrgstringizes to @t{"\n"}. 151110d565efSmrg 151210d565efSmrgAll leading and trailing whitespace in text being stringized is 151310d565efSmrgignored. Any sequence of whitespace in the middle of the text is 151410d565efSmrgconverted to a single space in the stringized result. Comments are 151510d565efSmrgreplaced by whitespace long before stringizing happens, so they 151610d565efSmrgnever appear in stringized text. 151710d565efSmrg 151810d565efSmrgThere is no way to convert a macro argument into a character constant. 151910d565efSmrg 152010d565efSmrgIf you want to stringize the result of expansion of a macro argument, 152110d565efSmrgyou have to use two levels of macros. 152210d565efSmrg 152310d565efSmrg@smallexample 152410d565efSmrg#define xstr(s) str(s) 152510d565efSmrg#define str(s) #s 152610d565efSmrg#define foo 4 152710d565efSmrgstr (foo) 152810d565efSmrg @expansion{} "foo" 152910d565efSmrgxstr (foo) 153010d565efSmrg @expansion{} xstr (4) 153110d565efSmrg @expansion{} str (4) 153210d565efSmrg @expansion{} "4" 153310d565efSmrg@end smallexample 153410d565efSmrg 153510d565efSmrg@code{s} is stringized when it is used in @code{str}, so it is not 153610d565efSmrgmacro-expanded first. But @code{s} is an ordinary argument to 153710d565efSmrg@code{xstr}, so it is completely macro-expanded before @code{xstr} 153810d565efSmrgitself is expanded (@pxref{Argument Prescan}). Therefore, by the time 153910d565efSmrg@code{str} gets to its argument, it has already been macro-expanded. 154010d565efSmrg 154110d565efSmrg@node Concatenation 154210d565efSmrg@section Concatenation 154310d565efSmrg@cindex concatenation 154410d565efSmrg@cindex token pasting 154510d565efSmrg@cindex token concatenation 154610d565efSmrg@cindex @samp{##} operator 154710d565efSmrg 154810d565efSmrgIt is often useful to merge two tokens into one while expanding macros. 154910d565efSmrgThis is called @dfn{token pasting} or @dfn{token concatenation}. The 155010d565efSmrg@samp{##} preprocessing operator performs token pasting. When a macro 155110d565efSmrgis expanded, the two tokens on either side of each @samp{##} operator 155210d565efSmrgare combined into a single token, which then replaces the @samp{##} and 155310d565efSmrgthe two original tokens in the macro expansion. Usually both will be 155410d565efSmrgidentifiers, or one will be an identifier and the other a preprocessing 155510d565efSmrgnumber. When pasted, they make a longer identifier. This isn't the 155610d565efSmrgonly valid case. It is also possible to concatenate two numbers (or a 155710d565efSmrgnumber and a name, such as @code{1.5} and @code{e3}) into a number. 155810d565efSmrgAlso, multi-character operators such as @code{+=} can be formed by 155910d565efSmrgtoken pasting. 156010d565efSmrg 156110d565efSmrgHowever, two tokens that don't together form a valid token cannot be 156210d565efSmrgpasted together. For example, you cannot concatenate @code{x} with 156310d565efSmrg@code{+} in either order. If you try, the preprocessor issues a warning 156410d565efSmrgand emits the two tokens. Whether it puts white space between the 156510d565efSmrgtokens is undefined. It is common to find unnecessary uses of @samp{##} 156610d565efSmrgin complex macros. If you get this warning, it is likely that you can 156710d565efSmrgsimply remove the @samp{##}. 156810d565efSmrg 156910d565efSmrgBoth the tokens combined by @samp{##} could come from the macro body, 157010d565efSmrgbut you could just as well write them as one token in the first place. 157110d565efSmrgToken pasting is most useful when one or both of the tokens comes from a 157210d565efSmrgmacro argument. If either of the tokens next to an @samp{##} is a 157310d565efSmrgparameter name, it is replaced by its actual argument before @samp{##} 157410d565efSmrgexecutes. As with stringizing, the actual argument is not 157510d565efSmrgmacro-expanded first. If the argument is empty, that @samp{##} has no 157610d565efSmrgeffect. 157710d565efSmrg 157810d565efSmrgKeep in mind that the C preprocessor converts comments to whitespace 157910d565efSmrgbefore macros are even considered. Therefore, you cannot create a 158010d565efSmrgcomment by concatenating @samp{/} and @samp{*}. You can put as much 158110d565efSmrgwhitespace between @samp{##} and its operands as you like, including 158210d565efSmrgcomments, and you can put comments in arguments that will be 158310d565efSmrgconcatenated. However, it is an error if @samp{##} appears at either 158410d565efSmrgend of a macro body. 158510d565efSmrg 158610d565efSmrgConsider a C program that interprets named commands. There probably 158710d565efSmrgneeds to be a table of commands, perhaps an array of structures declared 158810d565efSmrgas follows: 158910d565efSmrg 159010d565efSmrg@smallexample 159110d565efSmrg@group 159210d565efSmrgstruct command 159310d565efSmrg@{ 159410d565efSmrg char *name; 159510d565efSmrg void (*function) (void); 159610d565efSmrg@}; 159710d565efSmrg@end group 159810d565efSmrg 159910d565efSmrg@group 160010d565efSmrgstruct command commands[] = 160110d565efSmrg@{ 160210d565efSmrg @{ "quit", quit_command @}, 160310d565efSmrg @{ "help", help_command @}, 160410d565efSmrg @dots{} 160510d565efSmrg@}; 160610d565efSmrg@end group 160710d565efSmrg@end smallexample 160810d565efSmrg 160910d565efSmrgIt would be cleaner not to have to give each command name twice, once in 161010d565efSmrgthe string constant and once in the function name. A macro which takes the 161110d565efSmrgname of a command as an argument can make this unnecessary. The string 161210d565efSmrgconstant can be created with stringizing, and the function name by 161310d565efSmrgconcatenating the argument with @samp{_command}. Here is how it is done: 161410d565efSmrg 161510d565efSmrg@smallexample 161610d565efSmrg#define COMMAND(NAME) @{ #NAME, NAME ## _command @} 161710d565efSmrg 161810d565efSmrgstruct command commands[] = 161910d565efSmrg@{ 162010d565efSmrg COMMAND (quit), 162110d565efSmrg COMMAND (help), 162210d565efSmrg @dots{} 162310d565efSmrg@}; 162410d565efSmrg@end smallexample 162510d565efSmrg 162610d565efSmrg@node Variadic Macros 162710d565efSmrg@section Variadic Macros 162810d565efSmrg@cindex variable number of arguments 162910d565efSmrg@cindex macros with variable arguments 163010d565efSmrg@cindex variadic macros 163110d565efSmrg 163210d565efSmrgA macro can be declared to accept a variable number of arguments much as 163310d565efSmrga function can. The syntax for defining the macro is similar to that of 163410d565efSmrga function. Here is an example: 163510d565efSmrg 163610d565efSmrg@smallexample 1637*ec02198aSmrg#define eprintf(...) fprintf (stderr, __VA_ARGS__) 163810d565efSmrg@end smallexample 163910d565efSmrg 164010d565efSmrgThis kind of macro is called @dfn{variadic}. When the macro is invoked, 164110d565efSmrgall the tokens in its argument list after the last named argument (this 164210d565efSmrgmacro has none), including any commas, become the @dfn{variable 164310d565efSmrgargument}. This sequence of tokens replaces the identifier 164410d565efSmrg@code{@w{__VA_ARGS__}} in the macro body wherever it appears. Thus, we 164510d565efSmrghave this expansion: 164610d565efSmrg 164710d565efSmrg@smallexample 164810d565efSmrgeprintf ("%s:%d: ", input_file, lineno) 164910d565efSmrg @expansion{} fprintf (stderr, "%s:%d: ", input_file, lineno) 165010d565efSmrg@end smallexample 165110d565efSmrg 165210d565efSmrgThe variable argument is completely macro-expanded before it is inserted 165310d565efSmrginto the macro expansion, just like an ordinary argument. You may use 165410d565efSmrgthe @samp{#} and @samp{##} operators to stringize the variable argument 165510d565efSmrgor to paste its leading or trailing token with another token. (But see 165610d565efSmrgbelow for an important special case for @samp{##}.) 165710d565efSmrg 165810d565efSmrgIf your macro is complicated, you may want a more descriptive name for 165910d565efSmrgthe variable argument than @code{@w{__VA_ARGS__}}. CPP permits 166010d565efSmrgthis, as an extension. You may write an argument name immediately 1661*ec02198aSmrgbefore the @samp{...}; that name is used for the variable argument. 166210d565efSmrgThe @code{eprintf} macro above could be written 166310d565efSmrg 166410d565efSmrg@smallexample 1665*ec02198aSmrg#define eprintf(args...) fprintf (stderr, args) 166610d565efSmrg@end smallexample 166710d565efSmrg 166810d565efSmrg@noindent 166910d565efSmrgusing this extension. You cannot use @code{@w{__VA_ARGS__}} and this 167010d565efSmrgextension in the same macro. 167110d565efSmrg 167210d565efSmrgYou can have named arguments as well as variable arguments in a variadic 167310d565efSmrgmacro. We could define @code{eprintf} like this, instead: 167410d565efSmrg 167510d565efSmrg@smallexample 1676*ec02198aSmrg#define eprintf(format, ...) fprintf (stderr, format, __VA_ARGS__) 167710d565efSmrg@end smallexample 167810d565efSmrg 167910d565efSmrg@noindent 1680c7a68eb7SmrgThis formulation looks more descriptive, but historically it was less 1681c7a68eb7Smrgflexible: you had to supply at least one argument after the format 1682c7a68eb7Smrgstring. In standard C, you could not omit the comma separating the 1683c7a68eb7Smrgnamed argument from the variable arguments. (Note that this 1684c7a68eb7Smrgrestriction has been lifted in C++2a, and never existed in GNU C; see 1685c7a68eb7Smrgbelow.) 1686c7a68eb7Smrg 1687c7a68eb7SmrgFurthermore, if you left the variable argument empty, you would have 1688c7a68eb7Smrggotten a syntax error, because there would have been an extra comma 1689c7a68eb7Smrgafter the format string. 169010d565efSmrg 169110d565efSmrg@smallexample 169210d565efSmrgeprintf("success!\n", ); 169310d565efSmrg @expansion{} fprintf(stderr, "success!\n", ); 169410d565efSmrg@end smallexample 169510d565efSmrg 1696c7a68eb7SmrgThis has been fixed in C++2a, and GNU CPP also has a pair of 1697c7a68eb7Smrgextensions which deal with this problem. 1698c7a68eb7Smrg 1699c7a68eb7SmrgFirst, in GNU CPP, and in C++ beginning in C++2a, you are allowed to 1700c7a68eb7Smrgleave the variable argument out entirely: 170110d565efSmrg 170210d565efSmrg@smallexample 170310d565efSmrgeprintf ("success!\n") 170410d565efSmrg @expansion{} fprintf(stderr, "success!\n", ); 170510d565efSmrg@end smallexample 170610d565efSmrg 170710d565efSmrg@noindent 1708c7a68eb7SmrgSecond, C++2a introduces the @code{@w{__VA_OPT__}} function macro. 1709c7a68eb7SmrgThis macro may only appear in the definition of a variadic macro. If 1710c7a68eb7Smrgthe variable argument has any tokens, then a @code{@w{__VA_OPT__}} 1711c7a68eb7Smrginvocation expands to its argument; but if the variable argument does 1712c7a68eb7Smrgnot have any tokens, the @code{@w{__VA_OPT__}} expands to nothing: 1713c7a68eb7Smrg 1714c7a68eb7Smrg@smallexample 1715*ec02198aSmrg#define eprintf(format, ...) \ 1716c7a68eb7Smrg fprintf (stderr, format __VA_OPT__(,) __VA_ARGS__) 1717c7a68eb7Smrg@end smallexample 1718c7a68eb7Smrg 1719c7a68eb7Smrg@code{@w{__VA_OPT__}} is also available in GNU C and GNU C++. 1720c7a68eb7Smrg 1721c7a68eb7SmrgHistorically, GNU CPP has also had another extension to handle the 1722c7a68eb7Smrgtrailing comma: the @samp{##} token paste operator has a special 1723c7a68eb7Smrgmeaning when placed between a comma and a variable argument. Despite 1724c7a68eb7Smrgthe introduction of @code{@w{__VA_OPT__}}, this extension remains 1725c7a68eb7Smrgsupported in GNU CPP, for backward compatibility. If you write 172610d565efSmrg 172710d565efSmrg@smallexample 1728*ec02198aSmrg#define eprintf(format, ...) fprintf (stderr, format, ##__VA_ARGS__) 172910d565efSmrg@end smallexample 173010d565efSmrg 173110d565efSmrg@noindent 173210d565efSmrgand the variable argument is left out when the @code{eprintf} macro is 173310d565efSmrgused, then the comma before the @samp{##} will be deleted. This does 173410d565efSmrg@emph{not} happen if you pass an empty argument, nor does it happen if 173510d565efSmrgthe token preceding @samp{##} is anything other than a comma. 173610d565efSmrg 173710d565efSmrg@smallexample 173810d565efSmrgeprintf ("success!\n") 173910d565efSmrg @expansion{} fprintf(stderr, "success!\n"); 174010d565efSmrg@end smallexample 174110d565efSmrg 174210d565efSmrg@noindent 174310d565efSmrgThe above explanation is ambiguous about the case where the only macro 174410d565efSmrgparameter is a variable arguments parameter, as it is meaningless to 174510d565efSmrgtry to distinguish whether no argument at all is an empty argument or 174610d565efSmrga missing argument. 174710d565efSmrgCPP retains the comma when conforming to a specific C 174810d565efSmrgstandard. Otherwise the comma is dropped as an extension to the standard. 174910d565efSmrg 175010d565efSmrgThe C standard 175110d565efSmrgmandates that the only place the identifier @code{@w{__VA_ARGS__}} 175210d565efSmrgcan appear is in the replacement list of a variadic macro. It may not 175310d565efSmrgbe used as a macro name, macro argument name, or within a different type 175410d565efSmrgof macro. It may also be forbidden in open text; the standard is 175510d565efSmrgambiguous. We recommend you avoid using it except for its defined 175610d565efSmrgpurpose. 175710d565efSmrg 1758c7a68eb7SmrgLikewise, C++ forbids @code{@w{__VA_OPT__}} anywhere outside the 1759c7a68eb7Smrgreplacement list of a variadic macro. 1760c7a68eb7Smrg 176110d565efSmrgVariadic macros became a standard part of the C language with C99. 176210d565efSmrgGNU CPP previously supported them 176310d565efSmrgwith a named variable argument 1764*ec02198aSmrg(@samp{args...}, not @samp{...} and @code{@w{__VA_ARGS__}}), which 176510d565efSmrgis still supported for backward compatibility. 176610d565efSmrg 176710d565efSmrg@node Predefined Macros 176810d565efSmrg@section Predefined Macros 176910d565efSmrg 177010d565efSmrg@cindex predefined macros 177110d565efSmrgSeveral object-like macros are predefined; you use them without 177210d565efSmrgsupplying their definitions. They fall into three classes: standard, 177310d565efSmrgcommon, and system-specific. 177410d565efSmrg 177510d565efSmrgIn C++, there is a fourth category, the named operators. They act like 177610d565efSmrgpredefined macros, but you cannot undefine them. 177710d565efSmrg 177810d565efSmrg@menu 177910d565efSmrg* Standard Predefined Macros:: 178010d565efSmrg* Common Predefined Macros:: 178110d565efSmrg* System-specific Predefined Macros:: 178210d565efSmrg* C++ Named Operators:: 178310d565efSmrg@end menu 178410d565efSmrg 178510d565efSmrg@node Standard Predefined Macros 178610d565efSmrg@subsection Standard Predefined Macros 178710d565efSmrg@cindex standard predefined macros. 178810d565efSmrg 178910d565efSmrgThe standard predefined macros are specified by the relevant 179010d565efSmrglanguage standards, so they are available with all compilers that 179110d565efSmrgimplement those standards. Older compilers may not provide all of 179210d565efSmrgthem. Their names all start with double underscores. 179310d565efSmrg 179410d565efSmrg@table @code 179510d565efSmrg@item __FILE__ 179610d565efSmrgThis macro expands to the name of the current input file, in the form of 179710d565efSmrga C string constant. This is the path by which the preprocessor opened 179810d565efSmrgthe file, not the short name specified in @samp{#include} or as the 179910d565efSmrginput file name argument. For example, 180010d565efSmrg@code{"/usr/local/include/myheader.h"} is a possible expansion of this 180110d565efSmrgmacro. 180210d565efSmrg 180310d565efSmrg@item __LINE__ 180410d565efSmrgThis macro expands to the current input line number, in the form of a 180510d565efSmrgdecimal integer constant. While we call it a predefined macro, it's 180610d565efSmrga pretty strange macro, since its ``definition'' changes with each 180710d565efSmrgnew line of source code. 180810d565efSmrg@end table 180910d565efSmrg 181010d565efSmrg@code{__FILE__} and @code{__LINE__} are useful in generating an error 181110d565efSmrgmessage to report an inconsistency detected by the program; the message 181210d565efSmrgcan state the source line at which the inconsistency was detected. For 181310d565efSmrgexample, 181410d565efSmrg 181510d565efSmrg@smallexample 181610d565efSmrgfprintf (stderr, "Internal error: " 181710d565efSmrg "negative string length " 181810d565efSmrg "%d at %s, line %d.", 181910d565efSmrg length, __FILE__, __LINE__); 182010d565efSmrg@end smallexample 182110d565efSmrg 182210d565efSmrgAn @samp{#include} directive changes the expansions of @code{__FILE__} 182310d565efSmrgand @code{__LINE__} to correspond to the included file. At the end of 182410d565efSmrgthat file, when processing resumes on the input file that contained 182510d565efSmrgthe @samp{#include} directive, the expansions of @code{__FILE__} and 182610d565efSmrg@code{__LINE__} revert to the values they had before the 182710d565efSmrg@samp{#include} (but @code{__LINE__} is then incremented by one as 182810d565efSmrgprocessing moves to the line after the @samp{#include}). 182910d565efSmrg 183010d565efSmrgA @samp{#line} directive changes @code{__LINE__}, and may change 183110d565efSmrg@code{__FILE__} as well. @xref{Line Control}. 183210d565efSmrg 183310d565efSmrgC99 introduced @code{__func__}, and GCC has provided @code{__FUNCTION__} 183410d565efSmrgfor a long time. Both of these are strings containing the name of the 183510d565efSmrgcurrent function (there are slight semantic differences; see the GCC 183610d565efSmrgmanual). Neither of them is a macro; the preprocessor does not know the 183710d565efSmrgname of the current function. They tend to be useful in conjunction 183810d565efSmrgwith @code{__FILE__} and @code{__LINE__}, though. 183910d565efSmrg 184010d565efSmrg@table @code 184110d565efSmrg 184210d565efSmrg@item __DATE__ 184310d565efSmrgThis macro expands to a string constant that describes the date on which 184410d565efSmrgthe preprocessor is being run. The string constant contains eleven 184510d565efSmrgcharacters and looks like @code{@w{"Feb 12 1996"}}. If the day of the 184610d565efSmrgmonth is less than 10, it is padded with a space on the left. 184710d565efSmrg 184810d565efSmrgIf GCC cannot determine the current date, it will emit a warning message 184910d565efSmrg(once per compilation) and @code{__DATE__} will expand to 185010d565efSmrg@code{@w{"??? ?? ????"}}. 185110d565efSmrg 185210d565efSmrg@item __TIME__ 185310d565efSmrgThis macro expands to a string constant that describes the time at 185410d565efSmrgwhich the preprocessor is being run. The string constant contains 185510d565efSmrgeight characters and looks like @code{"23:59:01"}. 185610d565efSmrg 185710d565efSmrgIf GCC cannot determine the current time, it will emit a warning message 185810d565efSmrg(once per compilation) and @code{__TIME__} will expand to 185910d565efSmrg@code{"??:??:??"}. 186010d565efSmrg 186110d565efSmrg@item __STDC__ 186210d565efSmrgIn normal operation, this macro expands to the constant 1, to signify 186310d565efSmrgthat this compiler conforms to ISO Standard C@. If GNU CPP is used with 186410d565efSmrga compiler other than GCC, this is not necessarily true; however, the 186510d565efSmrgpreprocessor always conforms to the standard unless the 186610d565efSmrg@option{-traditional-cpp} option is used. 186710d565efSmrg 186810d565efSmrgThis macro is not defined if the @option{-traditional-cpp} option is used. 186910d565efSmrg 187010d565efSmrgOn some hosts, the system compiler uses a different convention, where 187110d565efSmrg@code{__STDC__} is normally 0, but is 1 if the user specifies strict 187210d565efSmrgconformance to the C Standard. CPP follows the host convention when 187310d565efSmrgprocessing system header files, but when processing user files 187410d565efSmrg@code{__STDC__} is always 1. This has been reported to cause problems; 187510d565efSmrgfor instance, some versions of Solaris provide X Windows headers that 187610d565efSmrgexpect @code{__STDC__} to be either undefined or 1. @xref{Invocation}. 187710d565efSmrg 187810d565efSmrg@item __STDC_VERSION__ 187910d565efSmrgThis macro expands to the C Standard's version number, a long integer 188010d565efSmrgconstant of the form @code{@var{yyyy}@var{mm}L} where @var{yyyy} and 188110d565efSmrg@var{mm} are the year and month of the Standard version. This signifies 188210d565efSmrgwhich version of the C Standard the compiler conforms to. Like 188310d565efSmrg@code{__STDC__}, this is not necessarily accurate for the entire 188410d565efSmrgimplementation, unless GNU CPP is being used with GCC@. 188510d565efSmrg 188610d565efSmrgThe value @code{199409L} signifies the 1989 C standard as amended in 188710d565efSmrg1994, which is the current default; the value @code{199901L} signifies 1888c7a68eb7Smrgthe 1999 revision of the C standard; the value @code{201112L} 1889c7a68eb7Smrgsignifies the 2011 revision of the C standard; the value 1890c7a68eb7Smrg@code{201710L} signifies the 2017 revision of the C standard (which is 1891c7a68eb7Smrgotherwise identical to the 2011 version apart from correction of 18920fc04c29Smrgdefects). An unspecified value larger than @code{201710L} is used for 18930fc04c29Smrgthe experimental @option{-std=c2x} and @option{-std=gnu2x} modes. 189410d565efSmrg 189510d565efSmrgThis macro is not defined if the @option{-traditional-cpp} option is 189610d565efSmrgused, nor when compiling C++ or Objective-C@. 189710d565efSmrg 189810d565efSmrg@item __STDC_HOSTED__ 189910d565efSmrgThis macro is defined, with value 1, if the compiler's target is a 190010d565efSmrg@dfn{hosted environment}. A hosted environment has the complete 190110d565efSmrgfacilities of the standard C library available. 190210d565efSmrg 190310d565efSmrg@item __cplusplus 190410d565efSmrgThis macro is defined when the C++ compiler is in use. You can use 190510d565efSmrg@code{__cplusplus} to test whether a header is compiled by a C compiler 190610d565efSmrgor a C++ compiler. This macro is similar to @code{__STDC_VERSION__}, in 190710d565efSmrgthat it expands to a version number. Depending on the language standard 190810d565efSmrgselected, the value of the macro is 190910d565efSmrg@code{199711L} for the 1998 C++ standard, 191010d565efSmrg@code{201103L} for the 2011 C++ standard, 191110d565efSmrg@code{201402L} for the 2014 C++ standard, 1912c7a68eb7Smrg@code{201703L} for the 2017 C++ standard, 1913c7a68eb7Smrgor an unspecified value strictly larger than @code{201703L} for the 1914c7a68eb7Smrgexperimental languages enabled by @option{-std=c++2a} and 1915c7a68eb7Smrg@option{-std=gnu++2a}. 191610d565efSmrg 191710d565efSmrg@item __OBJC__ 191810d565efSmrgThis macro is defined, with value 1, when the Objective-C compiler is in 191910d565efSmrguse. You can use @code{__OBJC__} to test whether a header is compiled 192010d565efSmrgby a C compiler or an Objective-C compiler. 192110d565efSmrg 192210d565efSmrg@item __ASSEMBLER__ 192310d565efSmrgThis macro is defined with value 1 when preprocessing assembly 192410d565efSmrglanguage. 192510d565efSmrg 192610d565efSmrg@end table 192710d565efSmrg 192810d565efSmrg@node Common Predefined Macros 192910d565efSmrg@subsection Common Predefined Macros 193010d565efSmrg@cindex common predefined macros 193110d565efSmrg 193210d565efSmrgThe common predefined macros are GNU C extensions. They are available 193310d565efSmrgwith the same meanings regardless of the machine or operating system on 193410d565efSmrgwhich you are using GNU C or GNU Fortran. Their names all start with 193510d565efSmrgdouble underscores. 193610d565efSmrg 193710d565efSmrg@table @code 193810d565efSmrg 193910d565efSmrg@item __COUNTER__ 194010d565efSmrgThis macro expands to sequential integral values starting from 0. In 194110d565efSmrgconjunction with the @code{##} operator, this provides a convenient means to 194210d565efSmrggenerate unique identifiers. Care must be taken to ensure that 194310d565efSmrg@code{__COUNTER__} is not expanded prior to inclusion of precompiled headers 194410d565efSmrgwhich use it. Otherwise, the precompiled headers will not be used. 194510d565efSmrg 194610d565efSmrg@item __GFORTRAN__ 194710d565efSmrgThe GNU Fortran compiler defines this. 194810d565efSmrg 194910d565efSmrg@item __GNUC__ 195010d565efSmrg@itemx __GNUC_MINOR__ 195110d565efSmrg@itemx __GNUC_PATCHLEVEL__ 195210d565efSmrgThese macros are defined by all GNU compilers that use the C 195310d565efSmrgpreprocessor: C, C++, Objective-C and Fortran. Their values are the major 195410d565efSmrgversion, minor version, and patch level of the compiler, as integer 195510d565efSmrgconstants. For example, GCC version @var{x}.@var{y}.@var{z} 195610d565efSmrgdefines @code{__GNUC__} to @var{x}, @code{__GNUC_MINOR__} to @var{y}, 195710d565efSmrgand @code{__GNUC_PATCHLEVEL__} to @var{z}. These 195810d565efSmrgmacros are also defined if you invoke the preprocessor directly. 195910d565efSmrg 196010d565efSmrgIf all you need to know is whether or not your program is being compiled 196110d565efSmrgby GCC, or a non-GCC compiler that claims to accept the GNU C dialects, 196210d565efSmrgyou can simply test @code{__GNUC__}. If you need to write code 196310d565efSmrgwhich depends on a specific version, you must be more careful. Each 196410d565efSmrgtime the minor version is increased, the patch level is reset to zero; 196510d565efSmrgeach time the major version is increased, the 196610d565efSmrgminor version and patch level are reset. If you wish to use the 196710d565efSmrgpredefined macros directly in the conditional, you will need to write it 196810d565efSmrglike this: 196910d565efSmrg 197010d565efSmrg@smallexample 197110d565efSmrg/* @r{Test for GCC > 3.2.0} */ 197210d565efSmrg#if __GNUC__ > 3 || \ 197310d565efSmrg (__GNUC__ == 3 && (__GNUC_MINOR__ > 2 || \ 197410d565efSmrg (__GNUC_MINOR__ == 2 && \ 197510d565efSmrg __GNUC_PATCHLEVEL__ > 0)) 197610d565efSmrg@end smallexample 197710d565efSmrg 197810d565efSmrg@noindent 197910d565efSmrgAnother approach is to use the predefined macros to 198010d565efSmrgcalculate a single number, then compare that against a threshold: 198110d565efSmrg 198210d565efSmrg@smallexample 198310d565efSmrg#define GCC_VERSION (__GNUC__ * 10000 \ 198410d565efSmrg + __GNUC_MINOR__ * 100 \ 198510d565efSmrg + __GNUC_PATCHLEVEL__) 198610d565efSmrg@dots{} 198710d565efSmrg/* @r{Test for GCC > 3.2.0} */ 198810d565efSmrg#if GCC_VERSION > 30200 198910d565efSmrg@end smallexample 199010d565efSmrg 199110d565efSmrg@noindent 199210d565efSmrgMany people find this form easier to understand. 199310d565efSmrg 199410d565efSmrg@item __GNUG__ 199510d565efSmrgThe GNU C++ compiler defines this. Testing it is equivalent to 199610d565efSmrgtesting @code{@w{(__GNUC__ && __cplusplus)}}. 199710d565efSmrg 199810d565efSmrg@item __STRICT_ANSI__ 199910d565efSmrgGCC defines this macro if and only if the @option{-ansi} switch, or a 200010d565efSmrg@option{-std} switch specifying strict conformance to some version of ISO C 200110d565efSmrgor ISO C++, was specified when GCC was invoked. It is defined to @samp{1}. 200210d565efSmrgThis macro exists primarily to direct GNU libc's header files to use only 200310d565efSmrgdefinitions found in standard C. 200410d565efSmrg 200510d565efSmrg@item __BASE_FILE__ 200610d565efSmrgThis macro expands to the name of the main input file, in the form 200710d565efSmrgof a C string constant. This is the source file that was specified 200810d565efSmrgon the command line of the preprocessor or C compiler. 200910d565efSmrg 201010d565efSmrg@item __INCLUDE_LEVEL__ 201110d565efSmrgThis macro expands to a decimal integer constant that represents the 201210d565efSmrgdepth of nesting in include files. The value of this macro is 201310d565efSmrgincremented on every @samp{#include} directive and decremented at the 201410d565efSmrgend of every included file. It starts out at 0, its value within the 201510d565efSmrgbase file specified on the command line. 201610d565efSmrg 201710d565efSmrg@item __ELF__ 201810d565efSmrgThis macro is defined if the target uses the ELF object format. 201910d565efSmrg 202010d565efSmrg@item __VERSION__ 202110d565efSmrgThis macro expands to a string constant which describes the version of 202210d565efSmrgthe compiler in use. You should not rely on its contents having any 202310d565efSmrgparticular form, but it can be counted on to contain at least the 202410d565efSmrgrelease number. 202510d565efSmrg 202610d565efSmrg@item __OPTIMIZE__ 202710d565efSmrg@itemx __OPTIMIZE_SIZE__ 202810d565efSmrg@itemx __NO_INLINE__ 202910d565efSmrgThese macros describe the compilation mode. @code{__OPTIMIZE__} is 203010d565efSmrgdefined in all optimizing compilations. @code{__OPTIMIZE_SIZE__} is 203110d565efSmrgdefined if the compiler is optimizing for size, not speed. 203210d565efSmrg@code{__NO_INLINE__} is defined if no functions will be inlined into 203310d565efSmrgtheir callers (when not optimizing, or when inlining has been 203410d565efSmrgspecifically disabled by @option{-fno-inline}). 203510d565efSmrg 203610d565efSmrgThese macros cause certain GNU header files to provide optimized 203710d565efSmrgdefinitions, using macros or inline functions, of system library 203810d565efSmrgfunctions. You should not use these macros in any way unless you make 203910d565efSmrgsure that programs will execute with the same effect whether or not they 204010d565efSmrgare defined. If they are defined, their value is 1. 204110d565efSmrg 204210d565efSmrg@item __GNUC_GNU_INLINE__ 204310d565efSmrgGCC defines this macro if functions declared @code{inline} will be 204410d565efSmrghandled in GCC's traditional gnu90 mode. Object files will contain 204510d565efSmrgexternally visible definitions of all functions declared @code{inline} 204610d565efSmrgwithout @code{extern} or @code{static}. They will not contain any 204710d565efSmrgdefinitions of any functions declared @code{extern inline}. 204810d565efSmrg 204910d565efSmrg@item __GNUC_STDC_INLINE__ 205010d565efSmrgGCC defines this macro if functions declared @code{inline} will be 205110d565efSmrghandled according to the ISO C99 or later standards. Object files will contain 205210d565efSmrgexternally visible definitions of all functions declared @code{extern 205310d565efSmrginline}. They will not contain definitions of any functions declared 205410d565efSmrg@code{inline} without @code{extern}. 205510d565efSmrg 205610d565efSmrgIf this macro is defined, GCC supports the @code{gnu_inline} function 205710d565efSmrgattribute as a way to always get the gnu90 behavior. 205810d565efSmrg 205910d565efSmrg@item __CHAR_UNSIGNED__ 206010d565efSmrgGCC defines this macro if and only if the data type @code{char} is 206110d565efSmrgunsigned on the target machine. It exists to cause the standard header 206210d565efSmrgfile @file{limits.h} to work correctly. You should not use this macro 206310d565efSmrgyourself; instead, refer to the standard macros defined in @file{limits.h}. 206410d565efSmrg 206510d565efSmrg@item __WCHAR_UNSIGNED__ 206610d565efSmrgLike @code{__CHAR_UNSIGNED__}, this macro is defined if and only if the 206710d565efSmrgdata type @code{wchar_t} is unsigned and the front-end is in C++ mode. 206810d565efSmrg 206910d565efSmrg@item __REGISTER_PREFIX__ 207010d565efSmrgThis macro expands to a single token (not a string constant) which is 207110d565efSmrgthe prefix applied to CPU register names in assembly language for this 207210d565efSmrgtarget. You can use it to write assembly that is usable in multiple 207310d565efSmrgenvironments. For example, in the @code{m68k-aout} environment it 207410d565efSmrgexpands to nothing, but in the @code{m68k-coff} environment it expands 207510d565efSmrgto a single @samp{%}. 207610d565efSmrg 207710d565efSmrg@item __USER_LABEL_PREFIX__ 207810d565efSmrgThis macro expands to a single token which is the prefix applied to 207910d565efSmrguser labels (symbols visible to C code) in assembly. For example, in 208010d565efSmrgthe @code{m68k-aout} environment it expands to an @samp{_}, but in the 208110d565efSmrg@code{m68k-coff} environment it expands to nothing. 208210d565efSmrg 208310d565efSmrgThis macro will have the correct definition even if 208410d565efSmrg@option{-f(no-)underscores} is in use, but it will not be correct if 208510d565efSmrgtarget-specific options that adjust this prefix are used (e.g.@: the 208610d565efSmrgOSF/rose @option{-mno-underscores} option). 208710d565efSmrg 208810d565efSmrg@item __SIZE_TYPE__ 208910d565efSmrg@itemx __PTRDIFF_TYPE__ 209010d565efSmrg@itemx __WCHAR_TYPE__ 209110d565efSmrg@itemx __WINT_TYPE__ 209210d565efSmrg@itemx __INTMAX_TYPE__ 209310d565efSmrg@itemx __UINTMAX_TYPE__ 209410d565efSmrg@itemx __SIG_ATOMIC_TYPE__ 209510d565efSmrg@itemx __INT8_TYPE__ 209610d565efSmrg@itemx __INT16_TYPE__ 209710d565efSmrg@itemx __INT32_TYPE__ 209810d565efSmrg@itemx __INT64_TYPE__ 209910d565efSmrg@itemx __UINT8_TYPE__ 210010d565efSmrg@itemx __UINT16_TYPE__ 210110d565efSmrg@itemx __UINT32_TYPE__ 210210d565efSmrg@itemx __UINT64_TYPE__ 210310d565efSmrg@itemx __INT_LEAST8_TYPE__ 210410d565efSmrg@itemx __INT_LEAST16_TYPE__ 210510d565efSmrg@itemx __INT_LEAST32_TYPE__ 210610d565efSmrg@itemx __INT_LEAST64_TYPE__ 210710d565efSmrg@itemx __UINT_LEAST8_TYPE__ 210810d565efSmrg@itemx __UINT_LEAST16_TYPE__ 210910d565efSmrg@itemx __UINT_LEAST32_TYPE__ 211010d565efSmrg@itemx __UINT_LEAST64_TYPE__ 211110d565efSmrg@itemx __INT_FAST8_TYPE__ 211210d565efSmrg@itemx __INT_FAST16_TYPE__ 211310d565efSmrg@itemx __INT_FAST32_TYPE__ 211410d565efSmrg@itemx __INT_FAST64_TYPE__ 211510d565efSmrg@itemx __UINT_FAST8_TYPE__ 211610d565efSmrg@itemx __UINT_FAST16_TYPE__ 211710d565efSmrg@itemx __UINT_FAST32_TYPE__ 211810d565efSmrg@itemx __UINT_FAST64_TYPE__ 211910d565efSmrg@itemx __INTPTR_TYPE__ 212010d565efSmrg@itemx __UINTPTR_TYPE__ 212110d565efSmrgThese macros are defined to the correct underlying types for the 212210d565efSmrg@code{size_t}, @code{ptrdiff_t}, @code{wchar_t}, @code{wint_t}, 212310d565efSmrg@code{intmax_t}, @code{uintmax_t}, @code{sig_atomic_t}, @code{int8_t}, 212410d565efSmrg@code{int16_t}, @code{int32_t}, @code{int64_t}, @code{uint8_t}, 212510d565efSmrg@code{uint16_t}, @code{uint32_t}, @code{uint64_t}, 212610d565efSmrg@code{int_least8_t}, @code{int_least16_t}, @code{int_least32_t}, 212710d565efSmrg@code{int_least64_t}, @code{uint_least8_t}, @code{uint_least16_t}, 212810d565efSmrg@code{uint_least32_t}, @code{uint_least64_t}, @code{int_fast8_t}, 212910d565efSmrg@code{int_fast16_t}, @code{int_fast32_t}, @code{int_fast64_t}, 213010d565efSmrg@code{uint_fast8_t}, @code{uint_fast16_t}, @code{uint_fast32_t}, 213110d565efSmrg@code{uint_fast64_t}, @code{intptr_t}, and @code{uintptr_t} typedefs, 213210d565efSmrgrespectively. They exist to make the standard header files 213310d565efSmrg@file{stddef.h}, @file{stdint.h}, and @file{wchar.h} work correctly. 213410d565efSmrgYou should not use these macros directly; instead, include the 213510d565efSmrgappropriate headers and use the typedefs. Some of these macros may 213610d565efSmrgnot be defined on particular systems if GCC does not provide a 213710d565efSmrg@file{stdint.h} header on those systems. 213810d565efSmrg 213910d565efSmrg@item __CHAR_BIT__ 214010d565efSmrgDefined to the number of bits used in the representation of the 214110d565efSmrg@code{char} data type. It exists to make the standard header given 214210d565efSmrgnumerical limits work correctly. You should not use 214310d565efSmrgthis macro directly; instead, include the appropriate headers. 214410d565efSmrg 214510d565efSmrg@item __SCHAR_MAX__ 214610d565efSmrg@itemx __WCHAR_MAX__ 214710d565efSmrg@itemx __SHRT_MAX__ 214810d565efSmrg@itemx __INT_MAX__ 214910d565efSmrg@itemx __LONG_MAX__ 215010d565efSmrg@itemx __LONG_LONG_MAX__ 215110d565efSmrg@itemx __WINT_MAX__ 215210d565efSmrg@itemx __SIZE_MAX__ 215310d565efSmrg@itemx __PTRDIFF_MAX__ 215410d565efSmrg@itemx __INTMAX_MAX__ 215510d565efSmrg@itemx __UINTMAX_MAX__ 215610d565efSmrg@itemx __SIG_ATOMIC_MAX__ 215710d565efSmrg@itemx __INT8_MAX__ 215810d565efSmrg@itemx __INT16_MAX__ 215910d565efSmrg@itemx __INT32_MAX__ 216010d565efSmrg@itemx __INT64_MAX__ 216110d565efSmrg@itemx __UINT8_MAX__ 216210d565efSmrg@itemx __UINT16_MAX__ 216310d565efSmrg@itemx __UINT32_MAX__ 216410d565efSmrg@itemx __UINT64_MAX__ 216510d565efSmrg@itemx __INT_LEAST8_MAX__ 216610d565efSmrg@itemx __INT_LEAST16_MAX__ 216710d565efSmrg@itemx __INT_LEAST32_MAX__ 216810d565efSmrg@itemx __INT_LEAST64_MAX__ 216910d565efSmrg@itemx __UINT_LEAST8_MAX__ 217010d565efSmrg@itemx __UINT_LEAST16_MAX__ 217110d565efSmrg@itemx __UINT_LEAST32_MAX__ 217210d565efSmrg@itemx __UINT_LEAST64_MAX__ 217310d565efSmrg@itemx __INT_FAST8_MAX__ 217410d565efSmrg@itemx __INT_FAST16_MAX__ 217510d565efSmrg@itemx __INT_FAST32_MAX__ 217610d565efSmrg@itemx __INT_FAST64_MAX__ 217710d565efSmrg@itemx __UINT_FAST8_MAX__ 217810d565efSmrg@itemx __UINT_FAST16_MAX__ 217910d565efSmrg@itemx __UINT_FAST32_MAX__ 218010d565efSmrg@itemx __UINT_FAST64_MAX__ 218110d565efSmrg@itemx __INTPTR_MAX__ 218210d565efSmrg@itemx __UINTPTR_MAX__ 218310d565efSmrg@itemx __WCHAR_MIN__ 218410d565efSmrg@itemx __WINT_MIN__ 218510d565efSmrg@itemx __SIG_ATOMIC_MIN__ 218610d565efSmrgDefined to the maximum value of the @code{signed char}, @code{wchar_t}, 218710d565efSmrg@code{signed short}, 218810d565efSmrg@code{signed int}, @code{signed long}, @code{signed long long}, 218910d565efSmrg@code{wint_t}, @code{size_t}, @code{ptrdiff_t}, 219010d565efSmrg@code{intmax_t}, @code{uintmax_t}, @code{sig_atomic_t}, @code{int8_t}, 219110d565efSmrg@code{int16_t}, @code{int32_t}, @code{int64_t}, @code{uint8_t}, 219210d565efSmrg@code{uint16_t}, @code{uint32_t}, @code{uint64_t}, 219310d565efSmrg@code{int_least8_t}, @code{int_least16_t}, @code{int_least32_t}, 219410d565efSmrg@code{int_least64_t}, @code{uint_least8_t}, @code{uint_least16_t}, 219510d565efSmrg@code{uint_least32_t}, @code{uint_least64_t}, @code{int_fast8_t}, 219610d565efSmrg@code{int_fast16_t}, @code{int_fast32_t}, @code{int_fast64_t}, 219710d565efSmrg@code{uint_fast8_t}, @code{uint_fast16_t}, @code{uint_fast32_t}, 219810d565efSmrg@code{uint_fast64_t}, @code{intptr_t}, and @code{uintptr_t} types and 219910d565efSmrgto the minimum value of the @code{wchar_t}, @code{wint_t}, and 220010d565efSmrg@code{sig_atomic_t} types respectively. They exist to make the 220110d565efSmrgstandard header given numerical limits work correctly. You should not 220210d565efSmrguse these macros directly; instead, include the appropriate headers. 220310d565efSmrgSome of these macros may not be defined on particular systems if GCC 220410d565efSmrgdoes not provide a @file{stdint.h} header on those systems. 220510d565efSmrg 220610d565efSmrg@item __INT8_C 220710d565efSmrg@itemx __INT16_C 220810d565efSmrg@itemx __INT32_C 220910d565efSmrg@itemx __INT64_C 221010d565efSmrg@itemx __UINT8_C 221110d565efSmrg@itemx __UINT16_C 221210d565efSmrg@itemx __UINT32_C 221310d565efSmrg@itemx __UINT64_C 221410d565efSmrg@itemx __INTMAX_C 221510d565efSmrg@itemx __UINTMAX_C 221610d565efSmrgDefined to implementations of the standard @file{stdint.h} macros with 221710d565efSmrgthe same names without the leading @code{__}. They exist the make the 221810d565efSmrgimplementation of that header work correctly. You should not use 221910d565efSmrgthese macros directly; instead, include the appropriate headers. Some 222010d565efSmrgof these macros may not be defined on particular systems if GCC does 222110d565efSmrgnot provide a @file{stdint.h} header on those systems. 222210d565efSmrg 222310d565efSmrg@item __SCHAR_WIDTH__ 222410d565efSmrg@itemx __SHRT_WIDTH__ 222510d565efSmrg@itemx __INT_WIDTH__ 222610d565efSmrg@itemx __LONG_WIDTH__ 222710d565efSmrg@itemx __LONG_LONG_WIDTH__ 222810d565efSmrg@itemx __PTRDIFF_WIDTH__ 222910d565efSmrg@itemx __SIG_ATOMIC_WIDTH__ 223010d565efSmrg@itemx __SIZE_WIDTH__ 223110d565efSmrg@itemx __WCHAR_WIDTH__ 223210d565efSmrg@itemx __WINT_WIDTH__ 223310d565efSmrg@itemx __INT_LEAST8_WIDTH__ 223410d565efSmrg@itemx __INT_LEAST16_WIDTH__ 223510d565efSmrg@itemx __INT_LEAST32_WIDTH__ 223610d565efSmrg@itemx __INT_LEAST64_WIDTH__ 223710d565efSmrg@itemx __INT_FAST8_WIDTH__ 223810d565efSmrg@itemx __INT_FAST16_WIDTH__ 223910d565efSmrg@itemx __INT_FAST32_WIDTH__ 224010d565efSmrg@itemx __INT_FAST64_WIDTH__ 224110d565efSmrg@itemx __INTPTR_WIDTH__ 224210d565efSmrg@itemx __INTMAX_WIDTH__ 224310d565efSmrgDefined to the bit widths of the corresponding types. They exist to 224410d565efSmrgmake the implementations of @file{limits.h} and @file{stdint.h} behave 224510d565efSmrgcorrectly. You should not use these macros directly; instead, include 224610d565efSmrgthe appropriate headers. Some of these macros may not be defined on 224710d565efSmrgparticular systems if GCC does not provide a @file{stdint.h} header on 224810d565efSmrgthose systems. 224910d565efSmrg 225010d565efSmrg@item __SIZEOF_INT__ 225110d565efSmrg@itemx __SIZEOF_LONG__ 225210d565efSmrg@itemx __SIZEOF_LONG_LONG__ 225310d565efSmrg@itemx __SIZEOF_SHORT__ 225410d565efSmrg@itemx __SIZEOF_POINTER__ 225510d565efSmrg@itemx __SIZEOF_FLOAT__ 225610d565efSmrg@itemx __SIZEOF_DOUBLE__ 225710d565efSmrg@itemx __SIZEOF_LONG_DOUBLE__ 225810d565efSmrg@itemx __SIZEOF_SIZE_T__ 225910d565efSmrg@itemx __SIZEOF_WCHAR_T__ 226010d565efSmrg@itemx __SIZEOF_WINT_T__ 226110d565efSmrg@itemx __SIZEOF_PTRDIFF_T__ 226210d565efSmrgDefined to the number of bytes of the C standard data types: @code{int}, 226310d565efSmrg@code{long}, @code{long long}, @code{short}, @code{void *}, @code{float}, 226410d565efSmrg@code{double}, @code{long double}, @code{size_t}, @code{wchar_t}, @code{wint_t} 226510d565efSmrgand @code{ptrdiff_t}. 226610d565efSmrg 226710d565efSmrg@item __BYTE_ORDER__ 226810d565efSmrg@itemx __ORDER_LITTLE_ENDIAN__ 226910d565efSmrg@itemx __ORDER_BIG_ENDIAN__ 227010d565efSmrg@itemx __ORDER_PDP_ENDIAN__ 227110d565efSmrg@code{__BYTE_ORDER__} is defined to one of the values 227210d565efSmrg@code{__ORDER_LITTLE_ENDIAN__}, @code{__ORDER_BIG_ENDIAN__}, or 227310d565efSmrg@code{__ORDER_PDP_ENDIAN__} to reflect the layout of multi-byte and 227410d565efSmrgmulti-word quantities in memory. If @code{__BYTE_ORDER__} is equal to 227510d565efSmrg@code{__ORDER_LITTLE_ENDIAN__} or @code{__ORDER_BIG_ENDIAN__}, then 227610d565efSmrgmulti-byte and multi-word quantities are laid out identically: the 227710d565efSmrgbyte (word) at the lowest address is the least significant or most 227810d565efSmrgsignificant byte (word) of the quantity, respectively. If 227910d565efSmrg@code{__BYTE_ORDER__} is equal to @code{__ORDER_PDP_ENDIAN__}, then 228010d565efSmrgbytes in 16-bit words are laid out in a little-endian fashion, whereas 228110d565efSmrgthe 16-bit subwords of a 32-bit quantity are laid out in big-endian 228210d565efSmrgfashion. 228310d565efSmrg 228410d565efSmrgYou should use these macros for testing like this: 228510d565efSmrg 228610d565efSmrg@smallexample 228710d565efSmrg/* @r{Test for a little-endian machine} */ 228810d565efSmrg#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__ 228910d565efSmrg@end smallexample 229010d565efSmrg 229110d565efSmrg@item __FLOAT_WORD_ORDER__ 229210d565efSmrg@code{__FLOAT_WORD_ORDER__} is defined to one of the values 229310d565efSmrg@code{__ORDER_LITTLE_ENDIAN__} or @code{__ORDER_BIG_ENDIAN__} to reflect 229410d565efSmrgthe layout of the words of multi-word floating-point quantities. 229510d565efSmrg 229610d565efSmrg@item __DEPRECATED 229710d565efSmrgThis macro is defined, with value 1, when compiling a C++ source file 229810d565efSmrgwith warnings about deprecated constructs enabled. These warnings are 229910d565efSmrgenabled by default, but can be disabled with @option{-Wno-deprecated}. 230010d565efSmrg 230110d565efSmrg@item __EXCEPTIONS 230210d565efSmrgThis macro is defined, with value 1, when compiling a C++ source file 230310d565efSmrgwith exceptions enabled. If @option{-fno-exceptions} is used when 230410d565efSmrgcompiling the file, then this macro is not defined. 230510d565efSmrg 230610d565efSmrg@item __GXX_RTTI 230710d565efSmrgThis macro is defined, with value 1, when compiling a C++ source file 230810d565efSmrgwith runtime type identification enabled. If @option{-fno-rtti} is 230910d565efSmrgused when compiling the file, then this macro is not defined. 231010d565efSmrg 231110d565efSmrg@item __USING_SJLJ_EXCEPTIONS__ 231210d565efSmrgThis macro is defined, with value 1, if the compiler uses the old 231310d565efSmrgmechanism based on @code{setjmp} and @code{longjmp} for exception 231410d565efSmrghandling. 231510d565efSmrg 231610d565efSmrg@item __GXX_EXPERIMENTAL_CXX0X__ 2317*ec02198aSmrgThis macro is defined when compiling a C++ source file with C++11 features 2318*ec02198aSmrgenabled, i.e., for all C++ language dialects except @option{-std=c++98} 2319*ec02198aSmrgand @option{-std=gnu++98}. This macro is obsolete, but can be used to 2320*ec02198aSmrgdetect experimental C++0x features in very old versions of GCC. Since 2321*ec02198aSmrgGCC 4.7.0 the @code{__cplusplus} macro is defined correctly, so most 2322*ec02198aSmrgcode should test @code{__cplusplus >= 201103L} instead of using this 2323*ec02198aSmrgmacro. 232410d565efSmrg 232510d565efSmrg@item __GXX_WEAK__ 232610d565efSmrgThis macro is defined when compiling a C++ source file. It has the 232710d565efSmrgvalue 1 if the compiler will use weak symbols, COMDAT sections, or 232810d565efSmrgother similar techniques to collapse symbols with ``vague linkage'' 232910d565efSmrgthat are defined in multiple translation units. If the compiler will 233010d565efSmrgnot collapse such symbols, this macro is defined with value 0. In 233110d565efSmrggeneral, user code should not need to make use of this macro; the 233210d565efSmrgpurpose of this macro is to ease implementation of the C++ runtime 233310d565efSmrglibrary provided with G++. 233410d565efSmrg 233510d565efSmrg@item __NEXT_RUNTIME__ 233610d565efSmrgThis macro is defined, with value 1, if (and only if) the NeXT runtime 233710d565efSmrg(as in @option{-fnext-runtime}) is in use for Objective-C@. If the GNU 233810d565efSmrgruntime is used, this macro is not defined, so that you can use this 233910d565efSmrgmacro to determine which runtime (NeXT or GNU) is being used. 234010d565efSmrg 234110d565efSmrg@item __LP64__ 234210d565efSmrg@itemx _LP64 234310d565efSmrgThese macros are defined, with value 1, if (and only if) the compilation 234410d565efSmrgis for a target where @code{long int} and pointer both use 64-bits and 234510d565efSmrg@code{int} uses 32-bit. 234610d565efSmrg 234710d565efSmrg@item __SSP__ 234810d565efSmrgThis macro is defined, with value 1, when @option{-fstack-protector} is in 234910d565efSmrguse. 235010d565efSmrg 235110d565efSmrg@item __SSP_ALL__ 235210d565efSmrgThis macro is defined, with value 2, when @option{-fstack-protector-all} is 235310d565efSmrgin use. 235410d565efSmrg 235510d565efSmrg@item __SSP_STRONG__ 235610d565efSmrgThis macro is defined, with value 3, when @option{-fstack-protector-strong} is 235710d565efSmrgin use. 235810d565efSmrg 235910d565efSmrg@item __SSP_EXPLICIT__ 236010d565efSmrgThis macro is defined, with value 4, when @option{-fstack-protector-explicit} is 236110d565efSmrgin use. 236210d565efSmrg 236310d565efSmrg@item __SANITIZE_ADDRESS__ 236410d565efSmrgThis macro is defined, with value 1, when @option{-fsanitize=address} 236510d565efSmrgor @option{-fsanitize=kernel-address} are in use. 236610d565efSmrg 236710d565efSmrg@item __SANITIZE_THREAD__ 236810d565efSmrgThis macro is defined, with value 1, when @option{-fsanitize=thread} is in use. 236910d565efSmrg 237010d565efSmrg@item __TIMESTAMP__ 237110d565efSmrgThis macro expands to a string constant that describes the date and time 237210d565efSmrgof the last modification of the current source file. The string constant 237310d565efSmrgcontains abbreviated day of the week, month, day of the month, time in 237410d565efSmrghh:mm:ss form, year and looks like @code{@w{"Sun Sep 16 01:03:52 1973"}}. 237510d565efSmrgIf the day of the month is less than 10, it is padded with a space on the left. 237610d565efSmrg 237710d565efSmrgIf GCC cannot determine the current date, it will emit a warning message 237810d565efSmrg(once per compilation) and @code{__TIMESTAMP__} will expand to 237910d565efSmrg@code{@w{"??? ??? ?? ??:??:?? ????"}}. 238010d565efSmrg 238110d565efSmrg@item __GCC_HAVE_SYNC_COMPARE_AND_SWAP_1 238210d565efSmrg@itemx __GCC_HAVE_SYNC_COMPARE_AND_SWAP_2 238310d565efSmrg@itemx __GCC_HAVE_SYNC_COMPARE_AND_SWAP_4 238410d565efSmrg@itemx __GCC_HAVE_SYNC_COMPARE_AND_SWAP_8 238510d565efSmrg@itemx __GCC_HAVE_SYNC_COMPARE_AND_SWAP_16 238610d565efSmrgThese macros are defined when the target processor supports atomic compare 238710d565efSmrgand swap operations on operands 1, 2, 4, 8 or 16 bytes in length, respectively. 238810d565efSmrg 23890fc04c29Smrg@item __HAVE_SPECULATION_SAFE_VALUE 23900fc04c29SmrgThis macro is defined with the value 1 to show that this version of GCC 23910fc04c29Smrgsupports @code{__builtin_speculation_safe_value}. 23920fc04c29Smrg 239310d565efSmrg@item __GCC_HAVE_DWARF2_CFI_ASM 239410d565efSmrgThis macro is defined when the compiler is emitting DWARF CFI directives 239510d565efSmrgto the assembler. When this is defined, it is possible to emit those same 239610d565efSmrgdirectives in inline assembly. 239710d565efSmrg 239810d565efSmrg@item __FP_FAST_FMA 239910d565efSmrg@itemx __FP_FAST_FMAF 240010d565efSmrg@itemx __FP_FAST_FMAL 240110d565efSmrgThese macros are defined with value 1 if the backend supports the 240210d565efSmrg@code{fma}, @code{fmaf}, and @code{fmal} builtin functions, so that 240310d565efSmrgthe include file @file{math.h} can define the macros 240410d565efSmrg@code{FP_FAST_FMA}, @code{FP_FAST_FMAF}, and @code{FP_FAST_FMAL} 240510d565efSmrgfor compatibility with the 1999 C standard. 240610d565efSmrg 2407c7a68eb7Smrg@item __FP_FAST_FMAF16 2408c7a68eb7Smrg@itemx __FP_FAST_FMAF32 2409c7a68eb7Smrg@itemx __FP_FAST_FMAF64 2410c7a68eb7Smrg@itemx __FP_FAST_FMAF128 2411c7a68eb7Smrg@itemx __FP_FAST_FMAF32X 2412c7a68eb7Smrg@itemx __FP_FAST_FMAF64X 2413c7a68eb7Smrg@itemx __FP_FAST_FMAF128X 2414c7a68eb7SmrgThese macros are defined with the value 1 if the backend supports the 2415c7a68eb7Smrg@code{fma} functions using the additional @code{_Float@var{n}} and 2416c7a68eb7Smrg@code{_Float@var{n}x} types that are defined in ISO/IEC TS 2417c7a68eb7Smrg18661-3:2015. The include file @file{math.h} can define the 2418c7a68eb7Smrg@code{FP_FAST_FMAF@var{n}} and @code{FP_FAST_FMAF@var{n}x} macros if 2419c7a68eb7Smrgthe user defined @code{__STDC_WANT_IEC_60559_TYPES_EXT__} before 2420c7a68eb7Smrgincluding @file{math.h}. 2421c7a68eb7Smrg 242210d565efSmrg@item __GCC_IEC_559 242310d565efSmrgThis macro is defined to indicate the intended level of support for 242410d565efSmrgIEEE 754 (IEC 60559) floating-point arithmetic. It expands to a 242510d565efSmrgnonnegative integer value. If 0, it indicates that the combination of 242610d565efSmrgthe compiler configuration and the command-line options is not 242710d565efSmrgintended to support IEEE 754 arithmetic for @code{float} and 242810d565efSmrg@code{double} as defined in C99 and C11 Annex F (for example, that the 242910d565efSmrgstandard rounding modes and exceptions are not supported, or that 243010d565efSmrgoptimizations are enabled that conflict with IEEE 754 semantics). If 243110d565efSmrg1, it indicates that IEEE 754 arithmetic is intended to be supported; 243210d565efSmrgthis does not mean that all relevant language features are supported 243310d565efSmrgby GCC. If 2 or more, it additionally indicates support for IEEE 243410d565efSmrg754-2008 (in particular, that the binary encodings for quiet and 243510d565efSmrgsignaling NaNs are as specified in IEEE 754-2008). 243610d565efSmrg 243710d565efSmrgThis macro does not indicate the default state of command-line options 243810d565efSmrgthat control optimizations that C99 and C11 permit to be controlled by 243910d565efSmrgstandard pragmas, where those standards do not require a particular 244010d565efSmrgdefault state. It does not indicate whether optimizations respect 244110d565efSmrgsignaling NaN semantics (the macro for that is 244210d565efSmrg@code{__SUPPORT_SNAN__}). It does not indicate support for decimal 244310d565efSmrgfloating point or the IEEE 754 binary16 and binary128 types. 244410d565efSmrg 244510d565efSmrg@item __GCC_IEC_559_COMPLEX 244610d565efSmrgThis macro is defined to indicate the intended level of support for 244710d565efSmrgIEEE 754 (IEC 60559) floating-point arithmetic for complex numbers, as 244810d565efSmrgdefined in C99 and C11 Annex G. It expands to a nonnegative integer 244910d565efSmrgvalue. If 0, it indicates that the combination of the compiler 245010d565efSmrgconfiguration and the command-line options is not intended to support 245110d565efSmrgAnnex G requirements (for example, because @option{-fcx-limited-range} 245210d565efSmrgwas used). If 1 or more, it indicates that it is intended to support 245310d565efSmrgthose requirements; this does not mean that all relevant language 245410d565efSmrgfeatures are supported by GCC. 245510d565efSmrg 245610d565efSmrg@item __NO_MATH_ERRNO__ 245710d565efSmrgThis macro is defined if @option{-fno-math-errno} is used, or enabled 245810d565efSmrgby another option such as @option{-ffast-math} or by default. 245910d565efSmrg@end table 246010d565efSmrg 246110d565efSmrg@node System-specific Predefined Macros 246210d565efSmrg@subsection System-specific Predefined Macros 246310d565efSmrg 246410d565efSmrg@cindex system-specific predefined macros 246510d565efSmrg@cindex predefined macros, system-specific 246610d565efSmrg@cindex reserved namespace 246710d565efSmrg 246810d565efSmrgThe C preprocessor normally predefines several macros that indicate what 246910d565efSmrgtype of system and machine is in use. They are obviously different on 247010d565efSmrgeach target supported by GCC@. This manual, being for all systems and 247110d565efSmrgmachines, cannot tell you what their names are, but you can use 247210d565efSmrg@command{cpp -dM} to see them all. @xref{Invocation}. All system-specific 247310d565efSmrgpredefined macros expand to a constant value, so you can test them with 247410d565efSmrgeither @samp{#ifdef} or @samp{#if}. 247510d565efSmrg 247610d565efSmrgThe C standard requires that all system-specific macros be part of the 247710d565efSmrg@dfn{reserved namespace}. All names which begin with two underscores, 247810d565efSmrgor an underscore and a capital letter, are reserved for the compiler and 247910d565efSmrglibrary to use as they wish. However, historically system-specific 248010d565efSmrgmacros have had names with no special prefix; for instance, it is common 248110d565efSmrgto find @code{unix} defined on Unix systems. For all such macros, GCC 248210d565efSmrgprovides a parallel macro with two underscores added at the beginning 248310d565efSmrgand the end. If @code{unix} is defined, @code{__unix__} will be defined 248410d565efSmrgtoo. There will never be more than two underscores; the parallel of 248510d565efSmrg@code{_mips} is @code{__mips__}. 248610d565efSmrg 248710d565efSmrgWhen the @option{-ansi} option, or any @option{-std} option that 248810d565efSmrgrequests strict conformance, is given to the compiler, all the 248910d565efSmrgsystem-specific predefined macros outside the reserved namespace are 249010d565efSmrgsuppressed. The parallel macros, inside the reserved namespace, remain 249110d565efSmrgdefined. 249210d565efSmrg 249310d565efSmrgWe are slowly phasing out all predefined macros which are outside the 249410d565efSmrgreserved namespace. You should never use them in new programs, and we 249510d565efSmrgencourage you to correct older code to use the parallel macros whenever 249610d565efSmrgyou find it. We don't recommend you use the system-specific macros that 249710d565efSmrgare in the reserved namespace, either. It is better in the long run to 249810d565efSmrgcheck specifically for features you need, using a tool such as 249910d565efSmrg@command{autoconf}. 250010d565efSmrg 250110d565efSmrg@node C++ Named Operators 250210d565efSmrg@subsection C++ Named Operators 250310d565efSmrg@cindex named operators 250410d565efSmrg@cindex C++ named operators 250510d565efSmrg@cindex @file{iso646.h} 250610d565efSmrg 250710d565efSmrgIn C++, there are eleven keywords which are simply alternate spellings 250810d565efSmrgof operators normally written with punctuation. These keywords are 250910d565efSmrgtreated as such even in the preprocessor. They function as operators in 251010d565efSmrg@samp{#if}, and they cannot be defined as macros or poisoned. In C, you 251110d565efSmrgcan request that those keywords take their C++ meaning by including 251210d565efSmrg@file{iso646.h}. That header defines each one as a normal object-like 251310d565efSmrgmacro expanding to the appropriate punctuator. 251410d565efSmrg 251510d565efSmrgThese are the named operators and their corresponding punctuators: 251610d565efSmrg 251710d565efSmrg@multitable {Named Operator} {Punctuator} 251810d565efSmrg@item Named Operator @tab Punctuator 251910d565efSmrg@item @code{and} @tab @code{&&} 252010d565efSmrg@item @code{and_eq} @tab @code{&=} 252110d565efSmrg@item @code{bitand} @tab @code{&} 252210d565efSmrg@item @code{bitor} @tab @code{|} 252310d565efSmrg@item @code{compl} @tab @code{~} 252410d565efSmrg@item @code{not} @tab @code{!} 252510d565efSmrg@item @code{not_eq} @tab @code{!=} 252610d565efSmrg@item @code{or} @tab @code{||} 252710d565efSmrg@item @code{or_eq} @tab @code{|=} 252810d565efSmrg@item @code{xor} @tab @code{^} 252910d565efSmrg@item @code{xor_eq} @tab @code{^=} 253010d565efSmrg@end multitable 253110d565efSmrg 253210d565efSmrg@node Undefining and Redefining Macros 253310d565efSmrg@section Undefining and Redefining Macros 253410d565efSmrg@cindex undefining macros 253510d565efSmrg@cindex redefining macros 253610d565efSmrg@findex #undef 253710d565efSmrg 253810d565efSmrgIf a macro ceases to be useful, it may be @dfn{undefined} with the 253910d565efSmrg@samp{#undef} directive. @samp{#undef} takes a single argument, the 254010d565efSmrgname of the macro to undefine. You use the bare macro name, even if the 254110d565efSmrgmacro is function-like. It is an error if anything appears on the line 254210d565efSmrgafter the macro name. @samp{#undef} has no effect if the name is not a 254310d565efSmrgmacro. 254410d565efSmrg 254510d565efSmrg@smallexample 254610d565efSmrg#define FOO 4 254710d565efSmrgx = FOO; @expansion{} x = 4; 254810d565efSmrg#undef FOO 254910d565efSmrgx = FOO; @expansion{} x = FOO; 255010d565efSmrg@end smallexample 255110d565efSmrg 255210d565efSmrgOnce a macro has been undefined, that identifier may be @dfn{redefined} 255310d565efSmrgas a macro by a subsequent @samp{#define} directive. The new definition 255410d565efSmrgneed not have any resemblance to the old definition. 255510d565efSmrg 255610d565efSmrgHowever, if an identifier which is currently a macro is redefined, then 255710d565efSmrgthe new definition must be @dfn{effectively the same} as the old one. 255810d565efSmrgTwo macro definitions are effectively the same if: 255910d565efSmrg@itemize @bullet 256010d565efSmrg@item Both are the same type of macro (object- or function-like). 256110d565efSmrg@item All the tokens of the replacement list are the same. 256210d565efSmrg@item If there are any parameters, they are the same. 256310d565efSmrg@item Whitespace appears in the same places in both. It need not be 256410d565efSmrgexactly the same amount of whitespace, though. Remember that comments 256510d565efSmrgcount as whitespace. 256610d565efSmrg@end itemize 256710d565efSmrg 256810d565efSmrg@noindent 256910d565efSmrgThese definitions are effectively the same: 257010d565efSmrg@smallexample 257110d565efSmrg#define FOUR (2 + 2) 257210d565efSmrg#define FOUR (2 + 2) 257310d565efSmrg#define FOUR (2 /* @r{two} */ + 2) 257410d565efSmrg@end smallexample 257510d565efSmrg@noindent 257610d565efSmrgbut these are not: 257710d565efSmrg@smallexample 257810d565efSmrg#define FOUR (2 + 2) 257910d565efSmrg#define FOUR ( 2+2 ) 258010d565efSmrg#define FOUR (2 * 2) 258110d565efSmrg#define FOUR(score,and,seven,years,ago) (2 + 2) 258210d565efSmrg@end smallexample 258310d565efSmrg 258410d565efSmrgIf a macro is redefined with a definition that is not effectively the 258510d565efSmrgsame as the old one, the preprocessor issues a warning and changes the 258610d565efSmrgmacro to use the new definition. If the new definition is effectively 258710d565efSmrgthe same, the redefinition is silently ignored. This allows, for 258810d565efSmrginstance, two different headers to define a common macro. The 258910d565efSmrgpreprocessor will only complain if the definitions do not match. 259010d565efSmrg 259110d565efSmrg@node Directives Within Macro Arguments 259210d565efSmrg@section Directives Within Macro Arguments 259310d565efSmrg@cindex macro arguments and directives 259410d565efSmrg 259510d565efSmrgOccasionally it is convenient to use preprocessor directives within 259610d565efSmrgthe arguments of a macro. The C and C++ standards declare that 259710d565efSmrgbehavior in these cases is undefined. GNU CPP 259810d565efSmrgprocesses arbitrary directives within macro arguments in 259910d565efSmrgexactly the same way as it would have processed the directive were the 260010d565efSmrgfunction-like macro invocation not present. 260110d565efSmrg 260210d565efSmrgIf, within a macro invocation, that macro is redefined, then the new 260310d565efSmrgdefinition takes effect in time for argument pre-expansion, but the 260410d565efSmrgoriginal definition is still used for argument replacement. Here is a 260510d565efSmrgpathological example: 260610d565efSmrg 260710d565efSmrg@smallexample 260810d565efSmrg#define f(x) x x 260910d565efSmrgf (1 261010d565efSmrg#undef f 261110d565efSmrg#define f 2 261210d565efSmrgf) 261310d565efSmrg@end smallexample 261410d565efSmrg 261510d565efSmrg@noindent 261610d565efSmrgwhich expands to 261710d565efSmrg 261810d565efSmrg@smallexample 261910d565efSmrg1 2 1 2 262010d565efSmrg@end smallexample 262110d565efSmrg 262210d565efSmrg@noindent 262310d565efSmrgwith the semantics described above. 262410d565efSmrg 262510d565efSmrg@node Macro Pitfalls 262610d565efSmrg@section Macro Pitfalls 262710d565efSmrg@cindex problems with macros 262810d565efSmrg@cindex pitfalls of macros 262910d565efSmrg 263010d565efSmrgIn this section we describe some special rules that apply to macros and 263110d565efSmrgmacro expansion, and point out certain cases in which the rules have 263210d565efSmrgcounter-intuitive consequences that you must watch out for. 263310d565efSmrg 263410d565efSmrg@menu 263510d565efSmrg* Misnesting:: 263610d565efSmrg* Operator Precedence Problems:: 263710d565efSmrg* Swallowing the Semicolon:: 263810d565efSmrg* Duplication of Side Effects:: 263910d565efSmrg* Self-Referential Macros:: 264010d565efSmrg* Argument Prescan:: 264110d565efSmrg* Newlines in Arguments:: 264210d565efSmrg@end menu 264310d565efSmrg 264410d565efSmrg@node Misnesting 264510d565efSmrg@subsection Misnesting 264610d565efSmrg 264710d565efSmrgWhen a macro is called with arguments, the arguments are substituted 264810d565efSmrginto the macro body and the result is checked, together with the rest of 264910d565efSmrgthe input file, for more macro calls. It is possible to piece together 265010d565efSmrga macro call coming partially from the macro body and partially from the 265110d565efSmrgarguments. For example, 265210d565efSmrg 265310d565efSmrg@smallexample 265410d565efSmrg#define twice(x) (2*(x)) 265510d565efSmrg#define call_with_1(x) x(1) 265610d565efSmrgcall_with_1 (twice) 265710d565efSmrg @expansion{} twice(1) 265810d565efSmrg @expansion{} (2*(1)) 265910d565efSmrg@end smallexample 266010d565efSmrg 266110d565efSmrgMacro definitions do not have to have balanced parentheses. By writing 266210d565efSmrgan unbalanced open parenthesis in a macro body, it is possible to create 266310d565efSmrga macro call that begins inside the macro body but ends outside of it. 266410d565efSmrgFor example, 266510d565efSmrg 266610d565efSmrg@smallexample 266710d565efSmrg#define strange(file) fprintf (file, "%s %d", 266810d565efSmrg@dots{} 266910d565efSmrgstrange(stderr) p, 35) 267010d565efSmrg @expansion{} fprintf (stderr, "%s %d", p, 35) 267110d565efSmrg@end smallexample 267210d565efSmrg 267310d565efSmrgThe ability to piece together a macro call can be useful, but the use of 267410d565efSmrgunbalanced open parentheses in a macro body is just confusing, and 267510d565efSmrgshould be avoided. 267610d565efSmrg 267710d565efSmrg@node Operator Precedence Problems 267810d565efSmrg@subsection Operator Precedence Problems 267910d565efSmrg@cindex parentheses in macro bodies 268010d565efSmrg 268110d565efSmrgYou may have noticed that in most of the macro definition examples shown 268210d565efSmrgabove, each occurrence of a macro argument name had parentheses around 268310d565efSmrgit. In addition, another pair of parentheses usually surround the 268410d565efSmrgentire macro definition. Here is why it is best to write macros that 268510d565efSmrgway. 268610d565efSmrg 268710d565efSmrgSuppose you define a macro as follows, 268810d565efSmrg 268910d565efSmrg@smallexample 269010d565efSmrg#define ceil_div(x, y) (x + y - 1) / y 269110d565efSmrg@end smallexample 269210d565efSmrg 269310d565efSmrg@noindent 269410d565efSmrgwhose purpose is to divide, rounding up. (One use for this operation is 269510d565efSmrgto compute how many @code{int} objects are needed to hold a certain 269610d565efSmrgnumber of @code{char} objects.) Then suppose it is used as follows: 269710d565efSmrg 269810d565efSmrg@smallexample 269910d565efSmrga = ceil_div (b & c, sizeof (int)); 270010d565efSmrg @expansion{} a = (b & c + sizeof (int) - 1) / sizeof (int); 270110d565efSmrg@end smallexample 270210d565efSmrg 270310d565efSmrg@noindent 270410d565efSmrgThis does not do what is intended. The operator-precedence rules of 270510d565efSmrgC make it equivalent to this: 270610d565efSmrg 270710d565efSmrg@smallexample 270810d565efSmrga = (b & (c + sizeof (int) - 1)) / sizeof (int); 270910d565efSmrg@end smallexample 271010d565efSmrg 271110d565efSmrg@noindent 271210d565efSmrgWhat we want is this: 271310d565efSmrg 271410d565efSmrg@smallexample 271510d565efSmrga = ((b & c) + sizeof (int) - 1)) / sizeof (int); 271610d565efSmrg@end smallexample 271710d565efSmrg 271810d565efSmrg@noindent 271910d565efSmrgDefining the macro as 272010d565efSmrg 272110d565efSmrg@smallexample 272210d565efSmrg#define ceil_div(x, y) ((x) + (y) - 1) / (y) 272310d565efSmrg@end smallexample 272410d565efSmrg 272510d565efSmrg@noindent 272610d565efSmrgprovides the desired result. 272710d565efSmrg 272810d565efSmrgUnintended grouping can result in another way. Consider @code{sizeof 272910d565efSmrgceil_div(1, 2)}. That has the appearance of a C expression that would 273010d565efSmrgcompute the size of the type of @code{ceil_div (1, 2)}, but in fact it 273110d565efSmrgmeans something very different. Here is what it expands to: 273210d565efSmrg 273310d565efSmrg@smallexample 273410d565efSmrgsizeof ((1) + (2) - 1) / (2) 273510d565efSmrg@end smallexample 273610d565efSmrg 273710d565efSmrg@noindent 273810d565efSmrgThis would take the size of an integer and divide it by two. The 273910d565efSmrgprecedence rules have put the division outside the @code{sizeof} when it 274010d565efSmrgwas intended to be inside. 274110d565efSmrg 274210d565efSmrgParentheses around the entire macro definition prevent such problems. 274310d565efSmrgHere, then, is the recommended way to define @code{ceil_div}: 274410d565efSmrg 274510d565efSmrg@smallexample 274610d565efSmrg#define ceil_div(x, y) (((x) + (y) - 1) / (y)) 274710d565efSmrg@end smallexample 274810d565efSmrg 274910d565efSmrg@node Swallowing the Semicolon 275010d565efSmrg@subsection Swallowing the Semicolon 275110d565efSmrg@cindex semicolons (after macro calls) 275210d565efSmrg 275310d565efSmrgOften it is desirable to define a macro that expands into a compound 275410d565efSmrgstatement. Consider, for example, the following macro, that advances a 275510d565efSmrgpointer (the argument @code{p} says where to find it) across whitespace 275610d565efSmrgcharacters: 275710d565efSmrg 275810d565efSmrg@smallexample 275910d565efSmrg#define SKIP_SPACES(p, limit) \ 276010d565efSmrg@{ char *lim = (limit); \ 276110d565efSmrg while (p < lim) @{ \ 276210d565efSmrg if (*p++ != ' ') @{ \ 276310d565efSmrg p--; break; @}@}@} 276410d565efSmrg@end smallexample 276510d565efSmrg 276610d565efSmrg@noindent 276710d565efSmrgHere backslash-newline is used to split the macro definition, which must 276810d565efSmrgbe a single logical line, so that it resembles the way such code would 276910d565efSmrgbe laid out if not part of a macro definition. 277010d565efSmrg 277110d565efSmrgA call to this macro might be @code{SKIP_SPACES (p, lim)}. Strictly 277210d565efSmrgspeaking, the call expands to a compound statement, which is a complete 277310d565efSmrgstatement with no need for a semicolon to end it. However, since it 277410d565efSmrglooks like a function call, it minimizes confusion if you can use it 277510d565efSmrglike a function call, writing a semicolon afterward, as in 277610d565efSmrg@code{SKIP_SPACES (p, lim);} 277710d565efSmrg 277810d565efSmrgThis can cause trouble before @code{else} statements, because the 277910d565efSmrgsemicolon is actually a null statement. Suppose you write 278010d565efSmrg 278110d565efSmrg@smallexample 278210d565efSmrgif (*p != 0) 278310d565efSmrg SKIP_SPACES (p, lim); 278410d565efSmrgelse @dots{} 278510d565efSmrg@end smallexample 278610d565efSmrg 278710d565efSmrg@noindent 278810d565efSmrgThe presence of two statements---the compound statement and a null 278910d565efSmrgstatement---in between the @code{if} condition and the @code{else} 279010d565efSmrgmakes invalid C code. 279110d565efSmrg 279210d565efSmrgThe definition of the macro @code{SKIP_SPACES} can be altered to solve 279310d565efSmrgthis problem, using a @code{do @dots{} while} statement. Here is how: 279410d565efSmrg 279510d565efSmrg@smallexample 279610d565efSmrg#define SKIP_SPACES(p, limit) \ 279710d565efSmrgdo @{ char *lim = (limit); \ 279810d565efSmrg while (p < lim) @{ \ 279910d565efSmrg if (*p++ != ' ') @{ \ 280010d565efSmrg p--; break; @}@}@} \ 280110d565efSmrgwhile (0) 280210d565efSmrg@end smallexample 280310d565efSmrg 280410d565efSmrgNow @code{SKIP_SPACES (p, lim);} expands into 280510d565efSmrg 280610d565efSmrg@smallexample 280710d565efSmrgdo @{@dots{}@} while (0); 280810d565efSmrg@end smallexample 280910d565efSmrg 281010d565efSmrg@noindent 281110d565efSmrgwhich is one statement. The loop executes exactly once; most compilers 281210d565efSmrggenerate no extra code for it. 281310d565efSmrg 281410d565efSmrg@node Duplication of Side Effects 281510d565efSmrg@subsection Duplication of Side Effects 281610d565efSmrg 281710d565efSmrg@cindex side effects (in macro arguments) 281810d565efSmrg@cindex unsafe macros 281910d565efSmrgMany C programs define a macro @code{min}, for ``minimum'', like this: 282010d565efSmrg 282110d565efSmrg@smallexample 282210d565efSmrg#define min(X, Y) ((X) < (Y) ? (X) : (Y)) 282310d565efSmrg@end smallexample 282410d565efSmrg 282510d565efSmrgWhen you use this macro with an argument containing a side effect, 282610d565efSmrgas shown here, 282710d565efSmrg 282810d565efSmrg@smallexample 282910d565efSmrgnext = min (x + y, foo (z)); 283010d565efSmrg@end smallexample 283110d565efSmrg 283210d565efSmrg@noindent 283310d565efSmrgit expands as follows: 283410d565efSmrg 283510d565efSmrg@smallexample 283610d565efSmrgnext = ((x + y) < (foo (z)) ? (x + y) : (foo (z))); 283710d565efSmrg@end smallexample 283810d565efSmrg 283910d565efSmrg@noindent 284010d565efSmrgwhere @code{x + y} has been substituted for @code{X} and @code{foo (z)} 284110d565efSmrgfor @code{Y}. 284210d565efSmrg 284310d565efSmrgThe function @code{foo} is used only once in the statement as it appears 284410d565efSmrgin the program, but the expression @code{foo (z)} has been substituted 284510d565efSmrgtwice into the macro expansion. As a result, @code{foo} might be called 284610d565efSmrgtwo times when the statement is executed. If it has side effects or if 284710d565efSmrgit takes a long time to compute, the results might not be what you 284810d565efSmrgintended. We say that @code{min} is an @dfn{unsafe} macro. 284910d565efSmrg 285010d565efSmrgThe best solution to this problem is to define @code{min} in a way that 285110d565efSmrgcomputes the value of @code{foo (z)} only once. The C language offers 285210d565efSmrgno standard way to do this, but it can be done with GNU extensions as 285310d565efSmrgfollows: 285410d565efSmrg 285510d565efSmrg@smallexample 285610d565efSmrg#define min(X, Y) \ 285710d565efSmrg(@{ typeof (X) x_ = (X); \ 285810d565efSmrg typeof (Y) y_ = (Y); \ 285910d565efSmrg (x_ < y_) ? x_ : y_; @}) 286010d565efSmrg@end smallexample 286110d565efSmrg 286210d565efSmrgThe @samp{(@{ @dots{} @})} notation produces a compound statement that 286310d565efSmrgacts as an expression. Its value is the value of its last statement. 286410d565efSmrgThis permits us to define local variables and assign each argument to 286510d565efSmrgone. The local variables have underscores after their names to reduce 286610d565efSmrgthe risk of conflict with an identifier of wider scope (it is impossible 286710d565efSmrgto avoid this entirely). Now each argument is evaluated exactly once. 286810d565efSmrg 286910d565efSmrgIf you do not wish to use GNU C extensions, the only solution is to be 287010d565efSmrgcareful when @emph{using} the macro @code{min}. For example, you can 287110d565efSmrgcalculate the value of @code{foo (z)}, save it in a variable, and use 287210d565efSmrgthat variable in @code{min}: 287310d565efSmrg 287410d565efSmrg@smallexample 287510d565efSmrg@group 287610d565efSmrg#define min(X, Y) ((X) < (Y) ? (X) : (Y)) 287710d565efSmrg@dots{} 287810d565efSmrg@{ 287910d565efSmrg int tem = foo (z); 288010d565efSmrg next = min (x + y, tem); 288110d565efSmrg@} 288210d565efSmrg@end group 288310d565efSmrg@end smallexample 288410d565efSmrg 288510d565efSmrg@noindent 288610d565efSmrg(where we assume that @code{foo} returns type @code{int}). 288710d565efSmrg 288810d565efSmrg@node Self-Referential Macros 288910d565efSmrg@subsection Self-Referential Macros 289010d565efSmrg@cindex self-reference 289110d565efSmrg 289210d565efSmrgA @dfn{self-referential} macro is one whose name appears in its 289310d565efSmrgdefinition. Recall that all macro definitions are rescanned for more 289410d565efSmrgmacros to replace. If the self-reference were considered a use of the 289510d565efSmrgmacro, it would produce an infinitely large expansion. To prevent this, 289610d565efSmrgthe self-reference is not considered a macro call. It is passed into 289710d565efSmrgthe preprocessor output unchanged. Consider an example: 289810d565efSmrg 289910d565efSmrg@smallexample 290010d565efSmrg#define foo (4 + foo) 290110d565efSmrg@end smallexample 290210d565efSmrg 290310d565efSmrg@noindent 290410d565efSmrgwhere @code{foo} is also a variable in your program. 290510d565efSmrg 290610d565efSmrgFollowing the ordinary rules, each reference to @code{foo} will expand 290710d565efSmrginto @code{(4 + foo)}; then this will be rescanned and will expand into 290810d565efSmrg@code{(4 + (4 + foo))}; and so on until the computer runs out of memory. 290910d565efSmrg 291010d565efSmrgThe self-reference rule cuts this process short after one step, at 291110d565efSmrg@code{(4 + foo)}. Therefore, this macro definition has the possibly 291210d565efSmrguseful effect of causing the program to add 4 to the value of @code{foo} 291310d565efSmrgwherever @code{foo} is referred to. 291410d565efSmrg 291510d565efSmrgIn most cases, it is a bad idea to take advantage of this feature. A 291610d565efSmrgperson reading the program who sees that @code{foo} is a variable will 291710d565efSmrgnot expect that it is a macro as well. The reader will come across the 291810d565efSmrgidentifier @code{foo} in the program and think its value should be that 291910d565efSmrgof the variable @code{foo}, whereas in fact the value is four greater. 292010d565efSmrg 292110d565efSmrgOne common, useful use of self-reference is to create a macro which 292210d565efSmrgexpands to itself. If you write 292310d565efSmrg 292410d565efSmrg@smallexample 292510d565efSmrg#define EPERM EPERM 292610d565efSmrg@end smallexample 292710d565efSmrg 292810d565efSmrg@noindent 292910d565efSmrgthen the macro @code{EPERM} expands to @code{EPERM}. Effectively, it is 293010d565efSmrgleft alone by the preprocessor whenever it's used in running text. You 293110d565efSmrgcan tell that it's a macro with @samp{#ifdef}. You might do this if you 293210d565efSmrgwant to define numeric constants with an @code{enum}, but have 293310d565efSmrg@samp{#ifdef} be true for each constant. 293410d565efSmrg 293510d565efSmrgIf a macro @code{x} expands to use a macro @code{y}, and the expansion of 293610d565efSmrg@code{y} refers to the macro @code{x}, that is an @dfn{indirect 293710d565efSmrgself-reference} of @code{x}. @code{x} is not expanded in this case 293810d565efSmrgeither. Thus, if we have 293910d565efSmrg 294010d565efSmrg@smallexample 294110d565efSmrg#define x (4 + y) 294210d565efSmrg#define y (2 * x) 294310d565efSmrg@end smallexample 294410d565efSmrg 294510d565efSmrg@noindent 294610d565efSmrgthen @code{x} and @code{y} expand as follows: 294710d565efSmrg 294810d565efSmrg@smallexample 294910d565efSmrg@group 295010d565efSmrgx @expansion{} (4 + y) 295110d565efSmrg @expansion{} (4 + (2 * x)) 295210d565efSmrg 295310d565efSmrgy @expansion{} (2 * x) 295410d565efSmrg @expansion{} (2 * (4 + y)) 295510d565efSmrg@end group 295610d565efSmrg@end smallexample 295710d565efSmrg 295810d565efSmrg@noindent 295910d565efSmrgEach macro is expanded when it appears in the definition of the other 296010d565efSmrgmacro, but not when it indirectly appears in its own definition. 296110d565efSmrg 296210d565efSmrg@node Argument Prescan 296310d565efSmrg@subsection Argument Prescan 296410d565efSmrg@cindex expansion of arguments 296510d565efSmrg@cindex macro argument expansion 296610d565efSmrg@cindex prescan of macro arguments 296710d565efSmrg 296810d565efSmrgMacro arguments are completely macro-expanded before they are 296910d565efSmrgsubstituted into a macro body, unless they are stringized or pasted 297010d565efSmrgwith other tokens. After substitution, the entire macro body, including 297110d565efSmrgthe substituted arguments, is scanned again for macros to be expanded. 297210d565efSmrgThe result is that the arguments are scanned @emph{twice} to expand 297310d565efSmrgmacro calls in them. 297410d565efSmrg 297510d565efSmrgMost of the time, this has no effect. If the argument contained any 297610d565efSmrgmacro calls, they are expanded during the first scan. The result 297710d565efSmrgtherefore contains no macro calls, so the second scan does not change 297810d565efSmrgit. If the argument were substituted as given, with no prescan, the 297910d565efSmrgsingle remaining scan would find the same macro calls and produce the 298010d565efSmrgsame results. 298110d565efSmrg 298210d565efSmrgYou might expect the double scan to change the results when a 298310d565efSmrgself-referential macro is used in an argument of another macro 298410d565efSmrg(@pxref{Self-Referential Macros}): the self-referential macro would be 298510d565efSmrgexpanded once in the first scan, and a second time in the second scan. 298610d565efSmrgHowever, this is not what happens. The self-references that do not 298710d565efSmrgexpand in the first scan are marked so that they will not expand in the 298810d565efSmrgsecond scan either. 298910d565efSmrg 299010d565efSmrgYou might wonder, ``Why mention the prescan, if it makes no difference? 299110d565efSmrgAnd why not skip it and make the preprocessor faster?'' The answer is 299210d565efSmrgthat the prescan does make a difference in three special cases: 299310d565efSmrg 299410d565efSmrg@itemize @bullet 299510d565efSmrg@item 299610d565efSmrgNested calls to a macro. 299710d565efSmrg 299810d565efSmrgWe say that @dfn{nested} calls to a macro occur when a macro's argument 299910d565efSmrgcontains a call to that very macro. For example, if @code{f} is a macro 300010d565efSmrgthat expects one argument, @code{f (f (1))} is a nested pair of calls to 300110d565efSmrg@code{f}. The desired expansion is made by expanding @code{f (1)} and 300210d565efSmrgsubstituting that into the definition of @code{f}. The prescan causes 300310d565efSmrgthe expected result to happen. Without the prescan, @code{f (1)} itself 300410d565efSmrgwould be substituted as an argument, and the inner use of @code{f} would 300510d565efSmrgappear during the main scan as an indirect self-reference and would not 300610d565efSmrgbe expanded. 300710d565efSmrg 300810d565efSmrg@item 300910d565efSmrgMacros that call other macros that stringize or concatenate. 301010d565efSmrg 301110d565efSmrgIf an argument is stringized or concatenated, the prescan does not 301210d565efSmrgoccur. If you @emph{want} to expand a macro, then stringize or 301310d565efSmrgconcatenate its expansion, you can do that by causing one macro to call 301410d565efSmrganother macro that does the stringizing or concatenation. For 301510d565efSmrginstance, if you have 301610d565efSmrg 301710d565efSmrg@smallexample 301810d565efSmrg#define AFTERX(x) X_ ## x 301910d565efSmrg#define XAFTERX(x) AFTERX(x) 302010d565efSmrg#define TABLESIZE 1024 302110d565efSmrg#define BUFSIZE TABLESIZE 302210d565efSmrg@end smallexample 302310d565efSmrg 302410d565efSmrgthen @code{AFTERX(BUFSIZE)} expands to @code{X_BUFSIZE}, and 302510d565efSmrg@code{XAFTERX(BUFSIZE)} expands to @code{X_1024}. (Not to 302610d565efSmrg@code{X_TABLESIZE}. Prescan always does a complete expansion.) 302710d565efSmrg 302810d565efSmrg@item 302910d565efSmrgMacros used in arguments, whose expansions contain unshielded commas. 303010d565efSmrg 303110d565efSmrgThis can cause a macro expanded on the second scan to be called with the 303210d565efSmrgwrong number of arguments. Here is an example: 303310d565efSmrg 303410d565efSmrg@smallexample 303510d565efSmrg#define foo a,b 303610d565efSmrg#define bar(x) lose(x) 303710d565efSmrg#define lose(x) (1 + (x)) 303810d565efSmrg@end smallexample 303910d565efSmrg 304010d565efSmrgWe would like @code{bar(foo)} to turn into @code{(1 + (foo))}, which 304110d565efSmrgwould then turn into @code{(1 + (a,b))}. Instead, @code{bar(foo)} 304210d565efSmrgexpands into @code{lose(a,b)}, and you get an error because @code{lose} 304310d565efSmrgrequires a single argument. In this case, the problem is easily solved 304410d565efSmrgby the same parentheses that ought to be used to prevent misnesting of 304510d565efSmrgarithmetic operations: 304610d565efSmrg 304710d565efSmrg@smallexample 304810d565efSmrg#define foo (a,b) 304910d565efSmrg@exdent or 305010d565efSmrg#define bar(x) lose((x)) 305110d565efSmrg@end smallexample 305210d565efSmrg 305310d565efSmrgThe extra pair of parentheses prevents the comma in @code{foo}'s 305410d565efSmrgdefinition from being interpreted as an argument separator. 305510d565efSmrg 305610d565efSmrg@end itemize 305710d565efSmrg 305810d565efSmrg@node Newlines in Arguments 305910d565efSmrg@subsection Newlines in Arguments 306010d565efSmrg@cindex newlines in macro arguments 306110d565efSmrg 306210d565efSmrgThe invocation of a function-like macro can extend over many logical 306310d565efSmrglines. However, in the present implementation, the entire expansion 306410d565efSmrgcomes out on one line. Thus line numbers emitted by the compiler or 306510d565efSmrgdebugger refer to the line the invocation started on, which might be 306610d565efSmrgdifferent to the line containing the argument causing the problem. 306710d565efSmrg 306810d565efSmrgHere is an example illustrating this: 306910d565efSmrg 307010d565efSmrg@smallexample 307110d565efSmrg#define ignore_second_arg(a,b,c) a; c 307210d565efSmrg 307310d565efSmrgignore_second_arg (foo (), 307410d565efSmrg ignored (), 307510d565efSmrg syntax error); 307610d565efSmrg@end smallexample 307710d565efSmrg 307810d565efSmrg@noindent 307910d565efSmrgThe syntax error triggered by the tokens @code{syntax error} results in 308010d565efSmrgan error message citing line three---the line of ignore_second_arg--- 308110d565efSmrgeven though the problematic code comes from line five. 308210d565efSmrg 308310d565efSmrgWe consider this a bug, and intend to fix it in the near future. 308410d565efSmrg 308510d565efSmrg@node Conditionals 308610d565efSmrg@chapter Conditionals 308710d565efSmrg@cindex conditionals 308810d565efSmrg 308910d565efSmrgA @dfn{conditional} is a directive that instructs the preprocessor to 309010d565efSmrgselect whether or not to include a chunk of code in the final token 309110d565efSmrgstream passed to the compiler. Preprocessor conditionals can test 309210d565efSmrgarithmetic expressions, or whether a name is defined as a macro, or both 309310d565efSmrgsimultaneously using the special @code{defined} operator. 309410d565efSmrg 309510d565efSmrgA conditional in the C preprocessor resembles in some ways an @code{if} 309610d565efSmrgstatement in C, but it is important to understand the difference between 309710d565efSmrgthem. The condition in an @code{if} statement is tested during the 309810d565efSmrgexecution of your program. Its purpose is to allow your program to 309910d565efSmrgbehave differently from run to run, depending on the data it is 310010d565efSmrgoperating on. The condition in a preprocessing conditional directive is 310110d565efSmrgtested when your program is compiled. Its purpose is to allow different 310210d565efSmrgcode to be included in the program depending on the situation at the 310310d565efSmrgtime of compilation. 310410d565efSmrg 310510d565efSmrgHowever, the distinction is becoming less clear. Modern compilers often 310610d565efSmrgdo test @code{if} statements when a program is compiled, if their 310710d565efSmrgconditions are known not to vary at run time, and eliminate code which 310810d565efSmrgcan never be executed. If you can count on your compiler to do this, 310910d565efSmrgyou may find that your program is more readable if you use @code{if} 311010d565efSmrgstatements with constant conditions (perhaps determined by macros). Of 311110d565efSmrgcourse, you can only use this to exclude code, not type definitions or 311210d565efSmrgother preprocessing directives, and you can only do it if the code 311310d565efSmrgremains syntactically valid when it is not to be used. 311410d565efSmrg 311510d565efSmrg@menu 311610d565efSmrg* Conditional Uses:: 311710d565efSmrg* Conditional Syntax:: 311810d565efSmrg* Deleted Code:: 311910d565efSmrg@end menu 312010d565efSmrg 312110d565efSmrg@node Conditional Uses 312210d565efSmrg@section Conditional Uses 312310d565efSmrg 312410d565efSmrgThere are three general reasons to use a conditional. 312510d565efSmrg 312610d565efSmrg@itemize @bullet 312710d565efSmrg@item 312810d565efSmrgA program may need to use different code depending on the machine or 312910d565efSmrgoperating system it is to run on. In some cases the code for one 313010d565efSmrgoperating system may be erroneous on another operating system; for 313110d565efSmrgexample, it might refer to data types or constants that do not exist on 313210d565efSmrgthe other system. When this happens, it is not enough to avoid 313310d565efSmrgexecuting the invalid code. Its mere presence will cause the compiler 313410d565efSmrgto reject the program. With a preprocessing conditional, the offending 313510d565efSmrgcode can be effectively excised from the program when it is not valid. 313610d565efSmrg 313710d565efSmrg@item 313810d565efSmrgYou may want to be able to compile the same source file into two 313910d565efSmrgdifferent programs. One version might make frequent time-consuming 314010d565efSmrgconsistency checks on its intermediate data, or print the values of 314110d565efSmrgthose data for debugging, and the other not. 314210d565efSmrg 314310d565efSmrg@item 314410d565efSmrgA conditional whose condition is always false is one way to exclude code 314510d565efSmrgfrom the program but keep it as a sort of comment for future reference. 314610d565efSmrg@end itemize 314710d565efSmrg 314810d565efSmrgSimple programs that do not need system-specific logic or complex 314910d565efSmrgdebugging hooks generally will not need to use preprocessing 315010d565efSmrgconditionals. 315110d565efSmrg 315210d565efSmrg@node Conditional Syntax 315310d565efSmrg@section Conditional Syntax 315410d565efSmrg 315510d565efSmrg@findex #if 315610d565efSmrgA conditional in the C preprocessor begins with a @dfn{conditional 315710d565efSmrgdirective}: @samp{#if}, @samp{#ifdef} or @samp{#ifndef}. 315810d565efSmrg 315910d565efSmrg@menu 316010d565efSmrg* Ifdef:: 316110d565efSmrg* If:: 316210d565efSmrg* Defined:: 316310d565efSmrg* Else:: 316410d565efSmrg* Elif:: 31650fc04c29Smrg* @code{__has_attribute}:: 31660fc04c29Smrg* @code{__has_cpp_attribute}:: 3167*ec02198aSmrg* @code{__has_builtin}:: 31680fc04c29Smrg* @code{__has_include}:: 316910d565efSmrg@end menu 317010d565efSmrg 317110d565efSmrg@node Ifdef 317210d565efSmrg@subsection Ifdef 317310d565efSmrg@findex #ifdef 317410d565efSmrg@findex #endif 317510d565efSmrg 317610d565efSmrgThe simplest sort of conditional is 317710d565efSmrg 317810d565efSmrg@smallexample 317910d565efSmrg@group 318010d565efSmrg#ifdef @var{MACRO} 318110d565efSmrg 318210d565efSmrg@var{controlled text} 318310d565efSmrg 318410d565efSmrg#endif /* @var{MACRO} */ 318510d565efSmrg@end group 318610d565efSmrg@end smallexample 318710d565efSmrg 318810d565efSmrg@cindex conditional group 318910d565efSmrgThis block is called a @dfn{conditional group}. @var{controlled text} 319010d565efSmrgwill be included in the output of the preprocessor if and only if 319110d565efSmrg@var{MACRO} is defined. We say that the conditional @dfn{succeeds} if 319210d565efSmrg@var{MACRO} is defined, @dfn{fails} if it is not. 319310d565efSmrg 319410d565efSmrgThe @var{controlled text} inside of a conditional can include 319510d565efSmrgpreprocessing directives. They are executed only if the conditional 319610d565efSmrgsucceeds. You can nest conditional groups inside other conditional 319710d565efSmrggroups, but they must be completely nested. In other words, 319810d565efSmrg@samp{#endif} always matches the nearest @samp{#ifdef} (or 319910d565efSmrg@samp{#ifndef}, or @samp{#if}). Also, you cannot start a conditional 320010d565efSmrggroup in one file and end it in another. 320110d565efSmrg 320210d565efSmrgEven if a conditional fails, the @var{controlled text} inside it is 320310d565efSmrgstill run through initial transformations and tokenization. Therefore, 320410d565efSmrgit must all be lexically valid C@. Normally the only way this matters is 320510d565efSmrgthat all comments and string literals inside a failing conditional group 320610d565efSmrgmust still be properly ended. 320710d565efSmrg 320810d565efSmrgThe comment following the @samp{#endif} is not required, but it is a 320910d565efSmrggood practice if there is a lot of @var{controlled text}, because it 321010d565efSmrghelps people match the @samp{#endif} to the corresponding @samp{#ifdef}. 321110d565efSmrgOlder programs sometimes put @var{MACRO} directly after the 321210d565efSmrg@samp{#endif} without enclosing it in a comment. This is invalid code 321310d565efSmrgaccording to the C standard. CPP accepts it with a warning. It 321410d565efSmrgnever affects which @samp{#ifndef} the @samp{#endif} matches. 321510d565efSmrg 321610d565efSmrg@findex #ifndef 321710d565efSmrgSometimes you wish to use some code if a macro is @emph{not} defined. 321810d565efSmrgYou can do this by writing @samp{#ifndef} instead of @samp{#ifdef}. 321910d565efSmrgOne common use of @samp{#ifndef} is to include code only the first 322010d565efSmrgtime a header file is included. @xref{Once-Only Headers}. 322110d565efSmrg 322210d565efSmrgMacro definitions can vary between compilations for several reasons. 322310d565efSmrgHere are some samples. 322410d565efSmrg 322510d565efSmrg@itemize @bullet 322610d565efSmrg@item 322710d565efSmrgSome macros are predefined on each kind of machine 322810d565efSmrg(@pxref{System-specific Predefined Macros}). This allows you to provide 322910d565efSmrgcode specially tuned for a particular machine. 323010d565efSmrg 323110d565efSmrg@item 323210d565efSmrgSystem header files define more macros, associated with the features 323310d565efSmrgthey implement. You can test these macros with conditionals to avoid 323410d565efSmrgusing a system feature on a machine where it is not implemented. 323510d565efSmrg 323610d565efSmrg@item 323710d565efSmrgMacros can be defined or undefined with the @option{-D} and @option{-U} 323810d565efSmrgcommand-line options when you compile the program. You can arrange to 323910d565efSmrgcompile the same source file into two different programs by choosing a 324010d565efSmrgmacro name to specify which program you want, writing conditionals to 324110d565efSmrgtest whether or how this macro is defined, and then controlling the 324210d565efSmrgstate of the macro with command-line options, perhaps set in the 324310d565efSmrgMakefile. @xref{Invocation}. 324410d565efSmrg 324510d565efSmrg@item 324610d565efSmrgYour program might have a special header file (often called 324710d565efSmrg@file{config.h}) that is adjusted when the program is compiled. It can 324810d565efSmrgdefine or not define macros depending on the features of the system and 324910d565efSmrgthe desired capabilities of the program. The adjustment can be 325010d565efSmrgautomated by a tool such as @command{autoconf}, or done by hand. 325110d565efSmrg@end itemize 325210d565efSmrg 325310d565efSmrg@node If 325410d565efSmrg@subsection If 325510d565efSmrg 325610d565efSmrgThe @samp{#if} directive allows you to test the value of an arithmetic 325710d565efSmrgexpression, rather than the mere existence of one macro. Its syntax is 325810d565efSmrg 325910d565efSmrg@smallexample 326010d565efSmrg@group 326110d565efSmrg#if @var{expression} 326210d565efSmrg 326310d565efSmrg@var{controlled text} 326410d565efSmrg 326510d565efSmrg#endif /* @var{expression} */ 326610d565efSmrg@end group 326710d565efSmrg@end smallexample 326810d565efSmrg 326910d565efSmrg@var{expression} is a C expression of integer type, subject to stringent 327010d565efSmrgrestrictions. It may contain 327110d565efSmrg 327210d565efSmrg@itemize @bullet 327310d565efSmrg@item 327410d565efSmrgInteger constants. 327510d565efSmrg 327610d565efSmrg@item 327710d565efSmrgCharacter constants, which are interpreted as they would be in normal 327810d565efSmrgcode. 327910d565efSmrg 328010d565efSmrg@item 328110d565efSmrgArithmetic operators for addition, subtraction, multiplication, 328210d565efSmrgdivision, bitwise operations, shifts, comparisons, and logical 328310d565efSmrgoperations (@code{&&} and @code{||}). The latter two obey the usual 328410d565efSmrgshort-circuiting rules of standard C@. 328510d565efSmrg 328610d565efSmrg@item 328710d565efSmrgMacros. All macros in the expression are expanded before actual 328810d565efSmrgcomputation of the expression's value begins. 328910d565efSmrg 329010d565efSmrg@item 329110d565efSmrgUses of the @code{defined} operator, which lets you check whether macros 329210d565efSmrgare defined in the middle of an @samp{#if}. 329310d565efSmrg 329410d565efSmrg@item 329510d565efSmrgIdentifiers that are not macros, which are all considered to be the 329610d565efSmrgnumber zero. This allows you to write @code{@w{#if MACRO}} instead of 329710d565efSmrg@code{@w{#ifdef MACRO}}, if you know that MACRO, when defined, will 329810d565efSmrgalways have a nonzero value. Function-like macros used without their 329910d565efSmrgfunction call parentheses are also treated as zero. 330010d565efSmrg 330110d565efSmrgIn some contexts this shortcut is undesirable. The @option{-Wundef} 330210d565efSmrgoption causes GCC to warn whenever it encounters an identifier which is 330310d565efSmrgnot a macro in an @samp{#if}. 330410d565efSmrg@end itemize 330510d565efSmrg 330610d565efSmrgThe preprocessor does not know anything about types in the language. 330710d565efSmrgTherefore, @code{sizeof} operators are not recognized in @samp{#if}, and 330810d565efSmrgneither are @code{enum} constants. They will be taken as identifiers 330910d565efSmrgwhich are not macros, and replaced by zero. In the case of 331010d565efSmrg@code{sizeof}, this is likely to cause the expression to be invalid. 331110d565efSmrg 331210d565efSmrgThe preprocessor calculates the value of @var{expression}. It carries 331310d565efSmrgout all calculations in the widest integer type known to the compiler; 331410d565efSmrgon most machines supported by GCC this is 64 bits. This is not the same 331510d565efSmrgrule as the compiler uses to calculate the value of a constant 331610d565efSmrgexpression, and may give different results in some cases. If the value 331710d565efSmrgcomes out to be nonzero, the @samp{#if} succeeds and the @var{controlled 331810d565efSmrgtext} is included; otherwise it is skipped. 331910d565efSmrg 332010d565efSmrg@node Defined 332110d565efSmrg@subsection Defined 332210d565efSmrg 332310d565efSmrg@cindex @code{defined} 332410d565efSmrgThe special operator @code{defined} is used in @samp{#if} and 332510d565efSmrg@samp{#elif} expressions to test whether a certain name is defined as a 332610d565efSmrgmacro. @code{defined @var{name}} and @code{defined (@var{name})} are 332710d565efSmrgboth expressions whose value is 1 if @var{name} is defined as a macro at 332810d565efSmrgthe current point in the program, and 0 otherwise. Thus, @code{@w{#if 332910d565efSmrgdefined MACRO}} is precisely equivalent to @code{@w{#ifdef MACRO}}. 333010d565efSmrg 333110d565efSmrg@code{defined} is useful when you wish to test more than one macro for 333210d565efSmrgexistence at once. For example, 333310d565efSmrg 333410d565efSmrg@smallexample 333510d565efSmrg#if defined (__vax__) || defined (__ns16000__) 333610d565efSmrg@end smallexample 333710d565efSmrg 333810d565efSmrg@noindent 333910d565efSmrgwould succeed if either of the names @code{__vax__} or 334010d565efSmrg@code{__ns16000__} is defined as a macro. 334110d565efSmrg 334210d565efSmrgConditionals written like this: 334310d565efSmrg 334410d565efSmrg@smallexample 334510d565efSmrg#if defined BUFSIZE && BUFSIZE >= 1024 334610d565efSmrg@end smallexample 334710d565efSmrg 334810d565efSmrg@noindent 334910d565efSmrgcan generally be simplified to just @code{@w{#if BUFSIZE >= 1024}}, 335010d565efSmrgsince if @code{BUFSIZE} is not defined, it will be interpreted as having 335110d565efSmrgthe value zero. 335210d565efSmrg 335310d565efSmrgIf the @code{defined} operator appears as a result of a macro expansion, 335410d565efSmrgthe C standard says the behavior is undefined. GNU cpp treats it as a 335510d565efSmrggenuine @code{defined} operator and evaluates it normally. It will warn 335610d565efSmrgwherever your code uses this feature if you use the command-line option 335710d565efSmrg@option{-Wpedantic}, since other compilers may handle it differently. The 335810d565efSmrgwarning is also enabled by @option{-Wextra}, and can also be enabled 335910d565efSmrgindividually with @option{-Wexpansion-to-defined}. 336010d565efSmrg 336110d565efSmrg@node Else 336210d565efSmrg@subsection Else 336310d565efSmrg 336410d565efSmrg@findex #else 336510d565efSmrgThe @samp{#else} directive can be added to a conditional to provide 336610d565efSmrgalternative text to be used if the condition fails. This is what it 336710d565efSmrglooks like: 336810d565efSmrg 336910d565efSmrg@smallexample 337010d565efSmrg@group 337110d565efSmrg#if @var{expression} 337210d565efSmrg@var{text-if-true} 337310d565efSmrg#else /* Not @var{expression} */ 337410d565efSmrg@var{text-if-false} 337510d565efSmrg#endif /* Not @var{expression} */ 337610d565efSmrg@end group 337710d565efSmrg@end smallexample 337810d565efSmrg 337910d565efSmrg@noindent 338010d565efSmrgIf @var{expression} is nonzero, the @var{text-if-true} is included and 338110d565efSmrgthe @var{text-if-false} is skipped. If @var{expression} is zero, the 338210d565efSmrgopposite happens. 338310d565efSmrg 338410d565efSmrgYou can use @samp{#else} with @samp{#ifdef} and @samp{#ifndef}, too. 338510d565efSmrg 338610d565efSmrg@node Elif 338710d565efSmrg@subsection Elif 338810d565efSmrg 338910d565efSmrg@findex #elif 339010d565efSmrgOne common case of nested conditionals is used to check for more than two 339110d565efSmrgpossible alternatives. For example, you might have 339210d565efSmrg 339310d565efSmrg@smallexample 339410d565efSmrg#if X == 1 339510d565efSmrg@dots{} 339610d565efSmrg#else /* X != 1 */ 339710d565efSmrg#if X == 2 339810d565efSmrg@dots{} 339910d565efSmrg#else /* X != 2 */ 340010d565efSmrg@dots{} 340110d565efSmrg#endif /* X != 2 */ 340210d565efSmrg#endif /* X != 1 */ 340310d565efSmrg@end smallexample 340410d565efSmrg 340510d565efSmrgAnother conditional directive, @samp{#elif}, allows this to be 340610d565efSmrgabbreviated as follows: 340710d565efSmrg 340810d565efSmrg@smallexample 340910d565efSmrg#if X == 1 341010d565efSmrg@dots{} 341110d565efSmrg#elif X == 2 341210d565efSmrg@dots{} 341310d565efSmrg#else /* X != 2 and X != 1*/ 341410d565efSmrg@dots{} 341510d565efSmrg#endif /* X != 2 and X != 1*/ 341610d565efSmrg@end smallexample 341710d565efSmrg 341810d565efSmrg@samp{#elif} stands for ``else if''. Like @samp{#else}, it goes in the 341910d565efSmrgmiddle of a conditional group and subdivides it; it does not require a 342010d565efSmrgmatching @samp{#endif} of its own. Like @samp{#if}, the @samp{#elif} 342110d565efSmrgdirective includes an expression to be tested. The text following the 342210d565efSmrg@samp{#elif} is processed only if the original @samp{#if}-condition 342310d565efSmrgfailed and the @samp{#elif} condition succeeds. 342410d565efSmrg 342510d565efSmrgMore than one @samp{#elif} can go in the same conditional group. Then 342610d565efSmrgthe text after each @samp{#elif} is processed only if the @samp{#elif} 342710d565efSmrgcondition succeeds after the original @samp{#if} and all previous 342810d565efSmrg@samp{#elif} directives within it have failed. 342910d565efSmrg 343010d565efSmrg@samp{#else} is allowed after any number of @samp{#elif} directives, but 343110d565efSmrg@samp{#elif} may not follow @samp{#else}. 343210d565efSmrg 34330fc04c29Smrg@node @code{__has_attribute} 34340fc04c29Smrg@subsection @code{__has_attribute} 34350fc04c29Smrg@cindex @code{__has_attribute} 34360fc04c29Smrg 34370fc04c29SmrgThe special operator @code{__has_attribute (@var{operand})} may be used 34380fc04c29Smrgin @samp{#if} and @samp{#elif} expressions to test whether the attribute 34390fc04c29Smrgreferenced by its @var{operand} is recognized by GCC. Using the operator 34400fc04c29Smrgin other contexts is not valid. In C code, @var{operand} must be 34410fc04c29Smrga valid identifier. In C++ code, @var{operand} may be optionally 34420fc04c29Smrgintroduced by the @code{@var{attribute-scope}::} prefix. 34430fc04c29SmrgThe @var{attribute-scope} prefix identifies the ``namespace'' within 34440fc04c29Smrgwhich the attribute is recognized. The scope of GCC attributes is 34450fc04c29Smrg@samp{gnu} or @samp{__gnu__}. The @code{__has_attribute} operator by 34460fc04c29Smrgitself, without any @var{operand} or parentheses, acts as a predefined 34470fc04c29Smrgmacro so that support for it can be tested in portable code. Thus, 34480fc04c29Smrgthe recommended use of the operator is as follows: 34490fc04c29Smrg 34500fc04c29Smrg@smallexample 34510fc04c29Smrg#if defined __has_attribute 34520fc04c29Smrg# if __has_attribute (nonnull) 34530fc04c29Smrg# define ATTR_NONNULL __attribute__ ((nonnull)) 34540fc04c29Smrg# endif 34550fc04c29Smrg#endif 34560fc04c29Smrg@end smallexample 34570fc04c29Smrg 34580fc04c29SmrgThe first @samp{#if} test succeeds only when the operator is supported 34590fc04c29Smrgby the version of GCC (or another compiler) being used. Only when that 34600fc04c29Smrgtest succeeds is it valid to use @code{__has_attribute} as a preprocessor 34610fc04c29Smrgoperator. As a result, combining the two tests into a single expression as 34620fc04c29Smrgshown below would only be valid with a compiler that supports the operator 34630fc04c29Smrgbut not with others that don't. 34640fc04c29Smrg 34650fc04c29Smrg@smallexample 34660fc04c29Smrg#if defined __has_attribute && __has_attribute (nonnull) /* not portable */ 34670fc04c29Smrg@dots{} 34680fc04c29Smrg#endif 34690fc04c29Smrg@end smallexample 34700fc04c29Smrg 34710fc04c29Smrg@node @code{__has_cpp_attribute} 34720fc04c29Smrg@subsection @code{__has_cpp_attribute} 34730fc04c29Smrg@cindex @code{__has_cpp_attribute} 34740fc04c29Smrg 34750fc04c29SmrgThe special operator @code{__has_cpp_attribute (@var{operand})} may be used 34760fc04c29Smrgin @samp{#if} and @samp{#elif} expressions in C++ code to test whether 34770fc04c29Smrgthe attribute referenced by its @var{operand} is recognized by GCC. 34780fc04c29Smrg@code{__has_cpp_attribute (@var{operand})} is equivalent to 34790fc04c29Smrg@code{__has_attribute (@var{operand})} except that when @var{operand} 34800fc04c29Smrgdesignates a supported standard attribute it evaluates to an integer 34810fc04c29Smrgconstant of the form @code{YYYYMM} indicating the year and month when 34820fc04c29Smrgthe attribute was first introduced into the C++ standard. For additional 34830fc04c29Smrginformation including the dates of the introduction of current standard 34840fc04c29Smrgattributes, see @w{@uref{https://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations/, 34850fc04c29SmrgSD-6: SG10 Feature Test Recommendations}}. 34860fc04c29Smrg 3487*ec02198aSmrg@node @code{__has_builtin} 3488*ec02198aSmrg@subsection @code{__has_builtin} 3489*ec02198aSmrg@cindex @code{__has_builtin} 3490*ec02198aSmrg 3491*ec02198aSmrgThe special operator @code{__has_builtin (@var{operand})} may be used in 3492*ec02198aSmrgconstant integer contexts and in preprocessor @samp{#if} and @samp{#elif} 3493*ec02198aSmrgexpressions to test whether the symbol named by its @var{operand} is 3494*ec02198aSmrgrecognized as a built-in function by GCC in the current language and 3495*ec02198aSmrgconformance mode. It evaluates to a constant integer with a nonzero 3496*ec02198aSmrgvalue if the argument refers to such a function, and to zero otherwise. 3497*ec02198aSmrgThe operator may also be used in preprocessor @samp{#if} and @samp{#elif} 3498*ec02198aSmrgexpressions. The @code{__has_builtin} operator by itself, without any 3499*ec02198aSmrg@var{operand} or parentheses, acts as a predefined macro so that support 3500*ec02198aSmrgfor it can be tested in portable code. Thus, the recommended use of 3501*ec02198aSmrgthe operator is as follows: 3502*ec02198aSmrg 3503*ec02198aSmrg@smallexample 3504*ec02198aSmrg#if defined __has_builtin 3505*ec02198aSmrg# if __has_builtin (__builtin_object_size) 3506*ec02198aSmrg# define builtin_object_size(ptr) __builtin_object_size (ptr, 2) 3507*ec02198aSmrg# endif 3508*ec02198aSmrg#endif 3509*ec02198aSmrg#ifndef builtin_object_size 3510*ec02198aSmrg# define builtin_object_size(ptr) ((size_t)-1) 3511*ec02198aSmrg#endif 3512*ec02198aSmrg@end smallexample 3513*ec02198aSmrg 35140fc04c29Smrg@node @code{__has_include} 35150fc04c29Smrg@subsection @code{__has_include} 35160fc04c29Smrg@cindex @code{__has_include} 35170fc04c29Smrg 35180fc04c29SmrgThe special operator @code{__has_include (@var{operand})} may be used in 35190fc04c29Smrg@samp{#if} and @samp{#elif} expressions to test whether the header referenced 35200fc04c29Smrgby its @var{operand} can be included using the @samp{#include} directive. Using 35210fc04c29Smrgthe operator in other contexts is not valid. The @var{operand} takes 35220fc04c29Smrgthe same form as the file in the @samp{#include} directive (@pxref{Include 35230fc04c29SmrgSyntax}) and evaluates to a nonzero value if the header can be included and 35240fc04c29Smrgto zero otherwise. Note that that the ability to include a header doesn't 35250fc04c29Smrgimply that the header doesn't contain invalid constructs or @samp{#error} 35260fc04c29Smrgdirectives that would cause the preprocessor to fail. 35270fc04c29Smrg 35280fc04c29SmrgThe @code{__has_include} operator by itself, without any @var{operand} or 35290fc04c29Smrgparentheses, acts as a predefined macro so that support for it can be tested 35300fc04c29Smrgin portable code. Thus, the recommended use of the operator is as follows: 35310fc04c29Smrg 35320fc04c29Smrg@smallexample 35330fc04c29Smrg#if defined __has_include 35340fc04c29Smrg# if __has_include (<stdatomic.h>) 35350fc04c29Smrg# include <stdatomic.h> 35360fc04c29Smrg# endif 35370fc04c29Smrg#endif 35380fc04c29Smrg@end smallexample 35390fc04c29Smrg 35400fc04c29SmrgThe first @samp{#if} test succeeds only when the operator is supported 35410fc04c29Smrgby the version of GCC (or another compiler) being used. Only when that 35420fc04c29Smrgtest succeeds is it valid to use @code{__has_include} as a preprocessor 35430fc04c29Smrgoperator. As a result, combining the two tests into a single expression 35440fc04c29Smrgas shown below would only be valid with a compiler that supports the operator 35450fc04c29Smrgbut not with others that don't. 35460fc04c29Smrg 35470fc04c29Smrg@smallexample 35480fc04c29Smrg#if defined __has_include && __has_include ("header.h") /* not portable */ 35490fc04c29Smrg@dots{} 35500fc04c29Smrg#endif 35510fc04c29Smrg@end smallexample 35520fc04c29Smrg 355310d565efSmrg@node Deleted Code 355410d565efSmrg@section Deleted Code 355510d565efSmrg@cindex commenting out code 355610d565efSmrg 355710d565efSmrgIf you replace or delete a part of the program but want to keep the old 355810d565efSmrgcode around for future reference, you often cannot simply comment it 355910d565efSmrgout. Block comments do not nest, so the first comment inside the old 356010d565efSmrgcode will end the commenting-out. The probable result is a flood of 356110d565efSmrgsyntax errors. 356210d565efSmrg 356310d565efSmrgOne way to avoid this problem is to use an always-false conditional 356410d565efSmrginstead. For instance, put @code{#if 0} before the deleted code and 356510d565efSmrg@code{#endif} after it. This works even if the code being turned 356610d565efSmrgoff contains conditionals, but they must be entire conditionals 356710d565efSmrg(balanced @samp{#if} and @samp{#endif}). 356810d565efSmrg 356910d565efSmrgSome people use @code{#ifdef notdef} instead. This is risky, because 357010d565efSmrg@code{notdef} might be accidentally defined as a macro, and then the 357110d565efSmrgconditional would succeed. @code{#if 0} can be counted on to fail. 357210d565efSmrg 357310d565efSmrgDo not use @code{#if 0} for comments which are not C code. Use a real 357410d565efSmrgcomment, instead. The interior of @code{#if 0} must consist of complete 357510d565efSmrgtokens; in particular, single-quote characters must balance. Comments 357610d565efSmrgoften contain unbalanced single-quote characters (known in English as 357710d565efSmrgapostrophes). These confuse @code{#if 0}. They don't confuse 357810d565efSmrg@samp{/*}. 357910d565efSmrg 358010d565efSmrg@node Diagnostics 358110d565efSmrg@chapter Diagnostics 358210d565efSmrg@cindex diagnostic 358310d565efSmrg@cindex reporting errors 358410d565efSmrg@cindex reporting warnings 358510d565efSmrg 358610d565efSmrg@findex #error 358710d565efSmrgThe directive @samp{#error} causes the preprocessor to report a fatal 358810d565efSmrgerror. The tokens forming the rest of the line following @samp{#error} 358910d565efSmrgare used as the error message. 359010d565efSmrg 359110d565efSmrgYou would use @samp{#error} inside of a conditional that detects a 359210d565efSmrgcombination of parameters which you know the program does not properly 359310d565efSmrgsupport. For example, if you know that the program will not run 359410d565efSmrgproperly on a VAX, you might write 359510d565efSmrg 359610d565efSmrg@smallexample 359710d565efSmrg@group 359810d565efSmrg#ifdef __vax__ 359910d565efSmrg#error "Won't work on VAXen. See comments at get_last_object." 360010d565efSmrg#endif 360110d565efSmrg@end group 360210d565efSmrg@end smallexample 360310d565efSmrg 360410d565efSmrgIf you have several configuration parameters that must be set up by 360510d565efSmrgthe installation in a consistent way, you can use conditionals to detect 360610d565efSmrgan inconsistency and report it with @samp{#error}. For example, 360710d565efSmrg 360810d565efSmrg@smallexample 360910d565efSmrg#if !defined(FOO) && defined(BAR) 361010d565efSmrg#error "BAR requires FOO." 361110d565efSmrg#endif 361210d565efSmrg@end smallexample 361310d565efSmrg 361410d565efSmrg@findex #warning 361510d565efSmrgThe directive @samp{#warning} is like @samp{#error}, but causes the 361610d565efSmrgpreprocessor to issue a warning and continue preprocessing. The tokens 361710d565efSmrgfollowing @samp{#warning} are used as the warning message. 361810d565efSmrg 361910d565efSmrgYou might use @samp{#warning} in obsolete header files, with a message 362010d565efSmrgdirecting the user to the header file which should be used instead. 362110d565efSmrg 362210d565efSmrgNeither @samp{#error} nor @samp{#warning} macro-expands its argument. 362310d565efSmrgInternal whitespace sequences are each replaced with a single space. 362410d565efSmrgThe line must consist of complete tokens. It is wisest to make the 362510d565efSmrgargument of these directives be a single string constant; this avoids 362610d565efSmrgproblems with apostrophes and the like. 362710d565efSmrg 362810d565efSmrg@node Line Control 362910d565efSmrg@chapter Line Control 363010d565efSmrg@cindex line control 363110d565efSmrg 363210d565efSmrgThe C preprocessor informs the C compiler of the location in your source 363310d565efSmrgcode where each token came from. Presently, this is just the file name 363410d565efSmrgand line number. All the tokens resulting from macro expansion are 363510d565efSmrgreported as having appeared on the line of the source file where the 363610d565efSmrgoutermost macro was used. We intend to be more accurate in the future. 363710d565efSmrg 363810d565efSmrgIf you write a program which generates source code, such as the 363910d565efSmrg@command{bison} parser generator, you may want to adjust the preprocessor's 364010d565efSmrgnotion of the current file name and line number by hand. Parts of the 364110d565efSmrgoutput from @command{bison} are generated from scratch, other parts come 364210d565efSmrgfrom a standard parser file. The rest are copied verbatim from 364310d565efSmrg@command{bison}'s input. You would like compiler error messages and 364410d565efSmrgsymbolic debuggers to be able to refer to @code{bison}'s input file. 364510d565efSmrg 364610d565efSmrg@findex #line 364710d565efSmrg@command{bison} or any such program can arrange this by writing 364810d565efSmrg@samp{#line} directives into the output file. @samp{#line} is a 364910d565efSmrgdirective that specifies the original line number and source file name 365010d565efSmrgfor subsequent input in the current preprocessor input file. 365110d565efSmrg@samp{#line} has three variants: 365210d565efSmrg 365310d565efSmrg@table @code 365410d565efSmrg@item #line @var{linenum} 365510d565efSmrg@var{linenum} is a non-negative decimal integer constant. It specifies 365610d565efSmrgthe line number which should be reported for the following line of 365710d565efSmrginput. Subsequent lines are counted from @var{linenum}. 365810d565efSmrg 365910d565efSmrg@item #line @var{linenum} @var{filename} 366010d565efSmrg@var{linenum} is the same as for the first form, and has the same 366110d565efSmrgeffect. In addition, @var{filename} is a string constant. The 366210d565efSmrgfollowing line and all subsequent lines are reported to come from the 366310d565efSmrgfile it specifies, until something else happens to change that. 366410d565efSmrg@var{filename} is interpreted according to the normal rules for a string 366510d565efSmrgconstant: backslash escapes are interpreted. This is different from 366610d565efSmrg@samp{#include}. 366710d565efSmrg 366810d565efSmrg@item #line @var{anything else} 366910d565efSmrg@var{anything else} is checked for macro calls, which are expanded. 367010d565efSmrgThe result should match one of the above two forms. 367110d565efSmrg@end table 367210d565efSmrg 367310d565efSmrg@samp{#line} directives alter the results of the @code{__FILE__} and 367410d565efSmrg@code{__LINE__} predefined macros from that point on. @xref{Standard 367510d565efSmrgPredefined Macros}. They do not have any effect on @samp{#include}'s 367610d565efSmrgidea of the directory containing the current file. 367710d565efSmrg 367810d565efSmrg@node Pragmas 367910d565efSmrg@chapter Pragmas 368010d565efSmrg 36810fc04c29Smrg@cindex pragma directive 36820fc04c29Smrg 368310d565efSmrgThe @samp{#pragma} directive is the method specified by the C standard 368410d565efSmrgfor providing additional information to the compiler, beyond what is 368510d565efSmrgconveyed in the language itself. The forms of this directive 368610d565efSmrg(commonly known as @dfn{pragmas}) specified by C standard are prefixed with 368710d565efSmrg@code{STDC}. A C compiler is free to attach any meaning it likes to other 36880fc04c29Smrgpragmas. Most GNU-defined, supported pragmas have been given a 368910d565efSmrg@code{GCC} prefix. 369010d565efSmrg 369110d565efSmrg@cindex @code{_Pragma} 369210d565efSmrgC99 introduced the @code{@w{_Pragma}} operator. This feature addresses a 369310d565efSmrgmajor problem with @samp{#pragma}: being a directive, it cannot be 369410d565efSmrgproduced as the result of macro expansion. @code{@w{_Pragma}} is an 369510d565efSmrgoperator, much like @code{sizeof} or @code{defined}, and can be embedded 369610d565efSmrgin a macro. 369710d565efSmrg 369810d565efSmrgIts syntax is @code{@w{_Pragma (@var{string-literal})}}, where 369910d565efSmrg@var{string-literal} can be either a normal or wide-character string 370010d565efSmrgliteral. It is destringized, by replacing all @samp{\\} with a single 370110d565efSmrg@samp{\} and all @samp{\"} with a @samp{"}. The result is then 370210d565efSmrgprocessed as if it had appeared as the right hand side of a 370310d565efSmrg@samp{#pragma} directive. For example, 370410d565efSmrg 370510d565efSmrg@smallexample 370610d565efSmrg_Pragma ("GCC dependency \"parse.y\"") 370710d565efSmrg@end smallexample 370810d565efSmrg 370910d565efSmrg@noindent 371010d565efSmrghas the same effect as @code{#pragma GCC dependency "parse.y"}. The 371110d565efSmrgsame effect could be achieved using macros, for example 371210d565efSmrg 371310d565efSmrg@smallexample 371410d565efSmrg#define DO_PRAGMA(x) _Pragma (#x) 371510d565efSmrgDO_PRAGMA (GCC dependency "parse.y") 371610d565efSmrg@end smallexample 371710d565efSmrg 371810d565efSmrgThe standard is unclear on where a @code{_Pragma} operator can appear. 371910d565efSmrgThe preprocessor does not accept it within a preprocessing conditional 372010d565efSmrgdirective like @samp{#if}. To be safe, you are probably best keeping it 372110d565efSmrgout of directives other than @samp{#define}, and putting it on a line of 372210d565efSmrgits own. 372310d565efSmrg 372410d565efSmrgThis manual documents the pragmas which are meaningful to the 372510d565efSmrgpreprocessor itself. Other pragmas are meaningful to the C or C++ 372610d565efSmrgcompilers. They are documented in the GCC manual. 372710d565efSmrg 372810d565efSmrgGCC plugins may provide their own pragmas. 372910d565efSmrg 373010d565efSmrg@ftable @code 373110d565efSmrg@item #pragma GCC dependency 373210d565efSmrg@code{#pragma GCC dependency} allows you to check the relative dates of 373310d565efSmrgthe current file and another file. If the other file is more recent than 373410d565efSmrgthe current file, a warning is issued. This is useful if the current 373510d565efSmrgfile is derived from the other file, and should be regenerated. The 373610d565efSmrgother file is searched for using the normal include search path. 373710d565efSmrgOptional trailing text can be used to give more information in the 373810d565efSmrgwarning message. 373910d565efSmrg 374010d565efSmrg@smallexample 374110d565efSmrg#pragma GCC dependency "parse.y" 374210d565efSmrg#pragma GCC dependency "/usr/include/time.h" rerun fixincludes 374310d565efSmrg@end smallexample 374410d565efSmrg 374510d565efSmrg@item #pragma GCC poison 374610d565efSmrgSometimes, there is an identifier that you want to remove completely 374710d565efSmrgfrom your program, and make sure that it never creeps back in. To 374810d565efSmrgenforce this, you can @dfn{poison} the identifier with this pragma. 374910d565efSmrg@code{#pragma GCC poison} is followed by a list of identifiers to 375010d565efSmrgpoison. If any of those identifiers appears anywhere in the source 375110d565efSmrgafter the directive, it is a hard error. For example, 375210d565efSmrg 375310d565efSmrg@smallexample 375410d565efSmrg#pragma GCC poison printf sprintf fprintf 375510d565efSmrgsprintf(some_string, "hello"); 375610d565efSmrg@end smallexample 375710d565efSmrg 375810d565efSmrg@noindent 375910d565efSmrgwill produce an error. 376010d565efSmrg 376110d565efSmrgIf a poisoned identifier appears as part of the expansion of a macro 376210d565efSmrgwhich was defined before the identifier was poisoned, it will @emph{not} 376310d565efSmrgcause an error. This lets you poison an identifier without worrying 376410d565efSmrgabout system headers defining macros that use it. 376510d565efSmrg 376610d565efSmrgFor example, 376710d565efSmrg 376810d565efSmrg@smallexample 376910d565efSmrg#define strrchr rindex 377010d565efSmrg#pragma GCC poison rindex 377110d565efSmrgstrrchr(some_string, 'h'); 377210d565efSmrg@end smallexample 377310d565efSmrg 377410d565efSmrg@noindent 377510d565efSmrgwill not produce an error. 377610d565efSmrg 377710d565efSmrg@item #pragma GCC system_header 377810d565efSmrgThis pragma takes no arguments. It causes the rest of the code in the 377910d565efSmrgcurrent file to be treated as if it came from a system header. 378010d565efSmrg@xref{System Headers}. 378110d565efSmrg 378210d565efSmrg@item #pragma GCC warning 378310d565efSmrg@itemx #pragma GCC error 378410d565efSmrg@code{#pragma GCC warning "message"} causes the preprocessor to issue 378510d565efSmrga warning diagnostic with the text @samp{message}. The message 378610d565efSmrgcontained in the pragma must be a single string literal. Similarly, 378710d565efSmrg@code{#pragma GCC error "message"} issues an error message. Unlike 378810d565efSmrgthe @samp{#warning} and @samp{#error} directives, these pragmas can be 378910d565efSmrgembedded in preprocessor macros using @samp{_Pragma}. 379010d565efSmrg 37910fc04c29Smrg@item #pragma once 37920fc04c29SmrgIf @code{#pragma once} is seen when scanning a header file, that 37930fc04c29Smrgfile will never be read again, no matter what. It is a less-portable 37940fc04c29Smrgalternative to using @samp{#ifndef} to guard the contents of header files 37950fc04c29Smrgagainst multiple inclusions. 37960fc04c29Smrg 379710d565efSmrg@end ftable 379810d565efSmrg 379910d565efSmrg@node Other Directives 380010d565efSmrg@chapter Other Directives 380110d565efSmrg 380210d565efSmrg@findex #ident 380310d565efSmrg@findex #sccs 380410d565efSmrgThe @samp{#ident} directive takes one argument, a string constant. On 380510d565efSmrgsome systems, that string constant is copied into a special segment of 380610d565efSmrgthe object file. On other systems, the directive is ignored. The 380710d565efSmrg@samp{#sccs} directive is a synonym for @samp{#ident}. 380810d565efSmrg 380910d565efSmrgThese directives are not part of the C standard, but they are not 381010d565efSmrgofficial GNU extensions either. What historical information we have 381110d565efSmrgbeen able to find, suggests they originated with System V@. 381210d565efSmrg 381310d565efSmrg@cindex null directive 381410d565efSmrgThe @dfn{null directive} consists of a @samp{#} followed by a newline, 381510d565efSmrgwith only whitespace (including comments) in between. A null directive 381610d565efSmrgis understood as a preprocessing directive but has no effect on the 381710d565efSmrgpreprocessor output. The primary significance of the existence of the 381810d565efSmrgnull directive is that an input line consisting of just a @samp{#} will 381910d565efSmrgproduce no output, rather than a line of output containing just a 382010d565efSmrg@samp{#}. Supposedly some old C programs contain such lines. 382110d565efSmrg 382210d565efSmrg@node Preprocessor Output 382310d565efSmrg@chapter Preprocessor Output 382410d565efSmrg 382510d565efSmrgWhen the C preprocessor is used with the C, C++, or Objective-C 382610d565efSmrgcompilers, it is integrated into the compiler and communicates a stream 382710d565efSmrgof binary tokens directly to the compiler's parser. However, it can 382810d565efSmrgalso be used in the more conventional standalone mode, where it produces 382910d565efSmrgtextual output. 383010d565efSmrg@c FIXME: Document the library interface. 383110d565efSmrg 383210d565efSmrg@cindex output format 383310d565efSmrgThe output from the C preprocessor looks much like the input, except 383410d565efSmrgthat all preprocessing directive lines have been replaced with blank 383510d565efSmrglines and all comments with spaces. Long runs of blank lines are 383610d565efSmrgdiscarded. 383710d565efSmrg 383810d565efSmrgThe ISO standard specifies that it is implementation defined whether a 383910d565efSmrgpreprocessor preserves whitespace between tokens, or replaces it with 384010d565efSmrge.g.@: a single space. In GNU CPP, whitespace between tokens is collapsed 384110d565efSmrgto become a single space, with the exception that the first token on a 384210d565efSmrgnon-directive line is preceded with sufficient spaces that it appears in 384310d565efSmrgthe same column in the preprocessed output that it appeared in the 384410d565efSmrgoriginal source file. This is so the output is easy to read. 384510d565efSmrgCPP does not insert any 384610d565efSmrgwhitespace where there was none in the original source, except where 384710d565efSmrgnecessary to prevent an accidental token paste. 384810d565efSmrg 384910d565efSmrg@cindex linemarkers 385010d565efSmrgSource file name and line number information is conveyed by lines 385110d565efSmrgof the form 385210d565efSmrg 385310d565efSmrg@smallexample 385410d565efSmrg# @var{linenum} @var{filename} @var{flags} 385510d565efSmrg@end smallexample 385610d565efSmrg 385710d565efSmrg@noindent 385810d565efSmrgThese are called @dfn{linemarkers}. They are inserted as needed into 385910d565efSmrgthe output (but never within a string or character constant). They mean 386010d565efSmrgthat the following line originated in file @var{filename} at line 386110d565efSmrg@var{linenum}. @var{filename} will never contain any non-printing 386210d565efSmrgcharacters; they are replaced with octal escape sequences. 386310d565efSmrg 386410d565efSmrgAfter the file name comes zero or more flags, which are @samp{1}, 386510d565efSmrg@samp{2}, @samp{3}, or @samp{4}. If there are multiple flags, spaces 386610d565efSmrgseparate them. Here is what the flags mean: 386710d565efSmrg 386810d565efSmrg@table @samp 386910d565efSmrg@item 1 387010d565efSmrgThis indicates the start of a new file. 387110d565efSmrg@item 2 387210d565efSmrgThis indicates returning to a file (after having included another file). 387310d565efSmrg@item 3 387410d565efSmrgThis indicates that the following text comes from a system header file, 387510d565efSmrgso certain warnings should be suppressed. 387610d565efSmrg@item 4 387710d565efSmrgThis indicates that the following text should be treated as being 387810d565efSmrgwrapped in an implicit @code{extern "C"} block. 38790fc04c29Smrg@c maybe cross reference SYSTEM_IMPLICIT_EXTERN_C 388010d565efSmrg@end table 388110d565efSmrg 388210d565efSmrgAs an extension, the preprocessor accepts linemarkers in non-assembler 388310d565efSmrginput files. They are treated like the corresponding @samp{#line} 388410d565efSmrgdirective, (@pxref{Line Control}), except that trailing flags are 388510d565efSmrgpermitted, and are interpreted with the meanings described above. If 388610d565efSmrgmultiple flags are given, they must be in ascending order. 388710d565efSmrg 388810d565efSmrgSome directives may be duplicated in the output of the preprocessor. 388910d565efSmrgThese are @samp{#ident} (always), @samp{#pragma} (only if the 389010d565efSmrgpreprocessor does not handle the pragma itself), and @samp{#define} and 389110d565efSmrg@samp{#undef} (with certain debugging options). If this happens, the 389210d565efSmrg@samp{#} of the directive will always be in the first column, and there 389310d565efSmrgwill be no space between the @samp{#} and the directive name. If macro 389410d565efSmrgexpansion happens to generate tokens which might be mistaken for a 389510d565efSmrgduplicated directive, a space will be inserted between the @samp{#} and 389610d565efSmrgthe directive name. 389710d565efSmrg 389810d565efSmrg@node Traditional Mode 389910d565efSmrg@chapter Traditional Mode 390010d565efSmrg 390110d565efSmrgTraditional (pre-standard) C preprocessing is rather different from 390210d565efSmrgthe preprocessing specified by the standard. When the preprocessor 390310d565efSmrgis invoked with the 390410d565efSmrg@option{-traditional-cpp} option, it attempts to emulate a traditional 390510d565efSmrgpreprocessor. 390610d565efSmrg 390710d565efSmrgThis mode is not useful for compiling C code with GCC, 390810d565efSmrgbut is intended for use with non-C preprocessing applications. Thus 390910d565efSmrgtraditional mode semantics are supported only when invoking 391010d565efSmrgthe preprocessor explicitly, and not in the compiler front ends. 391110d565efSmrg 391210d565efSmrgThe implementation does not correspond precisely to the behavior of 391310d565efSmrgearly pre-standard versions of GCC, nor to any true traditional preprocessor. 391410d565efSmrgAfter all, inconsistencies among traditional implementations were a 391510d565efSmrgmajor motivation for C standardization. However, we intend that it 391610d565efSmrgshould be compatible with true traditional preprocessors in all ways 391710d565efSmrgthat actually matter. 391810d565efSmrg 391910d565efSmrg@menu 392010d565efSmrg* Traditional lexical analysis:: 392110d565efSmrg* Traditional macros:: 392210d565efSmrg* Traditional miscellany:: 392310d565efSmrg* Traditional warnings:: 392410d565efSmrg@end menu 392510d565efSmrg 392610d565efSmrg@node Traditional lexical analysis 392710d565efSmrg@section Traditional lexical analysis 392810d565efSmrg 392910d565efSmrgThe traditional preprocessor does not decompose its input into tokens 393010d565efSmrgthe same way a standards-conforming preprocessor does. The input is 393110d565efSmrgsimply treated as a stream of text with minimal internal form. 393210d565efSmrg 393310d565efSmrgThis implementation does not treat trigraphs (@pxref{trigraphs}) 393410d565efSmrgspecially since they were an invention of the standards committee. It 393510d565efSmrghandles arbitrarily-positioned escaped newlines properly and splices 393610d565efSmrgthe lines as you would expect; many traditional preprocessors did not 393710d565efSmrgdo this. 393810d565efSmrg 393910d565efSmrgThe form of horizontal whitespace in the input file is preserved in 394010d565efSmrgthe output. In particular, hard tabs remain hard tabs. This can be 394110d565efSmrguseful if, for example, you are preprocessing a Makefile. 394210d565efSmrg 394310d565efSmrgTraditional CPP only recognizes C-style block comments, and treats the 394410d565efSmrg@samp{/*} sequence as introducing a comment only if it lies outside 394510d565efSmrgquoted text. Quoted text is introduced by the usual single and double 394610d565efSmrgquotes, and also by an initial @samp{<} in a @code{#include} 394710d565efSmrgdirective. 394810d565efSmrg 394910d565efSmrgTraditionally, comments are completely removed and are not replaced 395010d565efSmrgwith a space. Since a traditional compiler does its own tokenization 395110d565efSmrgof the output of the preprocessor, this means that comments can 395210d565efSmrgeffectively be used as token paste operators. However, comments 395310d565efSmrgbehave like separators for text handled by the preprocessor itself, 395410d565efSmrgsince it doesn't re-lex its input. For example, in 395510d565efSmrg 395610d565efSmrg@smallexample 395710d565efSmrg#if foo/**/bar 395810d565efSmrg@end smallexample 395910d565efSmrg 396010d565efSmrg@noindent 396110d565efSmrg@samp{foo} and @samp{bar} are distinct identifiers and expanded 396210d565efSmrgseparately if they happen to be macros. In other words, this 396310d565efSmrgdirective is equivalent to 396410d565efSmrg 396510d565efSmrg@smallexample 396610d565efSmrg#if foo bar 396710d565efSmrg@end smallexample 396810d565efSmrg 396910d565efSmrg@noindent 397010d565efSmrgrather than 397110d565efSmrg 397210d565efSmrg@smallexample 397310d565efSmrg#if foobar 397410d565efSmrg@end smallexample 397510d565efSmrg 397610d565efSmrgGenerally speaking, in traditional mode an opening quote need not have 397710d565efSmrga matching closing quote. In particular, a macro may be defined with 397810d565efSmrgreplacement text that contains an unmatched quote. Of course, if you 397910d565efSmrgattempt to compile preprocessed output containing an unmatched quote 398010d565efSmrgyou will get a syntax error. 398110d565efSmrg 398210d565efSmrgHowever, all preprocessing directives other than @code{#define} 398310d565efSmrgrequire matching quotes. For example: 398410d565efSmrg 398510d565efSmrg@smallexample 398610d565efSmrg#define m This macro's fine and has an unmatched quote 398710d565efSmrg"/* This is not a comment. */ 398810d565efSmrg/* @r{This is a comment. The following #include directive 398910d565efSmrg is ill-formed.} */ 399010d565efSmrg#include <stdio.h 399110d565efSmrg@end smallexample 399210d565efSmrg 399310d565efSmrgJust as for the ISO preprocessor, what would be a closing quote can be 399410d565efSmrgescaped with a backslash to prevent the quoted text from closing. 399510d565efSmrg 399610d565efSmrg@node Traditional macros 399710d565efSmrg@section Traditional macros 399810d565efSmrg 399910d565efSmrgThe major difference between traditional and ISO macros is that the 400010d565efSmrgformer expand to text rather than to a token sequence. CPP removes 400110d565efSmrgall leading and trailing horizontal whitespace from a macro's 400210d565efSmrgreplacement text before storing it, but preserves the form of internal 400310d565efSmrgwhitespace. 400410d565efSmrg 400510d565efSmrgOne consequence is that it is legitimate for the replacement text to 400610d565efSmrgcontain an unmatched quote (@pxref{Traditional lexical analysis}). An 400710d565efSmrgunclosed string or character constant continues into the text 400810d565efSmrgfollowing the macro call. Similarly, the text at the end of a macro's 400910d565efSmrgexpansion can run together with the text after the macro invocation to 401010d565efSmrgproduce a single token. 401110d565efSmrg 401210d565efSmrgNormally comments are removed from the replacement text after the 401310d565efSmrgmacro is expanded, but if the @option{-CC} option is passed on the 401410d565efSmrgcommand-line comments are preserved. (In fact, the current 401510d565efSmrgimplementation removes comments even before saving the macro 401610d565efSmrgreplacement text, but it careful to do it in such a way that the 401710d565efSmrgobserved effect is identical even in the function-like macro case.) 401810d565efSmrg 401910d565efSmrgThe ISO stringizing operator @samp{#} and token paste operator 402010d565efSmrg@samp{##} have no special meaning. As explained later, an effect 402110d565efSmrgsimilar to these operators can be obtained in a different way. Macro 402210d565efSmrgnames that are embedded in quotes, either from the main file or after 402310d565efSmrgmacro replacement, do not expand. 402410d565efSmrg 402510d565efSmrgCPP replaces an unquoted object-like macro name with its replacement 402610d565efSmrgtext, and then rescans it for further macros to replace. Unlike 402710d565efSmrgstandard macro expansion, traditional macro expansion has no provision 402810d565efSmrgto prevent recursion. If an object-like macro appears unquoted in its 402910d565efSmrgreplacement text, it will be replaced again during the rescan pass, 403010d565efSmrgand so on @emph{ad infinitum}. GCC detects when it is expanding 403110d565efSmrgrecursive macros, emits an error message, and continues after the 403210d565efSmrgoffending macro invocation. 403310d565efSmrg 403410d565efSmrg@smallexample 403510d565efSmrg#define PLUS + 403610d565efSmrg#define INC(x) PLUS+x 403710d565efSmrgINC(foo); 403810d565efSmrg @expansion{} ++foo; 403910d565efSmrg@end smallexample 404010d565efSmrg 404110d565efSmrgFunction-like macros are similar in form but quite different in 404210d565efSmrgbehavior to their ISO counterparts. Their arguments are contained 404310d565efSmrgwithin parentheses, are comma-separated, and can cross physical lines. 404410d565efSmrgCommas within nested parentheses are not treated as argument 404510d565efSmrgseparators. Similarly, a quote in an argument cannot be left 404610d565efSmrgunclosed; a following comma or parenthesis that comes before the 404710d565efSmrgclosing quote is treated like any other character. There is no 404810d565efSmrgfacility for handling variadic macros. 404910d565efSmrg 405010d565efSmrgThis implementation removes all comments from macro arguments, unless 405110d565efSmrgthe @option{-C} option is given. The form of all other horizontal 405210d565efSmrgwhitespace in arguments is preserved, including leading and trailing 405310d565efSmrgwhitespace. In particular 405410d565efSmrg 405510d565efSmrg@smallexample 405610d565efSmrgf( ) 405710d565efSmrg@end smallexample 405810d565efSmrg 405910d565efSmrg@noindent 406010d565efSmrgis treated as an invocation of the macro @samp{f} with a single 406110d565efSmrgargument consisting of a single space. If you want to invoke a 406210d565efSmrgfunction-like macro that takes no arguments, you must not leave any 406310d565efSmrgwhitespace between the parentheses. 406410d565efSmrg 406510d565efSmrgIf a macro argument crosses a new line, the new line is replaced with 406610d565efSmrga space when forming the argument. If the previous line contained an 406710d565efSmrgunterminated quote, the following line inherits the quoted state. 406810d565efSmrg 406910d565efSmrgTraditional preprocessors replace parameters in the replacement text 407010d565efSmrgwith their arguments regardless of whether the parameters are within 407110d565efSmrgquotes or not. This provides a way to stringize arguments. For 407210d565efSmrgexample 407310d565efSmrg 407410d565efSmrg@smallexample 407510d565efSmrg#define str(x) "x" 407610d565efSmrgstr(/* @r{A comment} */some text ) 407710d565efSmrg @expansion{} "some text " 407810d565efSmrg@end smallexample 407910d565efSmrg 408010d565efSmrg@noindent 408110d565efSmrgNote that the comment is removed, but that the trailing space is 408210d565efSmrgpreserved. Here is an example of using a comment to effect token 408310d565efSmrgpasting. 408410d565efSmrg 408510d565efSmrg@smallexample 408610d565efSmrg#define suffix(x) foo_/**/x 408710d565efSmrgsuffix(bar) 408810d565efSmrg @expansion{} foo_bar 408910d565efSmrg@end smallexample 409010d565efSmrg 409110d565efSmrg@node Traditional miscellany 409210d565efSmrg@section Traditional miscellany 409310d565efSmrg 409410d565efSmrgHere are some things to be aware of when using the traditional 409510d565efSmrgpreprocessor. 409610d565efSmrg 409710d565efSmrg@itemize @bullet 409810d565efSmrg@item 409910d565efSmrgPreprocessing directives are recognized only when their leading 410010d565efSmrg@samp{#} appears in the first column. There can be no whitespace 410110d565efSmrgbetween the beginning of the line and the @samp{#}, but whitespace can 410210d565efSmrgfollow the @samp{#}. 410310d565efSmrg 410410d565efSmrg@item 410510d565efSmrgA true traditional C preprocessor does not recognize @samp{#error} or 410610d565efSmrg@samp{#pragma}, and may not recognize @samp{#elif}. CPP supports all 410710d565efSmrgthe directives in traditional mode that it supports in ISO mode, 410810d565efSmrgincluding extensions, with the exception that the effects of 410910d565efSmrg@samp{#pragma GCC poison} are undefined. 411010d565efSmrg 411110d565efSmrg@item 411210d565efSmrg__STDC__ is not defined. 411310d565efSmrg 411410d565efSmrg@item 411510d565efSmrgIf you use digraphs the behavior is undefined. 411610d565efSmrg 411710d565efSmrg@item 411810d565efSmrgIf a line that looks like a directive appears within macro arguments, 411910d565efSmrgthe behavior is undefined. 412010d565efSmrg 412110d565efSmrg@end itemize 412210d565efSmrg 412310d565efSmrg@node Traditional warnings 412410d565efSmrg@section Traditional warnings 412510d565efSmrgYou can request warnings about features that did not exist, or worked 412610d565efSmrgdifferently, in traditional C with the @option{-Wtraditional} option. 412710d565efSmrgGCC does not warn about features of ISO C which you must use when you 412810d565efSmrgare using a conforming compiler, such as the @samp{#} and @samp{##} 412910d565efSmrgoperators. 413010d565efSmrg 413110d565efSmrgPresently @option{-Wtraditional} warns about: 413210d565efSmrg 413310d565efSmrg@itemize @bullet 413410d565efSmrg@item 413510d565efSmrgMacro parameters that appear within string literals in the macro body. 413610d565efSmrgIn traditional C macro replacement takes place within string literals, 413710d565efSmrgbut does not in ISO C@. 413810d565efSmrg 413910d565efSmrg@item 414010d565efSmrgIn traditional C, some preprocessor directives did not exist. 414110d565efSmrgTraditional preprocessors would only consider a line to be a directive 414210d565efSmrgif the @samp{#} appeared in column 1 on the line. Therefore 414310d565efSmrg@option{-Wtraditional} warns about directives that traditional C 414410d565efSmrgunderstands but would ignore because the @samp{#} does not appear as the 414510d565efSmrgfirst character on the line. It also suggests you hide directives like 414610d565efSmrg@samp{#pragma} not understood by traditional C by indenting them. Some 414710d565efSmrgtraditional implementations would not recognize @samp{#elif}, so it 414810d565efSmrgsuggests avoiding it altogether. 414910d565efSmrg 415010d565efSmrg@item 415110d565efSmrgA function-like macro that appears without an argument list. In some 415210d565efSmrgtraditional preprocessors this was an error. In ISO C it merely means 415310d565efSmrgthat the macro is not expanded. 415410d565efSmrg 415510d565efSmrg@item 415610d565efSmrgThe unary plus operator. This did not exist in traditional C@. 415710d565efSmrg 415810d565efSmrg@item 415910d565efSmrgThe @samp{U} and @samp{LL} integer constant suffixes, which were not 416010d565efSmrgavailable in traditional C@. (Traditional C does support the @samp{L} 416110d565efSmrgsuffix for simple long integer constants.) You are not warned about 416210d565efSmrguses of these suffixes in macros defined in system headers. For 416310d565efSmrginstance, @code{UINT_MAX} may well be defined as @code{4294967295U}, but 416410d565efSmrgyou will not be warned if you use @code{UINT_MAX}. 416510d565efSmrg 416610d565efSmrgYou can usually avoid the warning, and the related warning about 416710d565efSmrgconstants which are so large that they are unsigned, by writing the 416810d565efSmrginteger constant in question in hexadecimal, with no U suffix. Take 416910d565efSmrgcare, though, because this gives the wrong result in exotic cases. 417010d565efSmrg@end itemize 417110d565efSmrg 417210d565efSmrg@node Implementation Details 417310d565efSmrg@chapter Implementation Details 417410d565efSmrg 417510d565efSmrgHere we document details of how the preprocessor's implementation 417610d565efSmrgaffects its user-visible behavior. You should try to avoid undue 417710d565efSmrgreliance on behavior described here, as it is possible that it will 417810d565efSmrgchange subtly in future implementations. 417910d565efSmrg 418010d565efSmrgAlso documented here are obsolete features still supported by CPP@. 418110d565efSmrg 418210d565efSmrg@menu 418310d565efSmrg* Implementation-defined behavior:: 418410d565efSmrg* Implementation limits:: 418510d565efSmrg* Obsolete Features:: 418610d565efSmrg@end menu 418710d565efSmrg 418810d565efSmrg@node Implementation-defined behavior 418910d565efSmrg@section Implementation-defined behavior 419010d565efSmrg@cindex implementation-defined behavior 419110d565efSmrg 419210d565efSmrgThis is how CPP behaves in all the cases which the C standard 419310d565efSmrgdescribes as @dfn{implementation-defined}. This term means that the 419410d565efSmrgimplementation is free to do what it likes, but must document its choice 419510d565efSmrgand stick to it. 419610d565efSmrg@c FIXME: Check the C++ standard for more implementation-defined stuff. 419710d565efSmrg 419810d565efSmrg@itemize @bullet 419910d565efSmrg@need 1000 420010d565efSmrg@item The mapping of physical source file multi-byte characters to the 420110d565efSmrgexecution character set. 420210d565efSmrg 420310d565efSmrgThe input character set can be specified using the 420410d565efSmrg@option{-finput-charset} option, while the execution character set may 420510d565efSmrgbe controlled using the @option{-fexec-charset} and 420610d565efSmrg@option{-fwide-exec-charset} options. 420710d565efSmrg 420810d565efSmrg@item Identifier characters. 420910d565efSmrg@anchor{Identifier characters} 421010d565efSmrg 421110d565efSmrgThe C and C++ standards allow identifiers to be composed of @samp{_} 421210d565efSmrgand the alphanumeric characters. C++ also allows universal character 421310d565efSmrgnames. C99 and later C standards permit both universal character 4214*ec02198aSmrgnames and implementation-defined characters. In both C and C++ modes, 4215*ec02198aSmrgGCC accepts in identifiers exactly those extended characters that 4216*ec02198aSmrgcorrespond to universal character names permitted by the chosen 4217*ec02198aSmrgstandard. 421810d565efSmrg 421910d565efSmrgGCC allows the @samp{$} character in identifiers as an extension for 422010d565efSmrgmost targets. This is true regardless of the @option{std=} switch, 422110d565efSmrgsince this extension cannot conflict with standards-conforming 422210d565efSmrgprograms. When preprocessing assembler, however, dollars are not 422310d565efSmrgidentifier characters by default. 422410d565efSmrg 422510d565efSmrgCurrently the targets that by default do not permit @samp{$} are AVR, 422610d565efSmrgIP2K, MMIX, MIPS Irix 3, ARM aout, and PowerPC targets for the AIX 422710d565efSmrgoperating system. 422810d565efSmrg 422910d565efSmrgYou can override the default with @option{-fdollars-in-identifiers} or 423010d565efSmrg@option{fno-dollars-in-identifiers}. @xref{fdollars-in-identifiers}. 423110d565efSmrg 423210d565efSmrg@item Non-empty sequences of whitespace characters. 423310d565efSmrg 423410d565efSmrgIn textual output, each whitespace sequence is collapsed to a single 423510d565efSmrgspace. For aesthetic reasons, the first token on each non-directive 423610d565efSmrgline of output is preceded with sufficient spaces that it appears in the 423710d565efSmrgsame column as it did in the original source file. 423810d565efSmrg 423910d565efSmrg@item The numeric value of character constants in preprocessor expressions. 424010d565efSmrg 424110d565efSmrgThe preprocessor and compiler interpret character constants in the 424210d565efSmrgsame way; i.e.@: escape sequences such as @samp{\a} are given the 424310d565efSmrgvalues they would have on the target machine. 424410d565efSmrg 424510d565efSmrgThe compiler evaluates a multi-character character constant a character 424610d565efSmrgat a time, shifting the previous value left by the number of bits per 424710d565efSmrgtarget character, and then or-ing in the bit-pattern of the new 424810d565efSmrgcharacter truncated to the width of a target character. The final 424910d565efSmrgbit-pattern is given type @code{int}, and is therefore signed, 425010d565efSmrgregardless of whether single characters are signed or not. 425110d565efSmrgIf there are more 425210d565efSmrgcharacters in the constant than would fit in the target @code{int} the 425310d565efSmrgcompiler issues a warning, and the excess leading characters are 425410d565efSmrgignored. 425510d565efSmrg 425610d565efSmrgFor example, @code{'ab'} for a target with an 8-bit @code{char} would be 425710d565efSmrginterpreted as @w{@samp{(int) ((unsigned char) 'a' * 256 + (unsigned char) 425810d565efSmrg'b')}}, and @code{'\234a'} as @w{@samp{(int) ((unsigned char) '\234' * 425910d565efSmrg256 + (unsigned char) 'a')}}. 426010d565efSmrg 426110d565efSmrg@item Source file inclusion. 426210d565efSmrg 426310d565efSmrgFor a discussion on how the preprocessor locates header files, 426410d565efSmrg@ref{Include Operation}. 426510d565efSmrg 426610d565efSmrg@item Interpretation of the filename resulting from a macro-expanded 426710d565efSmrg@samp{#include} directive. 426810d565efSmrg 426910d565efSmrg@xref{Computed Includes}. 427010d565efSmrg 427110d565efSmrg@item Treatment of a @samp{#pragma} directive that after macro-expansion 427210d565efSmrgresults in a standard pragma. 427310d565efSmrg 427410d565efSmrgNo macro expansion occurs on any @samp{#pragma} directive line, so the 427510d565efSmrgquestion does not arise. 427610d565efSmrg 427710d565efSmrgNote that GCC does not yet implement any of the standard 427810d565efSmrgpragmas. 427910d565efSmrg 428010d565efSmrg@end itemize 428110d565efSmrg 428210d565efSmrg@node Implementation limits 428310d565efSmrg@section Implementation limits 428410d565efSmrg@cindex implementation limits 428510d565efSmrg 428610d565efSmrgCPP has a small number of internal limits. This section lists the 428710d565efSmrglimits which the C standard requires to be no lower than some minimum, 428810d565efSmrgand all the others known. It is intended that there should be as few limits 428910d565efSmrgas possible. If you encounter an undocumented or inconvenient limit, 429010d565efSmrgplease report that as a bug. @xref{Bugs, , Reporting Bugs, gcc, Using 429110d565efSmrgthe GNU Compiler Collection (GCC)}. 429210d565efSmrg 429310d565efSmrgWhere we say something is limited @dfn{only by available memory}, that 429410d565efSmrgmeans that internal data structures impose no intrinsic limit, and space 429510d565efSmrgis allocated with @code{malloc} or equivalent. The actual limit will 429610d565efSmrgtherefore depend on many things, such as the size of other things 429710d565efSmrgallocated by the compiler at the same time, the amount of memory 429810d565efSmrgconsumed by other processes on the same computer, etc. 429910d565efSmrg 430010d565efSmrg@itemize @bullet 430110d565efSmrg 430210d565efSmrg@item Nesting levels of @samp{#include} files. 430310d565efSmrg 430410d565efSmrgWe impose an arbitrary limit of 200 levels, to avoid runaway recursion. 430510d565efSmrgThe standard requires at least 15 levels. 430610d565efSmrg 430710d565efSmrg@item Nesting levels of conditional inclusion. 430810d565efSmrg 430910d565efSmrgThe C standard mandates this be at least 63. CPP is limited only by 431010d565efSmrgavailable memory. 431110d565efSmrg 431210d565efSmrg@item Levels of parenthesized expressions within a full expression. 431310d565efSmrg 431410d565efSmrgThe C standard requires this to be at least 63. In preprocessor 431510d565efSmrgconditional expressions, it is limited only by available memory. 431610d565efSmrg 431710d565efSmrg@item Significant initial characters in an identifier or macro name. 431810d565efSmrg 431910d565efSmrgThe preprocessor treats all characters as significant. The C standard 432010d565efSmrgrequires only that the first 63 be significant. 432110d565efSmrg 432210d565efSmrg@item Number of macros simultaneously defined in a single translation unit. 432310d565efSmrg 432410d565efSmrgThe standard requires at least 4095 be possible. CPP is limited only 432510d565efSmrgby available memory. 432610d565efSmrg 432710d565efSmrg@item Number of parameters in a macro definition and arguments in a macro call. 432810d565efSmrg 432910d565efSmrgWe allow @code{USHRT_MAX}, which is no smaller than 65,535. The minimum 433010d565efSmrgrequired by the standard is 127. 433110d565efSmrg 433210d565efSmrg@item Number of characters on a logical source line. 433310d565efSmrg 433410d565efSmrgThe C standard requires a minimum of 4096 be permitted. CPP places 433510d565efSmrgno limits on this, but you may get incorrect column numbers reported in 433610d565efSmrgdiagnostics for lines longer than 65,535 characters. 433710d565efSmrg 433810d565efSmrg@item Maximum size of a source file. 433910d565efSmrg 434010d565efSmrgThe standard does not specify any lower limit on the maximum size of a 434110d565efSmrgsource file. GNU cpp maps files into memory, so it is limited by the 434210d565efSmrgavailable address space. This is generally at least two gigabytes. 434310d565efSmrgDepending on the operating system, the size of physical memory may or 434410d565efSmrgmay not be a limitation. 434510d565efSmrg 434610d565efSmrg@end itemize 434710d565efSmrg 434810d565efSmrg@node Obsolete Features 434910d565efSmrg@section Obsolete Features 435010d565efSmrg 435110d565efSmrgCPP has some features which are present mainly for compatibility with 435210d565efSmrgolder programs. We discourage their use in new code. In some cases, 435310d565efSmrgwe plan to remove the feature in a future version of GCC@. 435410d565efSmrg 435510d565efSmrg@subsection Assertions 435610d565efSmrg@cindex assertions 435710d565efSmrg 435810d565efSmrg@dfn{Assertions} are a deprecated alternative to macros in writing 435910d565efSmrgconditionals to test what sort of computer or system the compiled 436010d565efSmrgprogram will run on. Assertions are usually predefined, but you can 436110d565efSmrgdefine them with preprocessing directives or command-line options. 436210d565efSmrg 436310d565efSmrgAssertions were intended to provide a more systematic way to describe 436410d565efSmrgthe compiler's target system and we added them for compatibility with 436510d565efSmrgexisting compilers. In practice they are just as unpredictable as the 436610d565efSmrgsystem-specific predefined macros. In addition, they are not part of 436710d565efSmrgany standard, and only a few compilers support them. 436810d565efSmrgTherefore, the use of assertions is @strong{less} portable than the use 436910d565efSmrgof system-specific predefined macros. We recommend you do not use them at 437010d565efSmrgall. 437110d565efSmrg 437210d565efSmrg@cindex predicates 437310d565efSmrgAn assertion looks like this: 437410d565efSmrg 437510d565efSmrg@smallexample 437610d565efSmrg#@var{predicate} (@var{answer}) 437710d565efSmrg@end smallexample 437810d565efSmrg 437910d565efSmrg@noindent 438010d565efSmrg@var{predicate} must be a single identifier. @var{answer} can be any 438110d565efSmrgsequence of tokens; all characters are significant except for leading 438210d565efSmrgand trailing whitespace, and differences in internal whitespace 438310d565efSmrgsequences are ignored. (This is similar to the rules governing macro 438410d565efSmrgredefinition.) Thus, @code{(x + y)} is different from @code{(x+y)} but 438510d565efSmrgequivalent to @code{@w{( x + y )}}. Parentheses do not nest inside an 438610d565efSmrganswer. 438710d565efSmrg 438810d565efSmrg@cindex testing predicates 438910d565efSmrgTo test an assertion, you write it in an @samp{#if}. For example, this 439010d565efSmrgconditional succeeds if either @code{vax} or @code{ns16000} has been 439110d565efSmrgasserted as an answer for @code{machine}. 439210d565efSmrg 439310d565efSmrg@smallexample 439410d565efSmrg#if #machine (vax) || #machine (ns16000) 439510d565efSmrg@end smallexample 439610d565efSmrg 439710d565efSmrg@noindent 439810d565efSmrgYou can test whether @emph{any} answer is asserted for a predicate by 439910d565efSmrgomitting the answer in the conditional: 440010d565efSmrg 440110d565efSmrg@smallexample 440210d565efSmrg#if #machine 440310d565efSmrg@end smallexample 440410d565efSmrg 440510d565efSmrg@findex #assert 440610d565efSmrgAssertions are made with the @samp{#assert} directive. Its sole 440710d565efSmrgargument is the assertion to make, without the leading @samp{#} that 440810d565efSmrgidentifies assertions in conditionals. 440910d565efSmrg 441010d565efSmrg@smallexample 441110d565efSmrg#assert @var{predicate} (@var{answer}) 441210d565efSmrg@end smallexample 441310d565efSmrg 441410d565efSmrg@noindent 441510d565efSmrgYou may make several assertions with the same predicate and different 441610d565efSmrganswers. Subsequent assertions do not override previous ones for the 441710d565efSmrgsame predicate. All the answers for any given predicate are 441810d565efSmrgsimultaneously true. 441910d565efSmrg 442010d565efSmrg@cindex assertions, canceling 442110d565efSmrg@findex #unassert 442210d565efSmrgAssertions can be canceled with the @samp{#unassert} directive. It 442310d565efSmrghas the same syntax as @samp{#assert}. In that form it cancels only the 442410d565efSmrganswer which was specified on the @samp{#unassert} line; other answers 442510d565efSmrgfor that predicate remain true. You can cancel an entire predicate by 442610d565efSmrgleaving out the answer: 442710d565efSmrg 442810d565efSmrg@smallexample 442910d565efSmrg#unassert @var{predicate} 443010d565efSmrg@end smallexample 443110d565efSmrg 443210d565efSmrg@noindent 443310d565efSmrgIn either form, if no such assertion has been made, @samp{#unassert} has 443410d565efSmrgno effect. 443510d565efSmrg 443610d565efSmrgYou can also make or cancel assertions using command-line options. 443710d565efSmrg@xref{Invocation}. 443810d565efSmrg 443910d565efSmrg@node Invocation 444010d565efSmrg@chapter Invocation 444110d565efSmrg@cindex invocation 444210d565efSmrg@cindex command line 444310d565efSmrg 444410d565efSmrgMost often when you use the C preprocessor you do not have to invoke it 444510d565efSmrgexplicitly: the C compiler does so automatically. However, the 444610d565efSmrgpreprocessor is sometimes useful on its own. You can invoke the 444710d565efSmrgpreprocessor either with the @command{cpp} command, or via @command{gcc -E}. 444810d565efSmrgIn GCC, the preprocessor is actually integrated with the compiler 444910d565efSmrgrather than a separate program, and both of these commands invoke 445010d565efSmrgGCC and tell it to stop after the preprocessing phase. 445110d565efSmrg 445210d565efSmrgThe @command{cpp} options listed here are also accepted by 445310d565efSmrg@command{gcc} and have the same meaning. Likewise the @command{cpp} 445410d565efSmrgcommand accepts all the usual @command{gcc} driver options, although those 445510d565efSmrgpertaining to compilation phases after preprocessing are ignored. 445610d565efSmrg 445710d565efSmrgOnly options specific to preprocessing behavior are documented here. 445810d565efSmrgRefer to the GCC manual for full documentation of other driver options. 445910d565efSmrg 446010d565efSmrg@ignore 446110d565efSmrg@c man begin SYNOPSIS 446210d565efSmrgcpp [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}] 446310d565efSmrg [@option{-I}@var{dir}@dots{}] [@option{-iquote}@var{dir}@dots{}] 446410d565efSmrg [@option{-iremap}@var{src}:@var{dst}] 446510d565efSmrg [@option{-W}@var{warn}@dots{}] 446610d565efSmrg [@option{-M}|@option{-MM}] [@option{-MG}] [@option{-MF} @var{filename}] 446710d565efSmrg [@option{-MP}] [@option{-MQ} @var{target}@dots{}] 446810d565efSmrg [@option{-MT} @var{target}@dots{}] 446910d565efSmrg @var{infile} [[@option{-o}] @var{outfile}] 447010d565efSmrg 447110d565efSmrgOnly the most useful options are given above; see below for a more 447210d565efSmrgcomplete list of preprocessor-specific options. 447310d565efSmrgIn addition, @command{cpp} accepts most @command{gcc} driver options, which 447410d565efSmrgare not listed here. Refer to the GCC documentation for details. 447510d565efSmrg@c man end 447610d565efSmrg@c man begin SEEALSO 447710d565efSmrggpl(7), gfdl(7), fsf-funding(7), 447810d565efSmrggcc(1), and the Info entries for @file{cpp} and @file{gcc}. 447910d565efSmrg@c man end 448010d565efSmrg@end ignore 448110d565efSmrg 448210d565efSmrg@c man begin OPTIONS 448310d565efSmrgThe @command{cpp} command expects two file names as arguments, @var{infile} and 448410d565efSmrg@var{outfile}. The preprocessor reads @var{infile} together with any 448510d565efSmrgother files it specifies with @samp{#include}. All the output generated 448610d565efSmrgby the combined input files is written in @var{outfile}. 448710d565efSmrg 448810d565efSmrgEither @var{infile} or @var{outfile} may be @option{-}, which as 448910d565efSmrg@var{infile} means to read from standard input and as @var{outfile} 449010d565efSmrgmeans to write to standard output. If either file is omitted, it 449110d565efSmrgmeans the same as if @option{-} had been specified for that file. 449210d565efSmrgYou can also use the @option{-o @var{outfile}} option to specify the 449310d565efSmrgoutput file. 449410d565efSmrg 449510d565efSmrgUnless otherwise noted, or the option ends in @samp{=}, all options 449610d565efSmrgwhich take an argument may have that argument appear either immediately 449710d565efSmrgafter the option, or with a space between option and argument: 449810d565efSmrg@option{-Ifoo} and @option{-I foo} have the same effect. 449910d565efSmrg 450010d565efSmrg@cindex grouping options 450110d565efSmrg@cindex options, grouping 450210d565efSmrgMany options have multi-letter names; therefore multiple single-letter 450310d565efSmrgoptions may @emph{not} be grouped: @option{-dM} is very different from 450410d565efSmrg@w{@samp{-d -M}}. 450510d565efSmrg 450610d565efSmrg@cindex options 450710d565efSmrg 450810d565efSmrg@table @gcctabopt 450910d565efSmrg@include cppopts.texi 451010d565efSmrg@include cppdiropts.texi 451110d565efSmrg@include cppwarnopts.texi 451210d565efSmrg@end table 451310d565efSmrg@c man end 451410d565efSmrg 451510d565efSmrg@node Environment Variables 451610d565efSmrg@chapter Environment Variables 451710d565efSmrg@cindex environment variables 451810d565efSmrg@c man begin ENVIRONMENT 451910d565efSmrg 452010d565efSmrgThis section describes the environment variables that affect how CPP 452110d565efSmrgoperates. You can use them to specify directories or prefixes to use 452210d565efSmrgwhen searching for include files, or to control dependency output. 452310d565efSmrg 452410d565efSmrgNote that you can also specify places to search using options such as 452510d565efSmrg@option{-I}, and control dependency output with options like 452610d565efSmrg@option{-M} (@pxref{Invocation}). These take precedence over 452710d565efSmrgenvironment variables, which in turn take precedence over the 452810d565efSmrgconfiguration of GCC@. 452910d565efSmrg 453010d565efSmrg@include cppenv.texi 453110d565efSmrg@c man end 453210d565efSmrg 453310d565efSmrg@page 453410d565efSmrg@include fdl.texi 453510d565efSmrg 453610d565efSmrg@page 453710d565efSmrg@node Index of Directives 453810d565efSmrg@unnumbered Index of Directives 453910d565efSmrg@printindex fn 454010d565efSmrg 454110d565efSmrg@node Option Index 454210d565efSmrg@unnumbered Option Index 454310d565efSmrg@noindent 454410d565efSmrgCPP's command-line options and environment variables are indexed here 454510d565efSmrgwithout any initial @samp{-} or @samp{--}. 454610d565efSmrg@printindex op 454710d565efSmrg 454810d565efSmrg@page 454910d565efSmrg@node Concept Index 455010d565efSmrg@unnumbered Concept Index 455110d565efSmrg@printindex cp 455210d565efSmrg 455310d565efSmrg@bye 4554