1*e4b17023SJohn Marino\input texinfo 2*e4b17023SJohn Marino@setfilename cpp.info 3*e4b17023SJohn Marino@settitle The C Preprocessor 4*e4b17023SJohn Marino@setchapternewpage off 5*e4b17023SJohn Marino@c @smallbook 6*e4b17023SJohn Marino@c @cropmarks 7*e4b17023SJohn Marino@c @finalout 8*e4b17023SJohn Marino 9*e4b17023SJohn Marino@include gcc-common.texi 10*e4b17023SJohn Marino 11*e4b17023SJohn Marino@copying 12*e4b17023SJohn Marino@c man begin COPYRIGHT 13*e4b17023SJohn MarinoCopyright @copyright{} 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 14*e4b17023SJohn Marino1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 15*e4b17023SJohn Marino2008, 2009, 2010, 2011 16*e4b17023SJohn MarinoFree Software Foundation, Inc. 17*e4b17023SJohn Marino 18*e4b17023SJohn MarinoPermission is granted to copy, distribute and/or modify this document 19*e4b17023SJohn Marinounder the terms of the GNU Free Documentation License, Version 1.3 or 20*e4b17023SJohn Marinoany later version published by the Free Software Foundation. A copy of 21*e4b17023SJohn Marinothe license is included in the 22*e4b17023SJohn Marino@c man end 23*e4b17023SJohn Marinosection entitled ``GNU Free Documentation License''. 24*e4b17023SJohn Marino@ignore 25*e4b17023SJohn Marino@c man begin COPYRIGHT 26*e4b17023SJohn Marinoman page gfdl(7). 27*e4b17023SJohn Marino@c man end 28*e4b17023SJohn Marino@end ignore 29*e4b17023SJohn Marino 30*e4b17023SJohn Marino@c man begin COPYRIGHT 31*e4b17023SJohn MarinoThis manual contains no Invariant Sections. The Front-Cover Texts are 32*e4b17023SJohn Marino(a) (see below), and the Back-Cover Texts are (b) (see below). 33*e4b17023SJohn Marino 34*e4b17023SJohn Marino(a) The FSF's Front-Cover Text is: 35*e4b17023SJohn Marino 36*e4b17023SJohn Marino A GNU Manual 37*e4b17023SJohn Marino 38*e4b17023SJohn Marino(b) The FSF's Back-Cover Text is: 39*e4b17023SJohn Marino 40*e4b17023SJohn Marino You have freedom to copy and modify this GNU Manual, like GNU 41*e4b17023SJohn Marino software. Copies published by the Free Software Foundation raise 42*e4b17023SJohn Marino funds for GNU development. 43*e4b17023SJohn Marino@c man end 44*e4b17023SJohn Marino@end copying 45*e4b17023SJohn Marino 46*e4b17023SJohn Marino@c Create a separate index for command line options. 47*e4b17023SJohn Marino@defcodeindex op 48*e4b17023SJohn Marino@syncodeindex vr op 49*e4b17023SJohn Marino 50*e4b17023SJohn Marino@c Used in cppopts.texi and cppenv.texi. 51*e4b17023SJohn Marino@set cppmanual 52*e4b17023SJohn Marino 53*e4b17023SJohn Marino@ifinfo 54*e4b17023SJohn Marino@dircategory Software development 55*e4b17023SJohn Marino@direntry 56*e4b17023SJohn Marino* Cpp: (cpp). The GNU C preprocessor. 57*e4b17023SJohn Marino@end direntry 58*e4b17023SJohn Marino@end ifinfo 59*e4b17023SJohn Marino 60*e4b17023SJohn Marino@titlepage 61*e4b17023SJohn Marino@title The C Preprocessor 62*e4b17023SJohn Marino@versionsubtitle 63*e4b17023SJohn Marino@author Richard M. Stallman, Zachary Weinberg 64*e4b17023SJohn Marino@page 65*e4b17023SJohn Marino@c There is a fill at the bottom of the page, so we need a filll to 66*e4b17023SJohn Marino@c override it. 67*e4b17023SJohn Marino@vskip 0pt plus 1filll 68*e4b17023SJohn Marino@insertcopying 69*e4b17023SJohn Marino@end titlepage 70*e4b17023SJohn Marino@contents 71*e4b17023SJohn Marino@page 72*e4b17023SJohn Marino 73*e4b17023SJohn Marino@ifnottex 74*e4b17023SJohn Marino@node Top 75*e4b17023SJohn Marino@top 76*e4b17023SJohn MarinoThe C preprocessor implements the macro language used to transform C, 77*e4b17023SJohn MarinoC++, and Objective-C programs before they are compiled. It can also be 78*e4b17023SJohn Marinouseful on its own. 79*e4b17023SJohn Marino 80*e4b17023SJohn Marino@menu 81*e4b17023SJohn Marino* Overview:: 82*e4b17023SJohn Marino* Header Files:: 83*e4b17023SJohn Marino* Macros:: 84*e4b17023SJohn Marino* Conditionals:: 85*e4b17023SJohn Marino* Diagnostics:: 86*e4b17023SJohn Marino* Line Control:: 87*e4b17023SJohn Marino* Pragmas:: 88*e4b17023SJohn Marino* Other Directives:: 89*e4b17023SJohn Marino* Preprocessor Output:: 90*e4b17023SJohn Marino* Traditional Mode:: 91*e4b17023SJohn Marino* Implementation Details:: 92*e4b17023SJohn Marino* Invocation:: 93*e4b17023SJohn Marino* Environment Variables:: 94*e4b17023SJohn Marino* GNU Free Documentation License:: 95*e4b17023SJohn Marino* Index of Directives:: 96*e4b17023SJohn Marino* Option Index:: 97*e4b17023SJohn Marino* Concept Index:: 98*e4b17023SJohn Marino 99*e4b17023SJohn Marino@detailmenu 100*e4b17023SJohn Marino --- The Detailed Node Listing --- 101*e4b17023SJohn Marino 102*e4b17023SJohn MarinoOverview 103*e4b17023SJohn Marino 104*e4b17023SJohn Marino* Character sets:: 105*e4b17023SJohn Marino* Initial processing:: 106*e4b17023SJohn Marino* Tokenization:: 107*e4b17023SJohn Marino* The preprocessing language:: 108*e4b17023SJohn Marino 109*e4b17023SJohn MarinoHeader Files 110*e4b17023SJohn Marino 111*e4b17023SJohn Marino* Include Syntax:: 112*e4b17023SJohn Marino* Include Operation:: 113*e4b17023SJohn Marino* Search Path:: 114*e4b17023SJohn Marino* Once-Only Headers:: 115*e4b17023SJohn Marino* Alternatives to Wrapper #ifndef:: 116*e4b17023SJohn Marino* Computed Includes:: 117*e4b17023SJohn Marino* Wrapper Headers:: 118*e4b17023SJohn Marino* System Headers:: 119*e4b17023SJohn Marino 120*e4b17023SJohn MarinoMacros 121*e4b17023SJohn Marino 122*e4b17023SJohn Marino* Object-like Macros:: 123*e4b17023SJohn Marino* Function-like Macros:: 124*e4b17023SJohn Marino* Macro Arguments:: 125*e4b17023SJohn Marino* Stringification:: 126*e4b17023SJohn Marino* Concatenation:: 127*e4b17023SJohn Marino* Variadic Macros:: 128*e4b17023SJohn Marino* Predefined Macros:: 129*e4b17023SJohn Marino* Undefining and Redefining Macros:: 130*e4b17023SJohn Marino* Directives Within Macro Arguments:: 131*e4b17023SJohn Marino* Macro Pitfalls:: 132*e4b17023SJohn Marino 133*e4b17023SJohn MarinoPredefined Macros 134*e4b17023SJohn Marino 135*e4b17023SJohn Marino* Standard Predefined Macros:: 136*e4b17023SJohn Marino* Common Predefined Macros:: 137*e4b17023SJohn Marino* System-specific Predefined Macros:: 138*e4b17023SJohn Marino* C++ Named Operators:: 139*e4b17023SJohn Marino 140*e4b17023SJohn MarinoMacro Pitfalls 141*e4b17023SJohn Marino 142*e4b17023SJohn Marino* Misnesting:: 143*e4b17023SJohn Marino* Operator Precedence Problems:: 144*e4b17023SJohn Marino* Swallowing the Semicolon:: 145*e4b17023SJohn Marino* Duplication of Side Effects:: 146*e4b17023SJohn Marino* Self-Referential Macros:: 147*e4b17023SJohn Marino* Argument Prescan:: 148*e4b17023SJohn Marino* Newlines in Arguments:: 149*e4b17023SJohn Marino 150*e4b17023SJohn MarinoConditionals 151*e4b17023SJohn Marino 152*e4b17023SJohn Marino* Conditional Uses:: 153*e4b17023SJohn Marino* Conditional Syntax:: 154*e4b17023SJohn Marino* Deleted Code:: 155*e4b17023SJohn Marino 156*e4b17023SJohn MarinoConditional Syntax 157*e4b17023SJohn Marino 158*e4b17023SJohn Marino* Ifdef:: 159*e4b17023SJohn Marino* If:: 160*e4b17023SJohn Marino* Defined:: 161*e4b17023SJohn Marino* Else:: 162*e4b17023SJohn Marino* Elif:: 163*e4b17023SJohn Marino 164*e4b17023SJohn MarinoImplementation Details 165*e4b17023SJohn Marino 166*e4b17023SJohn Marino* Implementation-defined behavior:: 167*e4b17023SJohn Marino* Implementation limits:: 168*e4b17023SJohn Marino* Obsolete Features:: 169*e4b17023SJohn Marino* Differences from previous versions:: 170*e4b17023SJohn Marino 171*e4b17023SJohn MarinoObsolete Features 172*e4b17023SJohn Marino 173*e4b17023SJohn Marino* Obsolete Features:: 174*e4b17023SJohn Marino 175*e4b17023SJohn Marino@end detailmenu 176*e4b17023SJohn Marino@end menu 177*e4b17023SJohn Marino 178*e4b17023SJohn Marino@insertcopying 179*e4b17023SJohn Marino@end ifnottex 180*e4b17023SJohn Marino 181*e4b17023SJohn Marino@node Overview 182*e4b17023SJohn Marino@chapter Overview 183*e4b17023SJohn Marino@c man begin DESCRIPTION 184*e4b17023SJohn MarinoThe C preprocessor, often known as @dfn{cpp}, is a @dfn{macro processor} 185*e4b17023SJohn Marinothat is used automatically by the C compiler to transform your program 186*e4b17023SJohn Marinobefore compilation. It is called a macro processor because it allows 187*e4b17023SJohn Marinoyou to define @dfn{macros}, which are brief abbreviations for longer 188*e4b17023SJohn Marinoconstructs. 189*e4b17023SJohn Marino 190*e4b17023SJohn MarinoThe C preprocessor is intended to be used only with C, C++, and 191*e4b17023SJohn MarinoObjective-C source code. In the past, it has been abused as a general 192*e4b17023SJohn Marinotext processor. It will choke on input which does not obey C's lexical 193*e4b17023SJohn Marinorules. For example, apostrophes will be interpreted as the beginning of 194*e4b17023SJohn Marinocharacter constants, and cause errors. Also, you cannot rely on it 195*e4b17023SJohn Marinopreserving characteristics of the input which are not significant to 196*e4b17023SJohn MarinoC-family languages. If a Makefile is preprocessed, all the hard tabs 197*e4b17023SJohn Marinowill be removed, and the Makefile will not work. 198*e4b17023SJohn Marino 199*e4b17023SJohn MarinoHaving said that, you can often get away with using cpp on things which 200*e4b17023SJohn Marinoare not C@. Other Algol-ish programming languages are often safe 201*e4b17023SJohn Marino(Pascal, Ada, etc.) So is assembly, with caution. @option{-traditional-cpp} 202*e4b17023SJohn Marinomode preserves more white space, and is otherwise more permissive. Many 203*e4b17023SJohn Marinoof the problems can be avoided by writing C or C++ style comments 204*e4b17023SJohn Marinoinstead of native language comments, and keeping macros simple. 205*e4b17023SJohn Marino 206*e4b17023SJohn MarinoWherever possible, you should use a preprocessor geared to the language 207*e4b17023SJohn Marinoyou are writing in. Modern versions of the GNU assembler have macro 208*e4b17023SJohn Marinofacilities. Most high level programming languages have their own 209*e4b17023SJohn Marinoconditional compilation and inclusion mechanism. If all else fails, 210*e4b17023SJohn Marinotry a true general text processor, such as GNU M4. 211*e4b17023SJohn Marino 212*e4b17023SJohn MarinoC preprocessors vary in some details. This manual discusses the GNU C 213*e4b17023SJohn Marinopreprocessor, which provides a small superset of the features of ISO 214*e4b17023SJohn MarinoStandard C@. In its default mode, the GNU C preprocessor does not do a 215*e4b17023SJohn Marinofew things required by the standard. These are features which are 216*e4b17023SJohn Marinorarely, if ever, used, and may cause surprising changes to the meaning 217*e4b17023SJohn Marinoof a program which does not expect them. To get strict ISO Standard C, 218*e4b17023SJohn Marinoyou should use the @option{-std=c90}, @option{-std=c99} or 219*e4b17023SJohn Marino@option{-std=c11} options, depending 220*e4b17023SJohn Marinoon which version of the standard you want. To get all the mandatory 221*e4b17023SJohn Marinodiagnostics, you must also use @option{-pedantic}. @xref{Invocation}. 222*e4b17023SJohn Marino 223*e4b17023SJohn MarinoThis manual describes the behavior of the ISO preprocessor. To 224*e4b17023SJohn Marinominimize gratuitous differences, where the ISO preprocessor's 225*e4b17023SJohn Marinobehavior does not conflict with traditional semantics, the 226*e4b17023SJohn Marinotraditional preprocessor should behave the same way. The various 227*e4b17023SJohn Marinodifferences that do exist are detailed in the section @ref{Traditional 228*e4b17023SJohn MarinoMode}. 229*e4b17023SJohn Marino 230*e4b17023SJohn MarinoFor clarity, unless noted otherwise, references to @samp{CPP} in this 231*e4b17023SJohn Marinomanual refer to GNU CPP@. 232*e4b17023SJohn Marino@c man end 233*e4b17023SJohn Marino 234*e4b17023SJohn Marino@menu 235*e4b17023SJohn Marino* Character sets:: 236*e4b17023SJohn Marino* Initial processing:: 237*e4b17023SJohn Marino* Tokenization:: 238*e4b17023SJohn Marino* The preprocessing language:: 239*e4b17023SJohn Marino@end menu 240*e4b17023SJohn Marino 241*e4b17023SJohn Marino@node Character sets 242*e4b17023SJohn Marino@section Character sets 243*e4b17023SJohn Marino 244*e4b17023SJohn MarinoSource code character set processing in C and related languages is 245*e4b17023SJohn Marinorather complicated. The C standard discusses two character sets, but 246*e4b17023SJohn Marinothere are really at least four. 247*e4b17023SJohn Marino 248*e4b17023SJohn MarinoThe files input to CPP might be in any character set at all. CPP's 249*e4b17023SJohn Marinovery first action, before it even looks for line boundaries, is to 250*e4b17023SJohn Marinoconvert the file into the character set it uses for internal 251*e4b17023SJohn Marinoprocessing. That set is what the C standard calls the @dfn{source} 252*e4b17023SJohn Marinocharacter set. It must be isomorphic with ISO 10646, also known as 253*e4b17023SJohn MarinoUnicode. CPP uses the UTF-8 encoding of Unicode. 254*e4b17023SJohn Marino 255*e4b17023SJohn MarinoThe character sets of the input files are specified using the 256*e4b17023SJohn Marino@option{-finput-charset=} option. 257*e4b17023SJohn Marino 258*e4b17023SJohn MarinoAll preprocessing work (the subject of the rest of this manual) is 259*e4b17023SJohn Marinocarried out in the source character set. If you request textual 260*e4b17023SJohn Marinooutput from the preprocessor with the @option{-E} option, it will be 261*e4b17023SJohn Marinoin UTF-8. 262*e4b17023SJohn Marino 263*e4b17023SJohn MarinoAfter preprocessing is complete, string and character constants are 264*e4b17023SJohn Marinoconverted again, into the @dfn{execution} character set. This 265*e4b17023SJohn Marinocharacter set is under control of the user; the default is UTF-8, 266*e4b17023SJohn Marinomatching the source character set. Wide string and character 267*e4b17023SJohn Marinoconstants have their own character set, which is not called out 268*e4b17023SJohn Marinospecifically in the standard. Again, it is under control of the user. 269*e4b17023SJohn MarinoThe default is UTF-16 or UTF-32, whichever fits in the target's 270*e4b17023SJohn Marino@code{wchar_t} type, in the target machine's byte 271*e4b17023SJohn Marinoorder.@footnote{UTF-16 does not meet the requirements of the C 272*e4b17023SJohn Marinostandard for a wide character set, but the choice of 16-bit 273*e4b17023SJohn Marino@code{wchar_t} is enshrined in some system ABIs so we cannot fix 274*e4b17023SJohn Marinothis.} Octal and hexadecimal escape sequences do not undergo 275*e4b17023SJohn Marinoconversion; @t{'\x12'} has the value 0x12 regardless of the currently 276*e4b17023SJohn Marinoselected execution character set. All other escapes are replaced by 277*e4b17023SJohn Marinothe character in the source character set that they represent, then 278*e4b17023SJohn Marinoconverted to the execution character set, just like unescaped 279*e4b17023SJohn Marinocharacters. 280*e4b17023SJohn Marino 281*e4b17023SJohn MarinoUnless the experimental @option{-fextended-identifiers} option is used, 282*e4b17023SJohn MarinoGCC does not permit the use of characters outside the ASCII range, nor 283*e4b17023SJohn Marino@samp{\u} and @samp{\U} escapes, in identifiers. Even with that 284*e4b17023SJohn Marinooption, characters outside the ASCII range can only be specified with 285*e4b17023SJohn Marinothe @samp{\u} and @samp{\U} escapes, not used directly in identifiers. 286*e4b17023SJohn Marino 287*e4b17023SJohn Marino@node Initial processing 288*e4b17023SJohn Marino@section Initial processing 289*e4b17023SJohn Marino 290*e4b17023SJohn MarinoThe preprocessor performs a series of textual transformations on its 291*e4b17023SJohn Marinoinput. These happen before all other processing. Conceptually, they 292*e4b17023SJohn Marinohappen in a rigid order, and the entire file is run through each 293*e4b17023SJohn Marinotransformation before the next one begins. CPP actually does them 294*e4b17023SJohn Marinoall at once, for performance reasons. These transformations correspond 295*e4b17023SJohn Marinoroughly to the first three ``phases of translation'' described in the C 296*e4b17023SJohn Marinostandard. 297*e4b17023SJohn Marino 298*e4b17023SJohn Marino@enumerate 299*e4b17023SJohn Marino@item 300*e4b17023SJohn Marino@cindex line endings 301*e4b17023SJohn MarinoThe input file is read into memory and broken into lines. 302*e4b17023SJohn Marino 303*e4b17023SJohn MarinoDifferent systems use different conventions to indicate the end of a 304*e4b17023SJohn Marinoline. GCC accepts the ASCII control sequences @kbd{LF}, @kbd{@w{CR 305*e4b17023SJohn MarinoLF}} and @kbd{CR} as end-of-line markers. These are the canonical 306*e4b17023SJohn Marinosequences used by Unix, DOS and VMS, and the classic Mac OS (before 307*e4b17023SJohn MarinoOSX) respectively. You may therefore safely copy source code written 308*e4b17023SJohn Marinoon any of those systems to a different one and use it without 309*e4b17023SJohn Marinoconversion. (GCC may lose track of the current line number if a file 310*e4b17023SJohn Marinodoesn't consistently use one convention, as sometimes happens when it 311*e4b17023SJohn Marinois edited on computers with different conventions that share a network 312*e4b17023SJohn Marinofile system.) 313*e4b17023SJohn Marino 314*e4b17023SJohn MarinoIf the last line of any input file lacks an end-of-line marker, the end 315*e4b17023SJohn Marinoof the file is considered to implicitly supply one. The C standard says 316*e4b17023SJohn Marinothat this condition provokes undefined behavior, so GCC will emit a 317*e4b17023SJohn Marinowarning message. 318*e4b17023SJohn Marino 319*e4b17023SJohn Marino@item 320*e4b17023SJohn Marino@cindex trigraphs 321*e4b17023SJohn Marino@anchor{trigraphs}If trigraphs are enabled, they are replaced by their 322*e4b17023SJohn Marinocorresponding single characters. By default GCC ignores trigraphs, 323*e4b17023SJohn Marinobut if you request a strictly conforming mode with the @option{-std} 324*e4b17023SJohn Marinooption, or you specify the @option{-trigraphs} option, then it 325*e4b17023SJohn Marinoconverts them. 326*e4b17023SJohn Marino 327*e4b17023SJohn MarinoThese are nine three-character sequences, all starting with @samp{??}, 328*e4b17023SJohn Marinothat are defined by ISO C to stand for single characters. They permit 329*e4b17023SJohn Marinoobsolete systems that lack some of C's punctuation to use C@. For 330*e4b17023SJohn Marinoexample, @samp{??/} stands for @samp{\}, so @t{'??/n'} is a character 331*e4b17023SJohn Marinoconstant for a newline. 332*e4b17023SJohn Marino 333*e4b17023SJohn MarinoTrigraphs are not popular and many compilers implement them 334*e4b17023SJohn Marinoincorrectly. Portable code should not rely on trigraphs being either 335*e4b17023SJohn Marinoconverted or ignored. With @option{-Wtrigraphs} GCC will warn you 336*e4b17023SJohn Marinowhen a trigraph may change the meaning of your program if it were 337*e4b17023SJohn Marinoconverted. @xref{Wtrigraphs}. 338*e4b17023SJohn Marino 339*e4b17023SJohn MarinoIn a string constant, you can prevent a sequence of question marks 340*e4b17023SJohn Marinofrom being confused with a trigraph by inserting a backslash between 341*e4b17023SJohn Marinothe question marks, or by separating the string literal at the 342*e4b17023SJohn Marinotrigraph and making use of string literal concatenation. @t{"(??\?)"} 343*e4b17023SJohn Marinois the string @samp{(???)}, not @samp{(?]}. Traditional C compilers 344*e4b17023SJohn Marinodo not recognize these idioms. 345*e4b17023SJohn Marino 346*e4b17023SJohn MarinoThe nine trigraphs and their replacements are 347*e4b17023SJohn Marino 348*e4b17023SJohn Marino@smallexample 349*e4b17023SJohn MarinoTrigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??- 350*e4b17023SJohn MarinoReplacement: [ ] @{ @} # \ ^ | ~ 351*e4b17023SJohn Marino@end smallexample 352*e4b17023SJohn Marino 353*e4b17023SJohn Marino@item 354*e4b17023SJohn Marino@cindex continued lines 355*e4b17023SJohn Marino@cindex backslash-newline 356*e4b17023SJohn MarinoContinued lines are merged into one long line. 357*e4b17023SJohn Marino 358*e4b17023SJohn MarinoA continued line is a line which ends with a backslash, @samp{\}. The 359*e4b17023SJohn Marinobackslash is removed and the following line is joined with the current 360*e4b17023SJohn Marinoone. No space is inserted, so you may split a line anywhere, even in 361*e4b17023SJohn Marinothe middle of a word. (It is generally more readable to split lines 362*e4b17023SJohn Marinoonly at white space.) 363*e4b17023SJohn Marino 364*e4b17023SJohn MarinoThe trailing backslash on a continued line is commonly referred to as a 365*e4b17023SJohn Marino@dfn{backslash-newline}. 366*e4b17023SJohn Marino 367*e4b17023SJohn MarinoIf there is white space between a backslash and the end of a line, that 368*e4b17023SJohn Marinois still a continued line. However, as this is usually the result of an 369*e4b17023SJohn Marinoediting mistake, and many compilers will not accept it as a continued 370*e4b17023SJohn Marinoline, GCC will warn you about it. 371*e4b17023SJohn Marino 372*e4b17023SJohn Marino@item 373*e4b17023SJohn Marino@cindex comments 374*e4b17023SJohn Marino@cindex line comments 375*e4b17023SJohn Marino@cindex block comments 376*e4b17023SJohn MarinoAll comments are replaced with single spaces. 377*e4b17023SJohn Marino 378*e4b17023SJohn MarinoThere are two kinds of comments. @dfn{Block comments} begin with 379*e4b17023SJohn Marino@samp{/*} and continue until the next @samp{*/}. Block comments do not 380*e4b17023SJohn Marinonest: 381*e4b17023SJohn Marino 382*e4b17023SJohn Marino@smallexample 383*e4b17023SJohn Marino/* @r{this is} /* @r{one comment} */ @r{text outside comment} 384*e4b17023SJohn Marino@end smallexample 385*e4b17023SJohn Marino 386*e4b17023SJohn Marino@dfn{Line comments} begin with @samp{//} and continue to the end of the 387*e4b17023SJohn Marinocurrent line. Line comments do not nest either, but it does not matter, 388*e4b17023SJohn Marinobecause they would end in the same place anyway. 389*e4b17023SJohn Marino 390*e4b17023SJohn Marino@smallexample 391*e4b17023SJohn Marino// @r{this is} // @r{one comment} 392*e4b17023SJohn Marino@r{text outside comment} 393*e4b17023SJohn Marino@end smallexample 394*e4b17023SJohn Marino@end enumerate 395*e4b17023SJohn Marino 396*e4b17023SJohn MarinoIt is safe to put line comments inside block comments, or vice versa. 397*e4b17023SJohn Marino 398*e4b17023SJohn Marino@smallexample 399*e4b17023SJohn Marino@group 400*e4b17023SJohn Marino/* @r{block comment} 401*e4b17023SJohn Marino // @r{contains line comment} 402*e4b17023SJohn Marino @r{yet more comment} 403*e4b17023SJohn Marino */ @r{outside comment} 404*e4b17023SJohn Marino 405*e4b17023SJohn Marino// @r{line comment} /* @r{contains block comment} */ 406*e4b17023SJohn Marino@end group 407*e4b17023SJohn Marino@end smallexample 408*e4b17023SJohn Marino 409*e4b17023SJohn MarinoBut beware of commenting out one end of a block comment with a line 410*e4b17023SJohn Marinocomment. 411*e4b17023SJohn Marino 412*e4b17023SJohn Marino@smallexample 413*e4b17023SJohn Marino@group 414*e4b17023SJohn Marino // @r{l.c.} /* @r{block comment begins} 415*e4b17023SJohn Marino @r{oops! this isn't a comment anymore} */ 416*e4b17023SJohn Marino@end group 417*e4b17023SJohn Marino@end smallexample 418*e4b17023SJohn Marino 419*e4b17023SJohn MarinoComments are not recognized within string literals. 420*e4b17023SJohn Marino@t{@w{"/* blah */"}} is the string constant @samp{@w{/* blah */}}, not 421*e4b17023SJohn Marinoan empty string. 422*e4b17023SJohn Marino 423*e4b17023SJohn MarinoLine comments are not in the 1989 edition of the C standard, but they 424*e4b17023SJohn Marinoare recognized by GCC as an extension. In C++ and in the 1999 edition 425*e4b17023SJohn Marinoof the C standard, they are an official part of the language. 426*e4b17023SJohn Marino 427*e4b17023SJohn MarinoSince these transformations happen before all other processing, you can 428*e4b17023SJohn Marinosplit a line mechanically with backslash-newline anywhere. You can 429*e4b17023SJohn Marinocomment out the end of a line. You can continue a line comment onto the 430*e4b17023SJohn Marinonext line with backslash-newline. You can even split @samp{/*}, 431*e4b17023SJohn Marino@samp{*/}, and @samp{//} onto multiple lines with backslash-newline. 432*e4b17023SJohn MarinoFor example: 433*e4b17023SJohn Marino 434*e4b17023SJohn Marino@smallexample 435*e4b17023SJohn Marino@group 436*e4b17023SJohn Marino/\ 437*e4b17023SJohn Marino* 438*e4b17023SJohn Marino*/ # /* 439*e4b17023SJohn Marino*/ defi\ 440*e4b17023SJohn Marinone FO\ 441*e4b17023SJohn MarinoO 10\ 442*e4b17023SJohn Marino20 443*e4b17023SJohn Marino@end group 444*e4b17023SJohn Marino@end smallexample 445*e4b17023SJohn Marino 446*e4b17023SJohn Marino@noindent 447*e4b17023SJohn Marinois equivalent to @code{@w{#define FOO 1020}}. All these tricks are 448*e4b17023SJohn Marinoextremely confusing and should not be used in code intended to be 449*e4b17023SJohn Marinoreadable. 450*e4b17023SJohn Marino 451*e4b17023SJohn MarinoThere is no way to prevent a backslash at the end of a line from being 452*e4b17023SJohn Marinointerpreted as a backslash-newline. This cannot affect any correct 453*e4b17023SJohn Marinoprogram, however. 454*e4b17023SJohn Marino 455*e4b17023SJohn Marino@node Tokenization 456*e4b17023SJohn Marino@section Tokenization 457*e4b17023SJohn Marino 458*e4b17023SJohn Marino@cindex tokens 459*e4b17023SJohn Marino@cindex preprocessing tokens 460*e4b17023SJohn MarinoAfter the textual transformations are finished, the input file is 461*e4b17023SJohn Marinoconverted into a sequence of @dfn{preprocessing tokens}. These mostly 462*e4b17023SJohn Marinocorrespond to the syntactic tokens used by the C compiler, but there are 463*e4b17023SJohn Marinoa few differences. White space separates tokens; it is not itself a 464*e4b17023SJohn Marinotoken of any kind. Tokens do not have to be separated by white space, 465*e4b17023SJohn Marinobut it is often necessary to avoid ambiguities. 466*e4b17023SJohn Marino 467*e4b17023SJohn MarinoWhen faced with a sequence of characters that has more than one possible 468*e4b17023SJohn Marinotokenization, the preprocessor is greedy. It always makes each token, 469*e4b17023SJohn Marinostarting from the left, as big as possible before moving on to the next 470*e4b17023SJohn Marinotoken. For instance, @code{a+++++b} is interpreted as 471*e4b17023SJohn Marino@code{@w{a ++ ++ + b}}, not as @code{@w{a ++ + ++ b}}, even though the 472*e4b17023SJohn Marinolatter tokenization could be part of a valid C program and the former 473*e4b17023SJohn Marinocould not. 474*e4b17023SJohn Marino 475*e4b17023SJohn MarinoOnce the input file is broken into tokens, the token boundaries never 476*e4b17023SJohn Marinochange, except when the @samp{##} preprocessing operator is used to paste 477*e4b17023SJohn Marinotokens together. @xref{Concatenation}. For example, 478*e4b17023SJohn Marino 479*e4b17023SJohn Marino@smallexample 480*e4b17023SJohn Marino@group 481*e4b17023SJohn Marino#define foo() bar 482*e4b17023SJohn Marinofoo()baz 483*e4b17023SJohn Marino @expansion{} bar baz 484*e4b17023SJohn Marino@emph{not} 485*e4b17023SJohn Marino @expansion{} barbaz 486*e4b17023SJohn Marino@end group 487*e4b17023SJohn Marino@end smallexample 488*e4b17023SJohn Marino 489*e4b17023SJohn MarinoThe compiler does not re-tokenize the preprocessor's output. Each 490*e4b17023SJohn Marinopreprocessing token becomes one compiler token. 491*e4b17023SJohn Marino 492*e4b17023SJohn Marino@cindex identifiers 493*e4b17023SJohn MarinoPreprocessing tokens fall into five broad classes: identifiers, 494*e4b17023SJohn Marinopreprocessing numbers, string literals, punctuators, and other. An 495*e4b17023SJohn Marino@dfn{identifier} is the same as an identifier in C: any sequence of 496*e4b17023SJohn Marinoletters, digits, or underscores, which begins with a letter or 497*e4b17023SJohn Marinounderscore. Keywords of C have no significance to the preprocessor; 498*e4b17023SJohn Marinothey are ordinary identifiers. You can define a macro whose name is a 499*e4b17023SJohn Marinokeyword, for instance. The only identifier which can be considered a 500*e4b17023SJohn Marinopreprocessing keyword is @code{defined}. @xref{Defined}. 501*e4b17023SJohn Marino 502*e4b17023SJohn MarinoThis is mostly true of other languages which use the C preprocessor. 503*e4b17023SJohn MarinoHowever, a few of the keywords of C++ are significant even in the 504*e4b17023SJohn Marinopreprocessor. @xref{C++ Named Operators}. 505*e4b17023SJohn Marino 506*e4b17023SJohn MarinoIn the 1999 C standard, identifiers may contain letters which are not 507*e4b17023SJohn Marinopart of the ``basic source character set'', at the implementation's 508*e4b17023SJohn Marinodiscretion (such as accented Latin letters, Greek letters, or Chinese 509*e4b17023SJohn Marinoideograms). This may be done with an extended character set, or the 510*e4b17023SJohn Marino@samp{\u} and @samp{\U} escape sequences. The implementation of this 511*e4b17023SJohn Marinofeature in GCC is experimental; such characters are only accepted in 512*e4b17023SJohn Marinothe @samp{\u} and @samp{\U} forms and only if 513*e4b17023SJohn Marino@option{-fextended-identifiers} is used. 514*e4b17023SJohn Marino 515*e4b17023SJohn MarinoAs an extension, GCC treats @samp{$} as a letter. This is for 516*e4b17023SJohn Marinocompatibility with some systems, such as VMS, where @samp{$} is commonly 517*e4b17023SJohn Marinoused in system-defined function and object names. @samp{$} is not a 518*e4b17023SJohn Marinoletter in strictly conforming mode, or if you specify the @option{-$} 519*e4b17023SJohn Marinooption. @xref{Invocation}. 520*e4b17023SJohn Marino 521*e4b17023SJohn Marino@cindex numbers 522*e4b17023SJohn Marino@cindex preprocessing numbers 523*e4b17023SJohn MarinoA @dfn{preprocessing number} has a rather bizarre definition. The 524*e4b17023SJohn Marinocategory includes all the normal integer and floating point constants 525*e4b17023SJohn Marinoone expects of C, but also a number of other things one might not 526*e4b17023SJohn Marinoinitially recognize as a number. Formally, preprocessing numbers begin 527*e4b17023SJohn Marinowith an optional period, a required decimal digit, and then continue 528*e4b17023SJohn Marinowith any sequence of letters, digits, underscores, periods, and 529*e4b17023SJohn Marinoexponents. Exponents are the two-character sequences @samp{e+}, 530*e4b17023SJohn Marino@samp{e-}, @samp{E+}, @samp{E-}, @samp{p+}, @samp{p-}, @samp{P+}, and 531*e4b17023SJohn Marino@samp{P-}. (The exponents that begin with @samp{p} or @samp{P} are new 532*e4b17023SJohn Marinoto C99. They are used for hexadecimal floating-point constants.) 533*e4b17023SJohn Marino 534*e4b17023SJohn MarinoThe purpose of this unusual definition is to isolate the preprocessor 535*e4b17023SJohn Marinofrom the full complexity of numeric constants. It does not have to 536*e4b17023SJohn Marinodistinguish between lexically valid and invalid floating-point numbers, 537*e4b17023SJohn Marinowhich is complicated. The definition also permits you to split an 538*e4b17023SJohn Marinoidentifier at any position and get exactly two tokens, which can then be 539*e4b17023SJohn Marinopasted back together with the @samp{##} operator. 540*e4b17023SJohn Marino 541*e4b17023SJohn MarinoIt's possible for preprocessing numbers to cause programs to be 542*e4b17023SJohn Marinomisinterpreted. For example, @code{0xE+12} is a preprocessing number 543*e4b17023SJohn Marinowhich does not translate to any valid numeric constant, therefore a 544*e4b17023SJohn Marinosyntax error. It does not mean @code{@w{0xE + 12}}, which is what you 545*e4b17023SJohn Marinomight have intended. 546*e4b17023SJohn Marino 547*e4b17023SJohn Marino@cindex string literals 548*e4b17023SJohn Marino@cindex string constants 549*e4b17023SJohn Marino@cindex character constants 550*e4b17023SJohn Marino@cindex header file names 551*e4b17023SJohn Marino@c the @: prevents makeinfo from turning '' into ". 552*e4b17023SJohn Marino@dfn{String literals} are string constants, character constants, and 553*e4b17023SJohn Marinoheader file names (the argument of @samp{#include}).@footnote{The C 554*e4b17023SJohn Marinostandard uses the term @dfn{string literal} to refer only to what we are 555*e4b17023SJohn Marinocalling @dfn{string constants}.} String constants and character 556*e4b17023SJohn Marinoconstants are straightforward: @t{"@dots{}"} or @t{'@dots{}'}. In 557*e4b17023SJohn Marinoeither case embedded quotes should be escaped with a backslash: 558*e4b17023SJohn Marino@t{'\'@:'} is the character constant for @samp{'}. There is no limit on 559*e4b17023SJohn Marinothe length of a character constant, but the value of a character 560*e4b17023SJohn Marinoconstant that contains more than one character is 561*e4b17023SJohn Marinoimplementation-defined. @xref{Implementation Details}. 562*e4b17023SJohn Marino 563*e4b17023SJohn MarinoHeader file names either look like string constants, @t{"@dots{}"}, or are 564*e4b17023SJohn Marinowritten with angle brackets instead, @t{<@dots{}>}. In either case, 565*e4b17023SJohn Marinobackslash is an ordinary character. There is no way to escape the 566*e4b17023SJohn Marinoclosing quote or angle bracket. The preprocessor looks for the header 567*e4b17023SJohn Marinofile in different places depending on which form you use. @xref{Include 568*e4b17023SJohn MarinoOperation}. 569*e4b17023SJohn Marino 570*e4b17023SJohn MarinoNo string literal may extend past the end of a line. Older versions 571*e4b17023SJohn Marinoof GCC accepted multi-line string constants. You may use continued 572*e4b17023SJohn Marinolines instead, or string constant concatenation. @xref{Differences 573*e4b17023SJohn Marinofrom previous versions}. 574*e4b17023SJohn Marino 575*e4b17023SJohn Marino@cindex punctuators 576*e4b17023SJohn Marino@cindex digraphs 577*e4b17023SJohn Marino@cindex alternative tokens 578*e4b17023SJohn Marino@dfn{Punctuators} are all the usual bits of punctuation which are 579*e4b17023SJohn Marinomeaningful to C and C++. All but three of the punctuation characters in 580*e4b17023SJohn MarinoASCII are C punctuators. The exceptions are @samp{@@}, @samp{$}, and 581*e4b17023SJohn Marino@samp{`}. In addition, all the two- and three-character operators are 582*e4b17023SJohn Marinopunctuators. There are also six @dfn{digraphs}, which the C++ standard 583*e4b17023SJohn Marinocalls @dfn{alternative tokens}, which are merely alternate ways to spell 584*e4b17023SJohn Marinoother punctuators. This is a second attempt to work around missing 585*e4b17023SJohn Marinopunctuation in obsolete systems. It has no negative side effects, 586*e4b17023SJohn Marinounlike trigraphs, but does not cover as much ground. The digraphs and 587*e4b17023SJohn Marinotheir corresponding normal punctuators are: 588*e4b17023SJohn Marino 589*e4b17023SJohn Marino@smallexample 590*e4b17023SJohn MarinoDigraph: <% %> <: :> %: %:%: 591*e4b17023SJohn MarinoPunctuator: @{ @} [ ] # ## 592*e4b17023SJohn Marino@end smallexample 593*e4b17023SJohn Marino 594*e4b17023SJohn Marino@cindex other tokens 595*e4b17023SJohn MarinoAny other single character is considered ``other''. It is passed on to 596*e4b17023SJohn Marinothe preprocessor's output unmolested. The C compiler will almost 597*e4b17023SJohn Marinocertainly reject source code containing ``other'' tokens. In ASCII, the 598*e4b17023SJohn Marinoonly other characters are @samp{@@}, @samp{$}, @samp{`}, and control 599*e4b17023SJohn Marinocharacters other than NUL (all bits zero). (Note that @samp{$} is 600*e4b17023SJohn Marinonormally considered a letter.) All characters with the high bit set 601*e4b17023SJohn Marino(numeric range 0x7F--0xFF) are also ``other'' in the present 602*e4b17023SJohn Marinoimplementation. This will change when proper support for international 603*e4b17023SJohn Marinocharacter sets is added to GCC@. 604*e4b17023SJohn Marino 605*e4b17023SJohn MarinoNUL is a special case because of the high probability that its 606*e4b17023SJohn Marinoappearance is accidental, and because it may be invisible to the user 607*e4b17023SJohn Marino(many terminals do not display NUL at all). Within comments, NULs are 608*e4b17023SJohn Marinosilently ignored, just as any other character would be. In running 609*e4b17023SJohn Marinotext, NUL is considered white space. For example, these two directives 610*e4b17023SJohn Marinohave the same meaning. 611*e4b17023SJohn Marino 612*e4b17023SJohn Marino@smallexample 613*e4b17023SJohn Marino#define X^@@1 614*e4b17023SJohn Marino#define X 1 615*e4b17023SJohn Marino@end smallexample 616*e4b17023SJohn Marino 617*e4b17023SJohn Marino@noindent 618*e4b17023SJohn Marino(where @samp{^@@} is ASCII NUL)@. Within string or character constants, 619*e4b17023SJohn MarinoNULs are preserved. In the latter two cases the preprocessor emits a 620*e4b17023SJohn Marinowarning message. 621*e4b17023SJohn Marino 622*e4b17023SJohn Marino@node The preprocessing language 623*e4b17023SJohn Marino@section The preprocessing language 624*e4b17023SJohn Marino@cindex directives 625*e4b17023SJohn Marino@cindex preprocessing directives 626*e4b17023SJohn Marino@cindex directive line 627*e4b17023SJohn Marino@cindex directive name 628*e4b17023SJohn Marino 629*e4b17023SJohn MarinoAfter tokenization, the stream of tokens may simply be passed straight 630*e4b17023SJohn Marinoto the compiler's parser. However, if it contains any operations in the 631*e4b17023SJohn Marino@dfn{preprocessing language}, it will be transformed first. This stage 632*e4b17023SJohn Marinocorresponds roughly to the standard's ``translation phase 4'' and is 633*e4b17023SJohn Marinowhat most people think of as the preprocessor's job. 634*e4b17023SJohn Marino 635*e4b17023SJohn MarinoThe preprocessing language consists of @dfn{directives} to be executed 636*e4b17023SJohn Marinoand @dfn{macros} to be expanded. Its primary capabilities are: 637*e4b17023SJohn Marino 638*e4b17023SJohn Marino@itemize @bullet 639*e4b17023SJohn Marino@item 640*e4b17023SJohn MarinoInclusion of header files. These are files of declarations that can be 641*e4b17023SJohn Marinosubstituted into your program. 642*e4b17023SJohn Marino 643*e4b17023SJohn Marino@item 644*e4b17023SJohn MarinoMacro expansion. You can define @dfn{macros}, which are abbreviations 645*e4b17023SJohn Marinofor arbitrary fragments of C code. The preprocessor will replace the 646*e4b17023SJohn Marinomacros with their definitions throughout the program. Some macros are 647*e4b17023SJohn Marinoautomatically defined for you. 648*e4b17023SJohn Marino 649*e4b17023SJohn Marino@item 650*e4b17023SJohn MarinoConditional compilation. You can include or exclude parts of the 651*e4b17023SJohn Marinoprogram according to various conditions. 652*e4b17023SJohn Marino 653*e4b17023SJohn Marino@item 654*e4b17023SJohn MarinoLine control. If you use a program to combine or rearrange source files 655*e4b17023SJohn Marinointo an intermediate file which is then compiled, you can use line 656*e4b17023SJohn Marinocontrol to inform the compiler where each source line originally came 657*e4b17023SJohn Marinofrom. 658*e4b17023SJohn Marino 659*e4b17023SJohn Marino@item 660*e4b17023SJohn MarinoDiagnostics. You can detect problems at compile time and issue errors 661*e4b17023SJohn Marinoor warnings. 662*e4b17023SJohn Marino@end itemize 663*e4b17023SJohn Marino 664*e4b17023SJohn MarinoThere are a few more, less useful, features. 665*e4b17023SJohn Marino 666*e4b17023SJohn MarinoExcept for expansion of predefined macros, all these operations are 667*e4b17023SJohn Marinotriggered with @dfn{preprocessing directives}. Preprocessing directives 668*e4b17023SJohn Marinoare lines in your program that start with @samp{#}. Whitespace is 669*e4b17023SJohn Marinoallowed before and after the @samp{#}. The @samp{#} is followed by an 670*e4b17023SJohn Marinoidentifier, the @dfn{directive name}. It specifies the operation to 671*e4b17023SJohn Marinoperform. Directives are commonly referred to as @samp{#@var{name}} 672*e4b17023SJohn Marinowhere @var{name} is the directive name. For example, @samp{#define} is 673*e4b17023SJohn Marinothe directive that defines a macro. 674*e4b17023SJohn Marino 675*e4b17023SJohn MarinoThe @samp{#} which begins a directive cannot come from a macro 676*e4b17023SJohn Marinoexpansion. Also, the directive name is not macro expanded. Thus, if 677*e4b17023SJohn Marino@code{foo} is defined as a macro expanding to @code{define}, that does 678*e4b17023SJohn Marinonot make @samp{#foo} a valid preprocessing directive. 679*e4b17023SJohn Marino 680*e4b17023SJohn MarinoThe set of valid directive names is fixed. Programs cannot define new 681*e4b17023SJohn Marinopreprocessing directives. 682*e4b17023SJohn Marino 683*e4b17023SJohn MarinoSome directives require arguments; these make up the rest of the 684*e4b17023SJohn Marinodirective line and must be separated from the directive name by 685*e4b17023SJohn Marinowhitespace. For example, @samp{#define} must be followed by a macro 686*e4b17023SJohn Marinoname and the intended expansion of the macro. 687*e4b17023SJohn Marino 688*e4b17023SJohn MarinoA preprocessing directive cannot cover more than one line. The line 689*e4b17023SJohn Marinomay, however, be continued with backslash-newline, or by a block comment 690*e4b17023SJohn Marinowhich extends past the end of the line. In either case, when the 691*e4b17023SJohn Marinodirective is processed, the continuations have already been merged with 692*e4b17023SJohn Marinothe first line to make one long line. 693*e4b17023SJohn Marino 694*e4b17023SJohn Marino@node Header Files 695*e4b17023SJohn Marino@chapter Header Files 696*e4b17023SJohn Marino 697*e4b17023SJohn Marino@cindex header file 698*e4b17023SJohn MarinoA header file is a file containing C declarations and macro definitions 699*e4b17023SJohn Marino(@pxref{Macros}) to be shared between several source files. You request 700*e4b17023SJohn Marinothe use of a header file in your program by @dfn{including} it, with the 701*e4b17023SJohn MarinoC preprocessing directive @samp{#include}. 702*e4b17023SJohn Marino 703*e4b17023SJohn MarinoHeader files serve two purposes. 704*e4b17023SJohn Marino 705*e4b17023SJohn Marino@itemize @bullet 706*e4b17023SJohn Marino@item 707*e4b17023SJohn Marino@cindex system header files 708*e4b17023SJohn MarinoSystem header files declare the interfaces to parts of the operating 709*e4b17023SJohn Marinosystem. You include them in your program to supply the definitions and 710*e4b17023SJohn Marinodeclarations you need to invoke system calls and libraries. 711*e4b17023SJohn Marino 712*e4b17023SJohn Marino@item 713*e4b17023SJohn MarinoYour own header files contain declarations for interfaces between the 714*e4b17023SJohn Marinosource files of your program. Each time you have a group of related 715*e4b17023SJohn Marinodeclarations and macro definitions all or most of which are needed in 716*e4b17023SJohn Marinoseveral different source files, it is a good idea to create a header 717*e4b17023SJohn Marinofile for them. 718*e4b17023SJohn Marino@end itemize 719*e4b17023SJohn Marino 720*e4b17023SJohn MarinoIncluding a header file produces the same results as copying the header 721*e4b17023SJohn Marinofile into each source file that needs it. Such copying would be 722*e4b17023SJohn Marinotime-consuming and error-prone. With a header file, the related 723*e4b17023SJohn Marinodeclarations appear in only one place. If they need to be changed, they 724*e4b17023SJohn Marinocan be changed in one place, and programs that include the header file 725*e4b17023SJohn Marinowill automatically use the new version when next recompiled. The header 726*e4b17023SJohn Marinofile eliminates the labor of finding and changing all the copies as well 727*e4b17023SJohn Marinoas the risk that a failure to find one copy will result in 728*e4b17023SJohn Marinoinconsistencies within a program. 729*e4b17023SJohn Marino 730*e4b17023SJohn MarinoIn C, the usual convention is to give header files names that end with 731*e4b17023SJohn Marino@file{.h}. It is most portable to use only letters, digits, dashes, and 732*e4b17023SJohn Marinounderscores in header file names, and at most one dot. 733*e4b17023SJohn Marino 734*e4b17023SJohn Marino@menu 735*e4b17023SJohn Marino* Include Syntax:: 736*e4b17023SJohn Marino* Include Operation:: 737*e4b17023SJohn Marino* Search Path:: 738*e4b17023SJohn Marino* Once-Only Headers:: 739*e4b17023SJohn Marino* Alternatives to Wrapper #ifndef:: 740*e4b17023SJohn Marino* Computed Includes:: 741*e4b17023SJohn Marino* Wrapper Headers:: 742*e4b17023SJohn Marino* System Headers:: 743*e4b17023SJohn Marino@end menu 744*e4b17023SJohn Marino 745*e4b17023SJohn Marino@node Include Syntax 746*e4b17023SJohn Marino@section Include Syntax 747*e4b17023SJohn Marino 748*e4b17023SJohn Marino@findex #include 749*e4b17023SJohn MarinoBoth user and system header files are included using the preprocessing 750*e4b17023SJohn Marinodirective @samp{#include}. It has two variants: 751*e4b17023SJohn Marino 752*e4b17023SJohn Marino@table @code 753*e4b17023SJohn Marino@item #include <@var{file}> 754*e4b17023SJohn MarinoThis variant is used for system header files. It searches for a file 755*e4b17023SJohn Marinonamed @var{file} in a standard list of system directories. You can prepend 756*e4b17023SJohn Marinodirectories to this list with the @option{-I} option (@pxref{Invocation}). 757*e4b17023SJohn Marino 758*e4b17023SJohn Marino@item #include "@var{file}" 759*e4b17023SJohn MarinoThis variant is used for header files of your own program. It 760*e4b17023SJohn Marinosearches for a file named @var{file} first in the directory containing 761*e4b17023SJohn Marinothe current file, then in the quote directories and then the same 762*e4b17023SJohn Marinodirectories used for @code{<@var{file}>}. You can prepend directories 763*e4b17023SJohn Marinoto the list of quote directories with the @option{-iquote} option. 764*e4b17023SJohn Marino@end table 765*e4b17023SJohn Marino 766*e4b17023SJohn MarinoThe argument of @samp{#include}, whether delimited with quote marks or 767*e4b17023SJohn Marinoangle brackets, behaves like a string constant in that comments are not 768*e4b17023SJohn Marinorecognized, and macro names are not expanded. Thus, @code{@w{#include 769*e4b17023SJohn Marino<x/*y>}} specifies inclusion of a system header file named @file{x/*y}. 770*e4b17023SJohn Marino 771*e4b17023SJohn MarinoHowever, if backslashes occur within @var{file}, they are considered 772*e4b17023SJohn Marinoordinary text characters, not escape characters. None of the character 773*e4b17023SJohn Marinoescape sequences appropriate to string constants in C are processed. 774*e4b17023SJohn MarinoThus, @code{@w{#include "x\n\\y"}} specifies a filename containing three 775*e4b17023SJohn Marinobackslashes. (Some systems interpret @samp{\} as a pathname separator. 776*e4b17023SJohn MarinoAll of these also interpret @samp{/} the same way. It is most portable 777*e4b17023SJohn Marinoto use only @samp{/}.) 778*e4b17023SJohn Marino 779*e4b17023SJohn MarinoIt is an error if there is anything (other than comments) on the line 780*e4b17023SJohn Marinoafter the file name. 781*e4b17023SJohn Marino 782*e4b17023SJohn Marino@node Include Operation 783*e4b17023SJohn Marino@section Include Operation 784*e4b17023SJohn Marino 785*e4b17023SJohn MarinoThe @samp{#include} directive works by directing the C preprocessor to 786*e4b17023SJohn Marinoscan the specified file as input before continuing with the rest of the 787*e4b17023SJohn Marinocurrent file. The output from the preprocessor contains the output 788*e4b17023SJohn Marinoalready generated, followed by the output resulting from the included 789*e4b17023SJohn Marinofile, followed by the output that comes from the text after the 790*e4b17023SJohn Marino@samp{#include} directive. For example, if you have a header file 791*e4b17023SJohn Marino@file{header.h} as follows, 792*e4b17023SJohn Marino 793*e4b17023SJohn Marino@smallexample 794*e4b17023SJohn Marinochar *test (void); 795*e4b17023SJohn Marino@end smallexample 796*e4b17023SJohn Marino 797*e4b17023SJohn Marino@noindent 798*e4b17023SJohn Marinoand a main program called @file{program.c} that uses the header file, 799*e4b17023SJohn Marinolike this, 800*e4b17023SJohn Marino 801*e4b17023SJohn Marino@smallexample 802*e4b17023SJohn Marinoint x; 803*e4b17023SJohn Marino#include "header.h" 804*e4b17023SJohn Marino 805*e4b17023SJohn Marinoint 806*e4b17023SJohn Marinomain (void) 807*e4b17023SJohn Marino@{ 808*e4b17023SJohn Marino puts (test ()); 809*e4b17023SJohn Marino@} 810*e4b17023SJohn Marino@end smallexample 811*e4b17023SJohn Marino 812*e4b17023SJohn Marino@noindent 813*e4b17023SJohn Marinothe compiler will see the same token stream as it would if 814*e4b17023SJohn Marino@file{program.c} read 815*e4b17023SJohn Marino 816*e4b17023SJohn Marino@smallexample 817*e4b17023SJohn Marinoint x; 818*e4b17023SJohn Marinochar *test (void); 819*e4b17023SJohn Marino 820*e4b17023SJohn Marinoint 821*e4b17023SJohn Marinomain (void) 822*e4b17023SJohn Marino@{ 823*e4b17023SJohn Marino puts (test ()); 824*e4b17023SJohn Marino@} 825*e4b17023SJohn Marino@end smallexample 826*e4b17023SJohn Marino 827*e4b17023SJohn MarinoIncluded files are not limited to declarations and macro definitions; 828*e4b17023SJohn Marinothose are merely the typical uses. Any fragment of a C program can be 829*e4b17023SJohn Marinoincluded from another file. The include file could even contain the 830*e4b17023SJohn Marinobeginning of a statement that is concluded in the containing file, or 831*e4b17023SJohn Marinothe end of a statement that was started in the including file. However, 832*e4b17023SJohn Marinoan included file must consist of complete tokens. Comments and string 833*e4b17023SJohn Marinoliterals which have not been closed by the end of an included file are 834*e4b17023SJohn Marinoinvalid. For error recovery, they are considered to end at the end of 835*e4b17023SJohn Marinothe file. 836*e4b17023SJohn Marino 837*e4b17023SJohn MarinoTo avoid confusion, it is best if header files contain only complete 838*e4b17023SJohn Marinosyntactic units---function declarations or definitions, type 839*e4b17023SJohn Marinodeclarations, etc. 840*e4b17023SJohn Marino 841*e4b17023SJohn MarinoThe line following the @samp{#include} directive is always treated as a 842*e4b17023SJohn Marinoseparate line by the C preprocessor, even if the included file lacks a 843*e4b17023SJohn Marinofinal newline. 844*e4b17023SJohn Marino 845*e4b17023SJohn Marino@node Search Path 846*e4b17023SJohn Marino@section Search Path 847*e4b17023SJohn Marino 848*e4b17023SJohn MarinoGCC looks in several different places for headers. On a normal Unix 849*e4b17023SJohn Marinosystem, if you do not instruct it otherwise, it will look for headers 850*e4b17023SJohn Marinorequested with @code{@w{#include <@var{file}>}} in: 851*e4b17023SJohn Marino 852*e4b17023SJohn Marino@smallexample 853*e4b17023SJohn Marino/usr/local/include 854*e4b17023SJohn Marino@var{libdir}/gcc/@var{target}/@var{version}/include 855*e4b17023SJohn Marino/usr/@var{target}/include 856*e4b17023SJohn Marino/usr/include 857*e4b17023SJohn Marino@end smallexample 858*e4b17023SJohn Marino 859*e4b17023SJohn MarinoFor C++ programs, it will also look in @file{/usr/include/g++-v3}, 860*e4b17023SJohn Marinofirst. In the above, @var{target} is the canonical name of the system 861*e4b17023SJohn MarinoGCC was configured to compile code for; often but not always the same as 862*e4b17023SJohn Marinothe canonical name of the system it runs on. @var{version} is the 863*e4b17023SJohn Marinoversion of GCC in use. 864*e4b17023SJohn Marino 865*e4b17023SJohn MarinoYou can add to this list with the @option{-I@var{dir}} command line 866*e4b17023SJohn Marinooption. All the directories named by @option{-I} are searched, in 867*e4b17023SJohn Marinoleft-to-right order, @emph{before} the default directories. The only 868*e4b17023SJohn Marinoexception is when @file{dir} is already searched by default. In 869*e4b17023SJohn Marinothis case, the option is ignored and the search order for system 870*e4b17023SJohn Marinodirectories remains unchanged. 871*e4b17023SJohn Marino 872*e4b17023SJohn MarinoDuplicate directories are removed from the quote and bracket search 873*e4b17023SJohn Marinochains before the two chains are merged to make the final search chain. 874*e4b17023SJohn MarinoThus, it is possible for a directory to occur twice in the final search 875*e4b17023SJohn Marinochain if it was specified in both the quote and bracket chains. 876*e4b17023SJohn Marino 877*e4b17023SJohn MarinoYou can prevent GCC from searching any of the default directories with 878*e4b17023SJohn Marinothe @option{-nostdinc} option. This is useful when you are compiling an 879*e4b17023SJohn Marinooperating system kernel or some other program that does not use the 880*e4b17023SJohn Marinostandard C library facilities, or the standard C library itself. 881*e4b17023SJohn Marino@option{-I} options are not ignored as described above when 882*e4b17023SJohn Marino@option{-nostdinc} is in effect. 883*e4b17023SJohn Marino 884*e4b17023SJohn MarinoGCC looks for headers requested with @code{@w{#include "@var{file}"}} 885*e4b17023SJohn Marinofirst in the directory containing the current file, then in the 886*e4b17023SJohn Marinodirectories as specified by @option{-iquote} options, then in the same 887*e4b17023SJohn Marinoplaces it would have looked for a header requested with angle 888*e4b17023SJohn Marinobrackets. For example, if @file{/usr/include/sys/stat.h} contains 889*e4b17023SJohn Marino@code{@w{#include "types.h"}}, GCC looks for @file{types.h} first in 890*e4b17023SJohn Marino@file{/usr/include/sys}, then in its usual search path. 891*e4b17023SJohn Marino 892*e4b17023SJohn Marino@samp{#line} (@pxref{Line Control}) does not change GCC's idea of the 893*e4b17023SJohn Marinodirectory containing the current file. 894*e4b17023SJohn Marino 895*e4b17023SJohn MarinoYou may put @option{-I-} at any point in your list of @option{-I} options. 896*e4b17023SJohn MarinoThis has two effects. First, directories appearing before the 897*e4b17023SJohn Marino@option{-I-} in the list are searched only for headers requested with 898*e4b17023SJohn Marinoquote marks. Directories after @option{-I-} are searched for all 899*e4b17023SJohn Marinoheaders. Second, the directory containing the current file is not 900*e4b17023SJohn Marinosearched for anything, unless it happens to be one of the directories 901*e4b17023SJohn Marinonamed by an @option{-I} switch. @option{-I-} is deprecated, @option{-iquote} 902*e4b17023SJohn Marinoshould be used instead. 903*e4b17023SJohn Marino 904*e4b17023SJohn Marino@option{-I. -I-} is not the same as no @option{-I} options at all, and does 905*e4b17023SJohn Marinonot cause the same behavior for @samp{<>} includes that @samp{""} 906*e4b17023SJohn Marinoincludes get with no special options. @option{-I.} searches the 907*e4b17023SJohn Marinocompiler's current working directory for header files. That may or may 908*e4b17023SJohn Marinonot be the same as the directory containing the current file. 909*e4b17023SJohn Marino 910*e4b17023SJohn MarinoIf you need to look for headers in a directory named @file{-}, write 911*e4b17023SJohn Marino@option{-I./-}. 912*e4b17023SJohn Marino 913*e4b17023SJohn MarinoThere are several more ways to adjust the header search path. They are 914*e4b17023SJohn Marinogenerally less useful. @xref{Invocation}. 915*e4b17023SJohn Marino 916*e4b17023SJohn Marino@node Once-Only Headers 917*e4b17023SJohn Marino@section Once-Only Headers 918*e4b17023SJohn Marino@cindex repeated inclusion 919*e4b17023SJohn Marino@cindex including just once 920*e4b17023SJohn Marino@cindex wrapper @code{#ifndef} 921*e4b17023SJohn Marino 922*e4b17023SJohn MarinoIf a header file happens to be included twice, the compiler will process 923*e4b17023SJohn Marinoits contents twice. This is very likely to cause an error, e.g.@: when the 924*e4b17023SJohn Marinocompiler sees the same structure definition twice. Even if it does not, 925*e4b17023SJohn Marinoit will certainly waste time. 926*e4b17023SJohn Marino 927*e4b17023SJohn MarinoThe standard way to prevent this is to enclose the entire real contents 928*e4b17023SJohn Marinoof the file in a conditional, like this: 929*e4b17023SJohn Marino 930*e4b17023SJohn Marino@smallexample 931*e4b17023SJohn Marino@group 932*e4b17023SJohn Marino/* File foo. */ 933*e4b17023SJohn Marino#ifndef FILE_FOO_SEEN 934*e4b17023SJohn Marino#define FILE_FOO_SEEN 935*e4b17023SJohn Marino 936*e4b17023SJohn Marino@var{the entire file} 937*e4b17023SJohn Marino 938*e4b17023SJohn Marino#endif /* !FILE_FOO_SEEN */ 939*e4b17023SJohn Marino@end group 940*e4b17023SJohn Marino@end smallexample 941*e4b17023SJohn Marino 942*e4b17023SJohn MarinoThis construct is commonly known as a @dfn{wrapper #ifndef}. 943*e4b17023SJohn MarinoWhen the header is included again, the conditional will be false, 944*e4b17023SJohn Marinobecause @code{FILE_FOO_SEEN} is defined. The preprocessor will skip 945*e4b17023SJohn Marinoover the entire contents of the file, and the compiler will not see it 946*e4b17023SJohn Marinotwice. 947*e4b17023SJohn Marino 948*e4b17023SJohn MarinoCPP optimizes even further. It remembers when a header file has a 949*e4b17023SJohn Marinowrapper @samp{#ifndef}. If a subsequent @samp{#include} specifies that 950*e4b17023SJohn Marinoheader, and the macro in the @samp{#ifndef} is still defined, it does 951*e4b17023SJohn Marinonot bother to rescan the file at all. 952*e4b17023SJohn Marino 953*e4b17023SJohn MarinoYou can put comments outside the wrapper. They will not interfere with 954*e4b17023SJohn Marinothis optimization. 955*e4b17023SJohn Marino 956*e4b17023SJohn Marino@cindex controlling macro 957*e4b17023SJohn Marino@cindex guard macro 958*e4b17023SJohn MarinoThe macro @code{FILE_FOO_SEEN} is called the @dfn{controlling macro} or 959*e4b17023SJohn Marino@dfn{guard macro}. In a user header file, the macro name should not 960*e4b17023SJohn Marinobegin with @samp{_}. In a system header file, it should begin with 961*e4b17023SJohn Marino@samp{__} to avoid conflicts with user programs. In any kind of header 962*e4b17023SJohn Marinofile, the macro name should contain the name of the file and some 963*e4b17023SJohn Marinoadditional text, to avoid conflicts with other header files. 964*e4b17023SJohn Marino 965*e4b17023SJohn Marino@node Alternatives to Wrapper #ifndef 966*e4b17023SJohn Marino@section Alternatives to Wrapper #ifndef 967*e4b17023SJohn Marino 968*e4b17023SJohn MarinoCPP supports two more ways of indicating that a header file should be 969*e4b17023SJohn Marinoread only once. Neither one is as portable as a wrapper @samp{#ifndef} 970*e4b17023SJohn Marinoand we recommend you do not use them in new programs, with the caveat 971*e4b17023SJohn Marinothat @samp{#import} is standard practice in Objective-C. 972*e4b17023SJohn Marino 973*e4b17023SJohn Marino@findex #import 974*e4b17023SJohn MarinoCPP supports a variant of @samp{#include} called @samp{#import} which 975*e4b17023SJohn Marinoincludes a file, but does so at most once. If you use @samp{#import} 976*e4b17023SJohn Marinoinstead of @samp{#include}, then you don't need the conditionals 977*e4b17023SJohn Marinoinside the header file to prevent multiple inclusion of the contents. 978*e4b17023SJohn Marino@samp{#import} is standard in Objective-C, but is considered a 979*e4b17023SJohn Marinodeprecated extension in C and C++. 980*e4b17023SJohn Marino 981*e4b17023SJohn Marino@samp{#import} is not a well designed feature. It requires the users of 982*e4b17023SJohn Marinoa header file to know that it should only be included once. It is much 983*e4b17023SJohn Marinobetter for the header file's implementor to write the file so that users 984*e4b17023SJohn Marinodon't need to know this. Using a wrapper @samp{#ifndef} accomplishes 985*e4b17023SJohn Marinothis goal. 986*e4b17023SJohn Marino 987*e4b17023SJohn MarinoIn the present implementation, a single use of @samp{#import} will 988*e4b17023SJohn Marinoprevent the file from ever being read again, by either @samp{#import} or 989*e4b17023SJohn Marino@samp{#include}. You should not rely on this; do not use both 990*e4b17023SJohn Marino@samp{#import} and @samp{#include} to refer to the same header file. 991*e4b17023SJohn Marino 992*e4b17023SJohn MarinoAnother way to prevent a header file from being included more than once 993*e4b17023SJohn Marinois with the @samp{#pragma once} directive. If @samp{#pragma once} is 994*e4b17023SJohn Marinoseen when scanning a header file, that file will never be read again, no 995*e4b17023SJohn Marinomatter what. 996*e4b17023SJohn Marino 997*e4b17023SJohn Marino@samp{#pragma once} does not have the problems that @samp{#import} does, 998*e4b17023SJohn Marinobut it is not recognized by all preprocessors, so you cannot rely on it 999*e4b17023SJohn Marinoin a portable program. 1000*e4b17023SJohn Marino 1001*e4b17023SJohn Marino@node Computed Includes 1002*e4b17023SJohn Marino@section Computed Includes 1003*e4b17023SJohn Marino@cindex computed includes 1004*e4b17023SJohn Marino@cindex macros in include 1005*e4b17023SJohn Marino 1006*e4b17023SJohn MarinoSometimes it is necessary to select one of several different header 1007*e4b17023SJohn Marinofiles to be included into your program. They might specify 1008*e4b17023SJohn Marinoconfiguration parameters to be used on different sorts of operating 1009*e4b17023SJohn Marinosystems, for instance. You could do this with a series of conditionals, 1010*e4b17023SJohn Marino 1011*e4b17023SJohn Marino@smallexample 1012*e4b17023SJohn Marino#if SYSTEM_1 1013*e4b17023SJohn Marino# include "system_1.h" 1014*e4b17023SJohn Marino#elif SYSTEM_2 1015*e4b17023SJohn Marino# include "system_2.h" 1016*e4b17023SJohn Marino#elif SYSTEM_3 1017*e4b17023SJohn Marino@dots{} 1018*e4b17023SJohn Marino#endif 1019*e4b17023SJohn Marino@end smallexample 1020*e4b17023SJohn Marino 1021*e4b17023SJohn MarinoThat rapidly becomes tedious. Instead, the preprocessor offers the 1022*e4b17023SJohn Marinoability to use a macro for the header name. This is called a 1023*e4b17023SJohn Marino@dfn{computed include}. Instead of writing a header name as the direct 1024*e4b17023SJohn Marinoargument of @samp{#include}, you simply put a macro name there instead: 1025*e4b17023SJohn Marino 1026*e4b17023SJohn Marino@smallexample 1027*e4b17023SJohn Marino#define SYSTEM_H "system_1.h" 1028*e4b17023SJohn Marino@dots{} 1029*e4b17023SJohn Marino#include SYSTEM_H 1030*e4b17023SJohn Marino@end smallexample 1031*e4b17023SJohn Marino 1032*e4b17023SJohn Marino@noindent 1033*e4b17023SJohn Marino@code{SYSTEM_H} will be expanded, and the preprocessor will look for 1034*e4b17023SJohn Marino@file{system_1.h} as if the @samp{#include} had been written that way 1035*e4b17023SJohn Marinooriginally. @code{SYSTEM_H} could be defined by your Makefile with a 1036*e4b17023SJohn Marino@option{-D} option. 1037*e4b17023SJohn Marino 1038*e4b17023SJohn MarinoYou must be careful when you define the macro. @samp{#define} saves 1039*e4b17023SJohn Marinotokens, not text. The preprocessor has no way of knowing that the macro 1040*e4b17023SJohn Marinowill be used as the argument of @samp{#include}, so it generates 1041*e4b17023SJohn Marinoordinary tokens, not a header name. This is unlikely to cause problems 1042*e4b17023SJohn Marinoif you use double-quote includes, which are close enough to string 1043*e4b17023SJohn Marinoconstants. If you use angle brackets, however, you may have trouble. 1044*e4b17023SJohn Marino 1045*e4b17023SJohn MarinoThe syntax of a computed include is actually a bit more general than the 1046*e4b17023SJohn Marinoabove. If the first non-whitespace character after @samp{#include} is 1047*e4b17023SJohn Marinonot @samp{"} or @samp{<}, then the entire line is macro-expanded 1048*e4b17023SJohn Marinolike running text would be. 1049*e4b17023SJohn Marino 1050*e4b17023SJohn MarinoIf the line expands to a single string constant, the contents of that 1051*e4b17023SJohn Marinostring constant are the file to be included. CPP does not re-examine the 1052*e4b17023SJohn Marinostring for embedded quotes, but neither does it process backslash 1053*e4b17023SJohn Marinoescapes in the string. Therefore 1054*e4b17023SJohn Marino 1055*e4b17023SJohn Marino@smallexample 1056*e4b17023SJohn Marino#define HEADER "a\"b" 1057*e4b17023SJohn Marino#include HEADER 1058*e4b17023SJohn Marino@end smallexample 1059*e4b17023SJohn Marino 1060*e4b17023SJohn Marino@noindent 1061*e4b17023SJohn Marinolooks for a file named @file{a\"b}. CPP searches for the file according 1062*e4b17023SJohn Marinoto the rules for double-quoted includes. 1063*e4b17023SJohn Marino 1064*e4b17023SJohn MarinoIf the line expands to a token stream beginning with a @samp{<} token 1065*e4b17023SJohn Marinoand including a @samp{>} token, then the tokens between the @samp{<} and 1066*e4b17023SJohn Marinothe first @samp{>} are combined to form the filename to be included. 1067*e4b17023SJohn MarinoAny whitespace between tokens is reduced to a single space; then any 1068*e4b17023SJohn Marinospace after the initial @samp{<} is retained, but a trailing space 1069*e4b17023SJohn Marinobefore the closing @samp{>} is ignored. CPP searches for the file 1070*e4b17023SJohn Marinoaccording to the rules for angle-bracket includes. 1071*e4b17023SJohn Marino 1072*e4b17023SJohn MarinoIn either case, if there are any tokens on the line after the file name, 1073*e4b17023SJohn Marinoan error occurs and the directive is not processed. It is also an error 1074*e4b17023SJohn Marinoif the result of expansion does not match either of the two expected 1075*e4b17023SJohn Marinoforms. 1076*e4b17023SJohn Marino 1077*e4b17023SJohn MarinoThese rules are implementation-defined behavior according to the C 1078*e4b17023SJohn Marinostandard. To minimize the risk of different compilers interpreting your 1079*e4b17023SJohn Marinocomputed includes differently, we recommend you use only a single 1080*e4b17023SJohn Marinoobject-like macro which expands to a string constant. This will also 1081*e4b17023SJohn Marinominimize confusion for people reading your program. 1082*e4b17023SJohn Marino 1083*e4b17023SJohn Marino@node Wrapper Headers 1084*e4b17023SJohn Marino@section Wrapper Headers 1085*e4b17023SJohn Marino@cindex wrapper headers 1086*e4b17023SJohn Marino@cindex overriding a header file 1087*e4b17023SJohn Marino@findex #include_next 1088*e4b17023SJohn Marino 1089*e4b17023SJohn MarinoSometimes it is necessary to adjust the contents of a system-provided 1090*e4b17023SJohn Marinoheader file without editing it directly. GCC's @command{fixincludes} 1091*e4b17023SJohn Marinooperation does this, for example. One way to do that would be to create 1092*e4b17023SJohn Marinoa new header file with the same name and insert it in the search path 1093*e4b17023SJohn Marinobefore the original header. That works fine as long as you're willing 1094*e4b17023SJohn Marinoto replace the old header entirely. But what if you want to refer to 1095*e4b17023SJohn Marinothe old header from the new one? 1096*e4b17023SJohn Marino 1097*e4b17023SJohn MarinoYou cannot simply include the old header with @samp{#include}. That 1098*e4b17023SJohn Marinowill start from the beginning, and find your new header again. If your 1099*e4b17023SJohn Marinoheader is not protected from multiple inclusion (@pxref{Once-Only 1100*e4b17023SJohn MarinoHeaders}), it will recurse infinitely and cause a fatal error. 1101*e4b17023SJohn Marino 1102*e4b17023SJohn MarinoYou could include the old header with an absolute pathname: 1103*e4b17023SJohn Marino@smallexample 1104*e4b17023SJohn Marino#include "/usr/include/old-header.h" 1105*e4b17023SJohn Marino@end smallexample 1106*e4b17023SJohn Marino@noindent 1107*e4b17023SJohn MarinoThis works, but is not clean; should the system headers ever move, you 1108*e4b17023SJohn Marinowould have to edit the new headers to match. 1109*e4b17023SJohn Marino 1110*e4b17023SJohn MarinoThere is no way to solve this problem within the C standard, but you can 1111*e4b17023SJohn Marinouse the GNU extension @samp{#include_next}. It means, ``Include the 1112*e4b17023SJohn Marino@emph{next} file with this name''. This directive works like 1113*e4b17023SJohn Marino@samp{#include} except in searching for the specified file: it starts 1114*e4b17023SJohn Marinosearching the list of header file directories @emph{after} the directory 1115*e4b17023SJohn Marinoin which the current file was found. 1116*e4b17023SJohn Marino 1117*e4b17023SJohn MarinoSuppose you specify @option{-I /usr/local/include}, and the list of 1118*e4b17023SJohn Marinodirectories to search also includes @file{/usr/include}; and suppose 1119*e4b17023SJohn Marinoboth directories contain @file{signal.h}. Ordinary @code{@w{#include 1120*e4b17023SJohn Marino<signal.h>}} finds the file under @file{/usr/local/include}. If that 1121*e4b17023SJohn Marinofile contains @code{@w{#include_next <signal.h>}}, it starts searching 1122*e4b17023SJohn Marinoafter that directory, and finds the file in @file{/usr/include}. 1123*e4b17023SJohn Marino 1124*e4b17023SJohn Marino@samp{#include_next} does not distinguish between @code{<@var{file}>} 1125*e4b17023SJohn Marinoand @code{"@var{file}"} inclusion, nor does it check that the file you 1126*e4b17023SJohn Marinospecify has the same name as the current file. It simply looks for the 1127*e4b17023SJohn Marinofile named, starting with the directory in the search path after the one 1128*e4b17023SJohn Marinowhere the current file was found. 1129*e4b17023SJohn Marino 1130*e4b17023SJohn MarinoThe use of @samp{#include_next} can lead to great confusion. We 1131*e4b17023SJohn Marinorecommend it be used only when there is no other alternative. In 1132*e4b17023SJohn Marinoparticular, it should not be used in the headers belonging to a specific 1133*e4b17023SJohn Marinoprogram; it should be used only to make global corrections along the 1134*e4b17023SJohn Marinolines of @command{fixincludes}. 1135*e4b17023SJohn Marino 1136*e4b17023SJohn Marino@node System Headers 1137*e4b17023SJohn Marino@section System Headers 1138*e4b17023SJohn Marino@cindex system header files 1139*e4b17023SJohn Marino 1140*e4b17023SJohn MarinoThe header files declaring interfaces to the operating system and 1141*e4b17023SJohn Marinoruntime libraries often cannot be written in strictly conforming C@. 1142*e4b17023SJohn MarinoTherefore, GCC gives code found in @dfn{system headers} special 1143*e4b17023SJohn Marinotreatment. All warnings, other than those generated by @samp{#warning} 1144*e4b17023SJohn Marino(@pxref{Diagnostics}), are suppressed while GCC is processing a system 1145*e4b17023SJohn Marinoheader. Macros defined in a system header are immune to a few warnings 1146*e4b17023SJohn Marinowherever they are expanded. This immunity is granted on an ad-hoc 1147*e4b17023SJohn Marinobasis, when we find that a warning generates lots of false positives 1148*e4b17023SJohn Marinobecause of code in macros defined in system headers. 1149*e4b17023SJohn Marino 1150*e4b17023SJohn MarinoNormally, only the headers found in specific directories are considered 1151*e4b17023SJohn Marinosystem headers. These directories are determined when GCC is compiled. 1152*e4b17023SJohn MarinoThere are, however, two ways to make normal headers into system headers. 1153*e4b17023SJohn Marino 1154*e4b17023SJohn MarinoThe @option{-isystem} command line option adds its argument to the list of 1155*e4b17023SJohn Marinodirectories to search for headers, just like @option{-I}. Any headers 1156*e4b17023SJohn Marinofound in that directory will be considered system headers. 1157*e4b17023SJohn Marino 1158*e4b17023SJohn MarinoAll directories named by @option{-isystem} are searched @emph{after} all 1159*e4b17023SJohn Marinodirectories named by @option{-I}, no matter what their order was on the 1160*e4b17023SJohn Marinocommand line. If the same directory is named by both @option{-I} and 1161*e4b17023SJohn Marino@option{-isystem}, the @option{-I} option is ignored. GCC provides an 1162*e4b17023SJohn Marinoinformative message when this occurs if @option{-v} is used. 1163*e4b17023SJohn Marino 1164*e4b17023SJohn Marino@findex #pragma GCC system_header 1165*e4b17023SJohn MarinoThere is also a directive, @code{@w{#pragma GCC system_header}}, which 1166*e4b17023SJohn Marinotells GCC to consider the rest of the current include file a system 1167*e4b17023SJohn Marinoheader, no matter where it was found. Code that comes before the 1168*e4b17023SJohn Marino@samp{#pragma} in the file will not be affected. @code{@w{#pragma GCC 1169*e4b17023SJohn Marinosystem_header}} has no effect in the primary source file. 1170*e4b17023SJohn Marino 1171*e4b17023SJohn MarinoOn very old systems, some of the pre-defined system header directories 1172*e4b17023SJohn Marinoget even more special treatment. GNU C++ considers code in headers 1173*e4b17023SJohn Marinofound in those directories to be surrounded by an @code{@w{extern "C"}} 1174*e4b17023SJohn Marinoblock. There is no way to request this behavior with a @samp{#pragma}, 1175*e4b17023SJohn Marinoor from the command line. 1176*e4b17023SJohn Marino 1177*e4b17023SJohn Marino@node Macros 1178*e4b17023SJohn Marino@chapter Macros 1179*e4b17023SJohn Marino 1180*e4b17023SJohn MarinoA @dfn{macro} is a fragment of code which has been given a name. 1181*e4b17023SJohn MarinoWhenever the name is used, it is replaced by the contents of the macro. 1182*e4b17023SJohn MarinoThere are two kinds of macros. They differ mostly in what they look 1183*e4b17023SJohn Marinolike when they are used. @dfn{Object-like} macros resemble data objects 1184*e4b17023SJohn Marinowhen used, @dfn{function-like} macros resemble function calls. 1185*e4b17023SJohn Marino 1186*e4b17023SJohn MarinoYou may define any valid identifier as a macro, even if it is a C 1187*e4b17023SJohn Marinokeyword. The preprocessor does not know anything about keywords. This 1188*e4b17023SJohn Marinocan be useful if you wish to hide a keyword such as @code{const} from an 1189*e4b17023SJohn Marinoolder compiler that does not understand it. However, the preprocessor 1190*e4b17023SJohn Marinooperator @code{defined} (@pxref{Defined}) can never be defined as a 1191*e4b17023SJohn Marinomacro, and C++'s named operators (@pxref{C++ Named Operators}) cannot be 1192*e4b17023SJohn Marinomacros when you are compiling C++. 1193*e4b17023SJohn Marino 1194*e4b17023SJohn Marino@menu 1195*e4b17023SJohn Marino* Object-like Macros:: 1196*e4b17023SJohn Marino* Function-like Macros:: 1197*e4b17023SJohn Marino* Macro Arguments:: 1198*e4b17023SJohn Marino* Stringification:: 1199*e4b17023SJohn Marino* Concatenation:: 1200*e4b17023SJohn Marino* Variadic Macros:: 1201*e4b17023SJohn Marino* Predefined Macros:: 1202*e4b17023SJohn Marino* Undefining and Redefining Macros:: 1203*e4b17023SJohn Marino* Directives Within Macro Arguments:: 1204*e4b17023SJohn Marino* Macro Pitfalls:: 1205*e4b17023SJohn Marino@end menu 1206*e4b17023SJohn Marino 1207*e4b17023SJohn Marino@node Object-like Macros 1208*e4b17023SJohn Marino@section Object-like Macros 1209*e4b17023SJohn Marino@cindex object-like macro 1210*e4b17023SJohn Marino@cindex symbolic constants 1211*e4b17023SJohn Marino@cindex manifest constants 1212*e4b17023SJohn Marino 1213*e4b17023SJohn MarinoAn @dfn{object-like macro} is a simple identifier which will be replaced 1214*e4b17023SJohn Marinoby a code fragment. It is called object-like because it looks like a 1215*e4b17023SJohn Marinodata object in code that uses it. They are most commonly used to give 1216*e4b17023SJohn Marinosymbolic names to numeric constants. 1217*e4b17023SJohn Marino 1218*e4b17023SJohn Marino@findex #define 1219*e4b17023SJohn MarinoYou create macros with the @samp{#define} directive. @samp{#define} is 1220*e4b17023SJohn Marinofollowed by the name of the macro and then the token sequence it should 1221*e4b17023SJohn Marinobe an abbreviation for, which is variously referred to as the macro's 1222*e4b17023SJohn Marino@dfn{body}, @dfn{expansion} or @dfn{replacement list}. For example, 1223*e4b17023SJohn Marino 1224*e4b17023SJohn Marino@smallexample 1225*e4b17023SJohn Marino#define BUFFER_SIZE 1024 1226*e4b17023SJohn Marino@end smallexample 1227*e4b17023SJohn Marino 1228*e4b17023SJohn Marino@noindent 1229*e4b17023SJohn Marinodefines a macro named @code{BUFFER_SIZE} as an abbreviation for the 1230*e4b17023SJohn Marinotoken @code{1024}. If somewhere after this @samp{#define} directive 1231*e4b17023SJohn Marinothere comes a C statement of the form 1232*e4b17023SJohn Marino 1233*e4b17023SJohn Marino@smallexample 1234*e4b17023SJohn Marinofoo = (char *) malloc (BUFFER_SIZE); 1235*e4b17023SJohn Marino@end smallexample 1236*e4b17023SJohn Marino 1237*e4b17023SJohn Marino@noindent 1238*e4b17023SJohn Marinothen the C preprocessor will recognize and @dfn{expand} the macro 1239*e4b17023SJohn Marino@code{BUFFER_SIZE}. The C compiler will see the same tokens as it would 1240*e4b17023SJohn Marinoif you had written 1241*e4b17023SJohn Marino 1242*e4b17023SJohn Marino@smallexample 1243*e4b17023SJohn Marinofoo = (char *) malloc (1024); 1244*e4b17023SJohn Marino@end smallexample 1245*e4b17023SJohn Marino 1246*e4b17023SJohn MarinoBy convention, macro names are written in uppercase. Programs are 1247*e4b17023SJohn Marinoeasier to read when it is possible to tell at a glance which names are 1248*e4b17023SJohn Marinomacros. 1249*e4b17023SJohn Marino 1250*e4b17023SJohn MarinoThe macro's body ends at the end of the @samp{#define} line. You may 1251*e4b17023SJohn Marinocontinue the definition onto multiple lines, if necessary, using 1252*e4b17023SJohn Marinobackslash-newline. When the macro is expanded, however, it will all 1253*e4b17023SJohn Marinocome out on one line. For example, 1254*e4b17023SJohn Marino 1255*e4b17023SJohn Marino@smallexample 1256*e4b17023SJohn Marino#define NUMBERS 1, \ 1257*e4b17023SJohn Marino 2, \ 1258*e4b17023SJohn Marino 3 1259*e4b17023SJohn Marinoint x[] = @{ NUMBERS @}; 1260*e4b17023SJohn Marino @expansion{} int x[] = @{ 1, 2, 3 @}; 1261*e4b17023SJohn Marino@end smallexample 1262*e4b17023SJohn Marino 1263*e4b17023SJohn Marino@noindent 1264*e4b17023SJohn MarinoThe most common visible consequence of this is surprising line numbers 1265*e4b17023SJohn Marinoin error messages. 1266*e4b17023SJohn Marino 1267*e4b17023SJohn MarinoThere is no restriction on what can go in a macro body provided it 1268*e4b17023SJohn Marinodecomposes into valid preprocessing tokens. Parentheses need not 1269*e4b17023SJohn Marinobalance, and the body need not resemble valid C code. (If it does not, 1270*e4b17023SJohn Marinoyou may get error messages from the C compiler when you use the macro.) 1271*e4b17023SJohn Marino 1272*e4b17023SJohn MarinoThe C preprocessor scans your program sequentially. Macro definitions 1273*e4b17023SJohn Marinotake effect at the place you write them. Therefore, the following input 1274*e4b17023SJohn Marinoto the C preprocessor 1275*e4b17023SJohn Marino 1276*e4b17023SJohn Marino@smallexample 1277*e4b17023SJohn Marinofoo = X; 1278*e4b17023SJohn Marino#define X 4 1279*e4b17023SJohn Marinobar = X; 1280*e4b17023SJohn Marino@end smallexample 1281*e4b17023SJohn Marino 1282*e4b17023SJohn Marino@noindent 1283*e4b17023SJohn Marinoproduces 1284*e4b17023SJohn Marino 1285*e4b17023SJohn Marino@smallexample 1286*e4b17023SJohn Marinofoo = X; 1287*e4b17023SJohn Marinobar = 4; 1288*e4b17023SJohn Marino@end smallexample 1289*e4b17023SJohn Marino 1290*e4b17023SJohn MarinoWhen the preprocessor expands a macro name, the macro's expansion 1291*e4b17023SJohn Marinoreplaces the macro invocation, then the expansion is examined for more 1292*e4b17023SJohn Marinomacros to expand. For example, 1293*e4b17023SJohn Marino 1294*e4b17023SJohn Marino@smallexample 1295*e4b17023SJohn Marino@group 1296*e4b17023SJohn Marino#define TABLESIZE BUFSIZE 1297*e4b17023SJohn Marino#define BUFSIZE 1024 1298*e4b17023SJohn MarinoTABLESIZE 1299*e4b17023SJohn Marino @expansion{} BUFSIZE 1300*e4b17023SJohn Marino @expansion{} 1024 1301*e4b17023SJohn Marino@end group 1302*e4b17023SJohn Marino@end smallexample 1303*e4b17023SJohn Marino 1304*e4b17023SJohn Marino@noindent 1305*e4b17023SJohn Marino@code{TABLESIZE} is expanded first to produce @code{BUFSIZE}, then that 1306*e4b17023SJohn Marinomacro is expanded to produce the final result, @code{1024}. 1307*e4b17023SJohn Marino 1308*e4b17023SJohn MarinoNotice that @code{BUFSIZE} was not defined when @code{TABLESIZE} was 1309*e4b17023SJohn Marinodefined. The @samp{#define} for @code{TABLESIZE} uses exactly the 1310*e4b17023SJohn Marinoexpansion you specify---in this case, @code{BUFSIZE}---and does not 1311*e4b17023SJohn Marinocheck to see whether it too contains macro names. Only when you 1312*e4b17023SJohn Marino@emph{use} @code{TABLESIZE} is the result of its expansion scanned for 1313*e4b17023SJohn Marinomore macro names. 1314*e4b17023SJohn Marino 1315*e4b17023SJohn MarinoThis makes a difference if you change the definition of @code{BUFSIZE} 1316*e4b17023SJohn Marinoat some point in the source file. @code{TABLESIZE}, defined as shown, 1317*e4b17023SJohn Marinowill always expand using the definition of @code{BUFSIZE} that is 1318*e4b17023SJohn Marinocurrently in effect: 1319*e4b17023SJohn Marino 1320*e4b17023SJohn Marino@smallexample 1321*e4b17023SJohn Marino#define BUFSIZE 1020 1322*e4b17023SJohn Marino#define TABLESIZE BUFSIZE 1323*e4b17023SJohn Marino#undef BUFSIZE 1324*e4b17023SJohn Marino#define BUFSIZE 37 1325*e4b17023SJohn Marino@end smallexample 1326*e4b17023SJohn Marino 1327*e4b17023SJohn Marino@noindent 1328*e4b17023SJohn MarinoNow @code{TABLESIZE} expands (in two stages) to @code{37}. 1329*e4b17023SJohn Marino 1330*e4b17023SJohn MarinoIf the expansion of a macro contains its own name, either directly or 1331*e4b17023SJohn Marinovia intermediate macros, it is not expanded again when the expansion is 1332*e4b17023SJohn Marinoexamined for more macros. This prevents infinite recursion. 1333*e4b17023SJohn Marino@xref{Self-Referential Macros}, for the precise details. 1334*e4b17023SJohn Marino 1335*e4b17023SJohn Marino@node Function-like Macros 1336*e4b17023SJohn Marino@section Function-like Macros 1337*e4b17023SJohn Marino@cindex function-like macros 1338*e4b17023SJohn Marino 1339*e4b17023SJohn MarinoYou can also define macros whose use looks like a function call. These 1340*e4b17023SJohn Marinoare called @dfn{function-like macros}. To define a function-like macro, 1341*e4b17023SJohn Marinoyou use the same @samp{#define} directive, but you put a pair of 1342*e4b17023SJohn Marinoparentheses immediately after the macro name. For example, 1343*e4b17023SJohn Marino 1344*e4b17023SJohn Marino@smallexample 1345*e4b17023SJohn Marino#define lang_init() c_init() 1346*e4b17023SJohn Marinolang_init() 1347*e4b17023SJohn Marino @expansion{} c_init() 1348*e4b17023SJohn Marino@end smallexample 1349*e4b17023SJohn Marino 1350*e4b17023SJohn MarinoA function-like macro is only expanded if its name appears with a pair 1351*e4b17023SJohn Marinoof parentheses after it. If you write just the name, it is left alone. 1352*e4b17023SJohn MarinoThis can be useful when you have a function and a macro of the same 1353*e4b17023SJohn Marinoname, and you wish to use the function sometimes. 1354*e4b17023SJohn Marino 1355*e4b17023SJohn Marino@smallexample 1356*e4b17023SJohn Marinoextern void foo(void); 1357*e4b17023SJohn Marino#define foo() /* @r{optimized inline version} */ 1358*e4b17023SJohn Marino@dots{} 1359*e4b17023SJohn Marino foo(); 1360*e4b17023SJohn Marino funcptr = foo; 1361*e4b17023SJohn Marino@end smallexample 1362*e4b17023SJohn Marino 1363*e4b17023SJohn MarinoHere the call to @code{foo()} will use the macro, but the function 1364*e4b17023SJohn Marinopointer will get the address of the real function. If the macro were to 1365*e4b17023SJohn Marinobe expanded, it would cause a syntax error. 1366*e4b17023SJohn Marino 1367*e4b17023SJohn MarinoIf you put spaces between the macro name and the parentheses in the 1368*e4b17023SJohn Marinomacro definition, that does not define a function-like macro, it defines 1369*e4b17023SJohn Marinoan object-like macro whose expansion happens to begin with a pair of 1370*e4b17023SJohn Marinoparentheses. 1371*e4b17023SJohn Marino 1372*e4b17023SJohn Marino@smallexample 1373*e4b17023SJohn Marino#define lang_init () c_init() 1374*e4b17023SJohn Marinolang_init() 1375*e4b17023SJohn Marino @expansion{} () c_init()() 1376*e4b17023SJohn Marino@end smallexample 1377*e4b17023SJohn Marino 1378*e4b17023SJohn MarinoThe first two pairs of parentheses in this expansion come from the 1379*e4b17023SJohn Marinomacro. The third is the pair that was originally after the macro 1380*e4b17023SJohn Marinoinvocation. Since @code{lang_init} is an object-like macro, it does not 1381*e4b17023SJohn Marinoconsume those parentheses. 1382*e4b17023SJohn Marino 1383*e4b17023SJohn Marino@node Macro Arguments 1384*e4b17023SJohn Marino@section Macro Arguments 1385*e4b17023SJohn Marino@cindex arguments 1386*e4b17023SJohn Marino@cindex macros with arguments 1387*e4b17023SJohn Marino@cindex arguments in macro definitions 1388*e4b17023SJohn Marino 1389*e4b17023SJohn MarinoFunction-like macros can take @dfn{arguments}, just like true functions. 1390*e4b17023SJohn MarinoTo define a macro that uses arguments, you insert @dfn{parameters} 1391*e4b17023SJohn Marinobetween the pair of parentheses in the macro definition that make the 1392*e4b17023SJohn Marinomacro function-like. The parameters must be valid C identifiers, 1393*e4b17023SJohn Marinoseparated by commas and optionally whitespace. 1394*e4b17023SJohn Marino 1395*e4b17023SJohn MarinoTo invoke a macro that takes arguments, you write the name of the macro 1396*e4b17023SJohn Marinofollowed by a list of @dfn{actual arguments} in parentheses, separated 1397*e4b17023SJohn Marinoby commas. The invocation of the macro need not be restricted to a 1398*e4b17023SJohn Marinosingle logical line---it can cross as many lines in the source file as 1399*e4b17023SJohn Marinoyou wish. The number of arguments you give must match the number of 1400*e4b17023SJohn Marinoparameters in the macro definition. When the macro is expanded, each 1401*e4b17023SJohn Marinouse of a parameter in its body is replaced by the tokens of the 1402*e4b17023SJohn Marinocorresponding argument. (You need not use all of the parameters in the 1403*e4b17023SJohn Marinomacro body.) 1404*e4b17023SJohn Marino 1405*e4b17023SJohn MarinoAs an example, here is a macro that computes the minimum of two numeric 1406*e4b17023SJohn Marinovalues, as it is defined in many C programs, and some uses. 1407*e4b17023SJohn Marino 1408*e4b17023SJohn Marino@smallexample 1409*e4b17023SJohn Marino#define min(X, Y) ((X) < (Y) ? (X) : (Y)) 1410*e4b17023SJohn Marino x = min(a, b); @expansion{} x = ((a) < (b) ? (a) : (b)); 1411*e4b17023SJohn Marino y = min(1, 2); @expansion{} y = ((1) < (2) ? (1) : (2)); 1412*e4b17023SJohn Marino z = min(a + 28, *p); @expansion{} z = ((a + 28) < (*p) ? (a + 28) : (*p)); 1413*e4b17023SJohn Marino@end smallexample 1414*e4b17023SJohn Marino 1415*e4b17023SJohn Marino@noindent 1416*e4b17023SJohn Marino(In this small example you can already see several of the dangers of 1417*e4b17023SJohn Marinomacro arguments. @xref{Macro Pitfalls}, for detailed explanations.) 1418*e4b17023SJohn Marino 1419*e4b17023SJohn MarinoLeading and trailing whitespace in each argument is dropped, and all 1420*e4b17023SJohn Marinowhitespace between the tokens of an argument is reduced to a single 1421*e4b17023SJohn Marinospace. Parentheses within each argument must balance; a comma within 1422*e4b17023SJohn Marinosuch parentheses does not end the argument. However, there is no 1423*e4b17023SJohn Marinorequirement for square brackets or braces to balance, and they do not 1424*e4b17023SJohn Marinoprevent a comma from separating arguments. Thus, 1425*e4b17023SJohn Marino 1426*e4b17023SJohn Marino@smallexample 1427*e4b17023SJohn Marinomacro (array[x = y, x + 1]) 1428*e4b17023SJohn Marino@end smallexample 1429*e4b17023SJohn Marino 1430*e4b17023SJohn Marino@noindent 1431*e4b17023SJohn Marinopasses two arguments to @code{macro}: @code{array[x = y} and @code{x + 1432*e4b17023SJohn Marino1]}. If you want to supply @code{array[x = y, x + 1]} as an argument, 1433*e4b17023SJohn Marinoyou can write it as @code{array[(x = y, x + 1)]}, which is equivalent C 1434*e4b17023SJohn Marinocode. 1435*e4b17023SJohn Marino 1436*e4b17023SJohn MarinoAll arguments to a macro are completely macro-expanded before they are 1437*e4b17023SJohn Marinosubstituted into the macro body. After substitution, the complete text 1438*e4b17023SJohn Marinois scanned again for macros to expand, including the arguments. This rule 1439*e4b17023SJohn Marinomay seem strange, but it is carefully designed so you need not worry 1440*e4b17023SJohn Marinoabout whether any function call is actually a macro invocation. You can 1441*e4b17023SJohn Marinorun into trouble if you try to be too clever, though. @xref{Argument 1442*e4b17023SJohn MarinoPrescan}, for detailed discussion. 1443*e4b17023SJohn Marino 1444*e4b17023SJohn MarinoFor example, @code{min (min (a, b), c)} is first expanded to 1445*e4b17023SJohn Marino 1446*e4b17023SJohn Marino@smallexample 1447*e4b17023SJohn Marino min (((a) < (b) ? (a) : (b)), (c)) 1448*e4b17023SJohn Marino@end smallexample 1449*e4b17023SJohn Marino 1450*e4b17023SJohn Marino@noindent 1451*e4b17023SJohn Marinoand then to 1452*e4b17023SJohn Marino 1453*e4b17023SJohn Marino@smallexample 1454*e4b17023SJohn Marino@group 1455*e4b17023SJohn Marino((((a) < (b) ? (a) : (b))) < (c) 1456*e4b17023SJohn Marino ? (((a) < (b) ? (a) : (b))) 1457*e4b17023SJohn Marino : (c)) 1458*e4b17023SJohn Marino@end group 1459*e4b17023SJohn Marino@end smallexample 1460*e4b17023SJohn Marino 1461*e4b17023SJohn Marino@noindent 1462*e4b17023SJohn Marino(Line breaks shown here for clarity would not actually be generated.) 1463*e4b17023SJohn Marino 1464*e4b17023SJohn Marino@cindex empty macro arguments 1465*e4b17023SJohn MarinoYou can leave macro arguments empty; this is not an error to the 1466*e4b17023SJohn Marinopreprocessor (but many macros will then expand to invalid code). 1467*e4b17023SJohn MarinoYou cannot leave out arguments entirely; if a macro takes two arguments, 1468*e4b17023SJohn Marinothere must be exactly one comma at the top level of its argument list. 1469*e4b17023SJohn MarinoHere are some silly examples using @code{min}: 1470*e4b17023SJohn Marino 1471*e4b17023SJohn Marino@smallexample 1472*e4b17023SJohn Marinomin(, b) @expansion{} (( ) < (b) ? ( ) : (b)) 1473*e4b17023SJohn Marinomin(a, ) @expansion{} ((a ) < ( ) ? (a ) : ( )) 1474*e4b17023SJohn Marinomin(,) @expansion{} (( ) < ( ) ? ( ) : ( )) 1475*e4b17023SJohn Marinomin((,),) @expansion{} (((,)) < ( ) ? ((,)) : ( )) 1476*e4b17023SJohn Marino 1477*e4b17023SJohn Marinomin() @error{} macro "min" requires 2 arguments, but only 1 given 1478*e4b17023SJohn Marinomin(,,) @error{} macro "min" passed 3 arguments, but takes just 2 1479*e4b17023SJohn Marino@end smallexample 1480*e4b17023SJohn Marino 1481*e4b17023SJohn MarinoWhitespace is not a preprocessing token, so if a macro @code{foo} takes 1482*e4b17023SJohn Marinoone argument, @code{@w{foo ()}} and @code{@w{foo ( )}} both supply it an 1483*e4b17023SJohn Marinoempty argument. Previous GNU preprocessor implementations and 1484*e4b17023SJohn Marinodocumentation were incorrect on this point, insisting that a 1485*e4b17023SJohn Marinofunction-like macro that takes a single argument be passed a space if an 1486*e4b17023SJohn Marinoempty argument was required. 1487*e4b17023SJohn Marino 1488*e4b17023SJohn MarinoMacro parameters appearing inside string literals are not replaced by 1489*e4b17023SJohn Marinotheir corresponding actual arguments. 1490*e4b17023SJohn Marino 1491*e4b17023SJohn Marino@smallexample 1492*e4b17023SJohn Marino#define foo(x) x, "x" 1493*e4b17023SJohn Marinofoo(bar) @expansion{} bar, "x" 1494*e4b17023SJohn Marino@end smallexample 1495*e4b17023SJohn Marino 1496*e4b17023SJohn Marino@node Stringification 1497*e4b17023SJohn Marino@section Stringification 1498*e4b17023SJohn Marino@cindex stringification 1499*e4b17023SJohn Marino@cindex @samp{#} operator 1500*e4b17023SJohn Marino 1501*e4b17023SJohn MarinoSometimes you may want to convert a macro argument into a string 1502*e4b17023SJohn Marinoconstant. Parameters are not replaced inside string constants, but you 1503*e4b17023SJohn Marinocan use the @samp{#} preprocessing operator instead. When a macro 1504*e4b17023SJohn Marinoparameter is used with a leading @samp{#}, the preprocessor replaces it 1505*e4b17023SJohn Marinowith the literal text of the actual argument, converted to a string 1506*e4b17023SJohn Marinoconstant. Unlike normal parameter replacement, the argument is not 1507*e4b17023SJohn Marinomacro-expanded first. This is called @dfn{stringification}. 1508*e4b17023SJohn Marino 1509*e4b17023SJohn MarinoThere is no way to combine an argument with surrounding text and 1510*e4b17023SJohn Marinostringify it all together. Instead, you can write a series of adjacent 1511*e4b17023SJohn Marinostring constants and stringified arguments. The preprocessor will 1512*e4b17023SJohn Marinoreplace the stringified arguments with string constants. The C 1513*e4b17023SJohn Marinocompiler will then combine all the adjacent string constants into one 1514*e4b17023SJohn Marinolong string. 1515*e4b17023SJohn Marino 1516*e4b17023SJohn MarinoHere is an example of a macro definition that uses stringification: 1517*e4b17023SJohn Marino 1518*e4b17023SJohn Marino@smallexample 1519*e4b17023SJohn Marino@group 1520*e4b17023SJohn Marino#define WARN_IF(EXP) \ 1521*e4b17023SJohn Marinodo @{ if (EXP) \ 1522*e4b17023SJohn Marino fprintf (stderr, "Warning: " #EXP "\n"); @} \ 1523*e4b17023SJohn Marinowhile (0) 1524*e4b17023SJohn MarinoWARN_IF (x == 0); 1525*e4b17023SJohn Marino @expansion{} do @{ if (x == 0) 1526*e4b17023SJohn Marino fprintf (stderr, "Warning: " "x == 0" "\n"); @} while (0); 1527*e4b17023SJohn Marino@end group 1528*e4b17023SJohn Marino@end smallexample 1529*e4b17023SJohn Marino 1530*e4b17023SJohn Marino@noindent 1531*e4b17023SJohn MarinoThe argument for @code{EXP} is substituted once, as-is, into the 1532*e4b17023SJohn Marino@code{if} statement, and once, stringified, into the argument to 1533*e4b17023SJohn Marino@code{fprintf}. If @code{x} were a macro, it would be expanded in the 1534*e4b17023SJohn Marino@code{if} statement, but not in the string. 1535*e4b17023SJohn Marino 1536*e4b17023SJohn MarinoThe @code{do} and @code{while (0)} are a kludge to make it possible to 1537*e4b17023SJohn Marinowrite @code{WARN_IF (@var{arg});}, which the resemblance of 1538*e4b17023SJohn Marino@code{WARN_IF} to a function would make C programmers want to do; see 1539*e4b17023SJohn Marino@ref{Swallowing the Semicolon}. 1540*e4b17023SJohn Marino 1541*e4b17023SJohn MarinoStringification in C involves more than putting double-quote characters 1542*e4b17023SJohn Marinoaround the fragment. The preprocessor backslash-escapes the quotes 1543*e4b17023SJohn Marinosurrounding embedded string constants, and all backslashes within string and 1544*e4b17023SJohn Marinocharacter constants, in order to get a valid C string constant with the 1545*e4b17023SJohn Marinoproper contents. Thus, stringifying @code{@w{p = "foo\n";}} results in 1546*e4b17023SJohn Marino@t{@w{"p = \"foo\\n\";"}}. However, backslashes that are not inside string 1547*e4b17023SJohn Marinoor character constants are not duplicated: @samp{\n} by itself 1548*e4b17023SJohn Marinostringifies to @t{"\n"}. 1549*e4b17023SJohn Marino 1550*e4b17023SJohn MarinoAll leading and trailing whitespace in text being stringified is 1551*e4b17023SJohn Marinoignored. Any sequence of whitespace in the middle of the text is 1552*e4b17023SJohn Marinoconverted to a single space in the stringified result. Comments are 1553*e4b17023SJohn Marinoreplaced by whitespace long before stringification happens, so they 1554*e4b17023SJohn Marinonever appear in stringified text. 1555*e4b17023SJohn Marino 1556*e4b17023SJohn MarinoThere is no way to convert a macro argument into a character constant. 1557*e4b17023SJohn Marino 1558*e4b17023SJohn MarinoIf you want to stringify the result of expansion of a macro argument, 1559*e4b17023SJohn Marinoyou have to use two levels of macros. 1560*e4b17023SJohn Marino 1561*e4b17023SJohn Marino@smallexample 1562*e4b17023SJohn Marino#define xstr(s) str(s) 1563*e4b17023SJohn Marino#define str(s) #s 1564*e4b17023SJohn Marino#define foo 4 1565*e4b17023SJohn Marinostr (foo) 1566*e4b17023SJohn Marino @expansion{} "foo" 1567*e4b17023SJohn Marinoxstr (foo) 1568*e4b17023SJohn Marino @expansion{} xstr (4) 1569*e4b17023SJohn Marino @expansion{} str (4) 1570*e4b17023SJohn Marino @expansion{} "4" 1571*e4b17023SJohn Marino@end smallexample 1572*e4b17023SJohn Marino 1573*e4b17023SJohn Marino@code{s} is stringified when it is used in @code{str}, so it is not 1574*e4b17023SJohn Marinomacro-expanded first. But @code{s} is an ordinary argument to 1575*e4b17023SJohn Marino@code{xstr}, so it is completely macro-expanded before @code{xstr} 1576*e4b17023SJohn Marinoitself is expanded (@pxref{Argument Prescan}). Therefore, by the time 1577*e4b17023SJohn Marino@code{str} gets to its argument, it has already been macro-expanded. 1578*e4b17023SJohn Marino 1579*e4b17023SJohn Marino@node Concatenation 1580*e4b17023SJohn Marino@section Concatenation 1581*e4b17023SJohn Marino@cindex concatenation 1582*e4b17023SJohn Marino@cindex token pasting 1583*e4b17023SJohn Marino@cindex token concatenation 1584*e4b17023SJohn Marino@cindex @samp{##} operator 1585*e4b17023SJohn Marino 1586*e4b17023SJohn MarinoIt is often useful to merge two tokens into one while expanding macros. 1587*e4b17023SJohn MarinoThis is called @dfn{token pasting} or @dfn{token concatenation}. The 1588*e4b17023SJohn Marino@samp{##} preprocessing operator performs token pasting. When a macro 1589*e4b17023SJohn Marinois expanded, the two tokens on either side of each @samp{##} operator 1590*e4b17023SJohn Marinoare combined into a single token, which then replaces the @samp{##} and 1591*e4b17023SJohn Marinothe two original tokens in the macro expansion. Usually both will be 1592*e4b17023SJohn Marinoidentifiers, or one will be an identifier and the other a preprocessing 1593*e4b17023SJohn Marinonumber. When pasted, they make a longer identifier. This isn't the 1594*e4b17023SJohn Marinoonly valid case. It is also possible to concatenate two numbers (or a 1595*e4b17023SJohn Marinonumber and a name, such as @code{1.5} and @code{e3}) into a number. 1596*e4b17023SJohn MarinoAlso, multi-character operators such as @code{+=} can be formed by 1597*e4b17023SJohn Marinotoken pasting. 1598*e4b17023SJohn Marino 1599*e4b17023SJohn MarinoHowever, two tokens that don't together form a valid token cannot be 1600*e4b17023SJohn Marinopasted together. For example, you cannot concatenate @code{x} with 1601*e4b17023SJohn Marino@code{+} in either order. If you try, the preprocessor issues a warning 1602*e4b17023SJohn Marinoand emits the two tokens. Whether it puts white space between the 1603*e4b17023SJohn Marinotokens is undefined. It is common to find unnecessary uses of @samp{##} 1604*e4b17023SJohn Marinoin complex macros. If you get this warning, it is likely that you can 1605*e4b17023SJohn Marinosimply remove the @samp{##}. 1606*e4b17023SJohn Marino 1607*e4b17023SJohn MarinoBoth the tokens combined by @samp{##} could come from the macro body, 1608*e4b17023SJohn Marinobut you could just as well write them as one token in the first place. 1609*e4b17023SJohn MarinoToken pasting is most useful when one or both of the tokens comes from a 1610*e4b17023SJohn Marinomacro argument. If either of the tokens next to an @samp{##} is a 1611*e4b17023SJohn Marinoparameter name, it is replaced by its actual argument before @samp{##} 1612*e4b17023SJohn Marinoexecutes. As with stringification, the actual argument is not 1613*e4b17023SJohn Marinomacro-expanded first. If the argument is empty, that @samp{##} has no 1614*e4b17023SJohn Marinoeffect. 1615*e4b17023SJohn Marino 1616*e4b17023SJohn MarinoKeep in mind that the C preprocessor converts comments to whitespace 1617*e4b17023SJohn Marinobefore macros are even considered. Therefore, you cannot create a 1618*e4b17023SJohn Marinocomment by concatenating @samp{/} and @samp{*}. You can put as much 1619*e4b17023SJohn Marinowhitespace between @samp{##} and its operands as you like, including 1620*e4b17023SJohn Marinocomments, and you can put comments in arguments that will be 1621*e4b17023SJohn Marinoconcatenated. However, it is an error if @samp{##} appears at either 1622*e4b17023SJohn Marinoend of a macro body. 1623*e4b17023SJohn Marino 1624*e4b17023SJohn MarinoConsider a C program that interprets named commands. There probably 1625*e4b17023SJohn Marinoneeds to be a table of commands, perhaps an array of structures declared 1626*e4b17023SJohn Marinoas follows: 1627*e4b17023SJohn Marino 1628*e4b17023SJohn Marino@smallexample 1629*e4b17023SJohn Marino@group 1630*e4b17023SJohn Marinostruct command 1631*e4b17023SJohn Marino@{ 1632*e4b17023SJohn Marino char *name; 1633*e4b17023SJohn Marino void (*function) (void); 1634*e4b17023SJohn Marino@}; 1635*e4b17023SJohn Marino@end group 1636*e4b17023SJohn Marino 1637*e4b17023SJohn Marino@group 1638*e4b17023SJohn Marinostruct command commands[] = 1639*e4b17023SJohn Marino@{ 1640*e4b17023SJohn Marino @{ "quit", quit_command @}, 1641*e4b17023SJohn Marino @{ "help", help_command @}, 1642*e4b17023SJohn Marino @dots{} 1643*e4b17023SJohn Marino@}; 1644*e4b17023SJohn Marino@end group 1645*e4b17023SJohn Marino@end smallexample 1646*e4b17023SJohn Marino 1647*e4b17023SJohn MarinoIt would be cleaner not to have to give each command name twice, once in 1648*e4b17023SJohn Marinothe string constant and once in the function name. A macro which takes the 1649*e4b17023SJohn Marinoname of a command as an argument can make this unnecessary. The string 1650*e4b17023SJohn Marinoconstant can be created with stringification, and the function name by 1651*e4b17023SJohn Marinoconcatenating the argument with @samp{_command}. Here is how it is done: 1652*e4b17023SJohn Marino 1653*e4b17023SJohn Marino@smallexample 1654*e4b17023SJohn Marino#define COMMAND(NAME) @{ #NAME, NAME ## _command @} 1655*e4b17023SJohn Marino 1656*e4b17023SJohn Marinostruct command commands[] = 1657*e4b17023SJohn Marino@{ 1658*e4b17023SJohn Marino COMMAND (quit), 1659*e4b17023SJohn Marino COMMAND (help), 1660*e4b17023SJohn Marino @dots{} 1661*e4b17023SJohn Marino@}; 1662*e4b17023SJohn Marino@end smallexample 1663*e4b17023SJohn Marino 1664*e4b17023SJohn Marino@node Variadic Macros 1665*e4b17023SJohn Marino@section Variadic Macros 1666*e4b17023SJohn Marino@cindex variable number of arguments 1667*e4b17023SJohn Marino@cindex macros with variable arguments 1668*e4b17023SJohn Marino@cindex variadic macros 1669*e4b17023SJohn Marino 1670*e4b17023SJohn MarinoA macro can be declared to accept a variable number of arguments much as 1671*e4b17023SJohn Marinoa function can. The syntax for defining the macro is similar to that of 1672*e4b17023SJohn Marinoa function. Here is an example: 1673*e4b17023SJohn Marino 1674*e4b17023SJohn Marino@smallexample 1675*e4b17023SJohn Marino#define eprintf(@dots{}) fprintf (stderr, __VA_ARGS__) 1676*e4b17023SJohn Marino@end smallexample 1677*e4b17023SJohn Marino 1678*e4b17023SJohn MarinoThis kind of macro is called @dfn{variadic}. When the macro is invoked, 1679*e4b17023SJohn Marinoall the tokens in its argument list after the last named argument (this 1680*e4b17023SJohn Marinomacro has none), including any commas, become the @dfn{variable 1681*e4b17023SJohn Marinoargument}. This sequence of tokens replaces the identifier 1682*e4b17023SJohn Marino@code{@w{__VA_ARGS__}} in the macro body wherever it appears. Thus, we 1683*e4b17023SJohn Marinohave this expansion: 1684*e4b17023SJohn Marino 1685*e4b17023SJohn Marino@smallexample 1686*e4b17023SJohn Marinoeprintf ("%s:%d: ", input_file, lineno) 1687*e4b17023SJohn Marino @expansion{} fprintf (stderr, "%s:%d: ", input_file, lineno) 1688*e4b17023SJohn Marino@end smallexample 1689*e4b17023SJohn Marino 1690*e4b17023SJohn MarinoThe variable argument is completely macro-expanded before it is inserted 1691*e4b17023SJohn Marinointo the macro expansion, just like an ordinary argument. You may use 1692*e4b17023SJohn Marinothe @samp{#} and @samp{##} operators to stringify the variable argument 1693*e4b17023SJohn Marinoor to paste its leading or trailing token with another token. (But see 1694*e4b17023SJohn Marinobelow for an important special case for @samp{##}.) 1695*e4b17023SJohn Marino 1696*e4b17023SJohn MarinoIf your macro is complicated, you may want a more descriptive name for 1697*e4b17023SJohn Marinothe variable argument than @code{@w{__VA_ARGS__}}. CPP permits 1698*e4b17023SJohn Marinothis, as an extension. You may write an argument name immediately 1699*e4b17023SJohn Marinobefore the @samp{@dots{}}; that name is used for the variable argument. 1700*e4b17023SJohn MarinoThe @code{eprintf} macro above could be written 1701*e4b17023SJohn Marino 1702*e4b17023SJohn Marino@smallexample 1703*e4b17023SJohn Marino#define eprintf(args@dots{}) fprintf (stderr, args) 1704*e4b17023SJohn Marino@end smallexample 1705*e4b17023SJohn Marino 1706*e4b17023SJohn Marino@noindent 1707*e4b17023SJohn Marinousing this extension. You cannot use @code{@w{__VA_ARGS__}} and this 1708*e4b17023SJohn Marinoextension in the same macro. 1709*e4b17023SJohn Marino 1710*e4b17023SJohn MarinoYou can have named arguments as well as variable arguments in a variadic 1711*e4b17023SJohn Marinomacro. We could define @code{eprintf} like this, instead: 1712*e4b17023SJohn Marino 1713*e4b17023SJohn Marino@smallexample 1714*e4b17023SJohn Marino#define eprintf(format, @dots{}) fprintf (stderr, format, __VA_ARGS__) 1715*e4b17023SJohn Marino@end smallexample 1716*e4b17023SJohn Marino 1717*e4b17023SJohn Marino@noindent 1718*e4b17023SJohn MarinoThis formulation looks more descriptive, but unfortunately it is less 1719*e4b17023SJohn Marinoflexible: you must now supply at least one argument after the format 1720*e4b17023SJohn Marinostring. In standard C, you cannot omit the comma separating the named 1721*e4b17023SJohn Marinoargument from the variable arguments. Furthermore, if you leave the 1722*e4b17023SJohn Marinovariable argument empty, you will get a syntax error, because 1723*e4b17023SJohn Marinothere will be an extra comma after the format string. 1724*e4b17023SJohn Marino 1725*e4b17023SJohn Marino@smallexample 1726*e4b17023SJohn Marinoeprintf("success!\n", ); 1727*e4b17023SJohn Marino @expansion{} fprintf(stderr, "success!\n", ); 1728*e4b17023SJohn Marino@end smallexample 1729*e4b17023SJohn Marino 1730*e4b17023SJohn MarinoGNU CPP has a pair of extensions which deal with this problem. First, 1731*e4b17023SJohn Marinoyou are allowed to leave the variable argument out entirely: 1732*e4b17023SJohn Marino 1733*e4b17023SJohn Marino@smallexample 1734*e4b17023SJohn Marinoeprintf ("success!\n") 1735*e4b17023SJohn Marino @expansion{} fprintf(stderr, "success!\n", ); 1736*e4b17023SJohn Marino@end smallexample 1737*e4b17023SJohn Marino 1738*e4b17023SJohn Marino@noindent 1739*e4b17023SJohn MarinoSecond, the @samp{##} token paste operator has a special meaning when 1740*e4b17023SJohn Marinoplaced between a comma and a variable argument. If you write 1741*e4b17023SJohn Marino 1742*e4b17023SJohn Marino@smallexample 1743*e4b17023SJohn Marino#define eprintf(format, @dots{}) fprintf (stderr, format, ##__VA_ARGS__) 1744*e4b17023SJohn Marino@end smallexample 1745*e4b17023SJohn Marino 1746*e4b17023SJohn Marino@noindent 1747*e4b17023SJohn Marinoand the variable argument is left out when the @code{eprintf} macro is 1748*e4b17023SJohn Marinoused, then the comma before the @samp{##} will be deleted. This does 1749*e4b17023SJohn Marino@emph{not} happen if you pass an empty argument, nor does it happen if 1750*e4b17023SJohn Marinothe token preceding @samp{##} is anything other than a comma. 1751*e4b17023SJohn Marino 1752*e4b17023SJohn Marino@smallexample 1753*e4b17023SJohn Marinoeprintf ("success!\n") 1754*e4b17023SJohn Marino @expansion{} fprintf(stderr, "success!\n"); 1755*e4b17023SJohn Marino@end smallexample 1756*e4b17023SJohn Marino 1757*e4b17023SJohn Marino@noindent 1758*e4b17023SJohn MarinoThe above explanation is ambiguous about the case where the only macro 1759*e4b17023SJohn Marinoparameter is a variable arguments parameter, as it is meaningless to 1760*e4b17023SJohn Marinotry to distinguish whether no argument at all is an empty argument or 1761*e4b17023SJohn Marinoa missing argument. In this case the C99 standard is clear that the 1762*e4b17023SJohn Marinocomma must remain, however the existing GCC extension used to swallow 1763*e4b17023SJohn Marinothe comma. So CPP retains the comma when conforming to a specific C 1764*e4b17023SJohn Marinostandard, and drops it otherwise. 1765*e4b17023SJohn Marino 1766*e4b17023SJohn MarinoC99 mandates that the only place the identifier @code{@w{__VA_ARGS__}} 1767*e4b17023SJohn Marinocan appear is in the replacement list of a variadic macro. It may not 1768*e4b17023SJohn Marinobe used as a macro name, macro argument name, or within a different type 1769*e4b17023SJohn Marinoof macro. It may also be forbidden in open text; the standard is 1770*e4b17023SJohn Marinoambiguous. We recommend you avoid using it except for its defined 1771*e4b17023SJohn Marinopurpose. 1772*e4b17023SJohn Marino 1773*e4b17023SJohn MarinoVariadic macros are a new feature in C99. GNU CPP has supported them 1774*e4b17023SJohn Marinofor a long time, but only with a named variable argument 1775*e4b17023SJohn Marino(@samp{args@dots{}}, not @samp{@dots{}} and @code{@w{__VA_ARGS__}}). If you are 1776*e4b17023SJohn Marinoconcerned with portability to previous versions of GCC, you should use 1777*e4b17023SJohn Marinoonly named variable arguments. On the other hand, if you are concerned 1778*e4b17023SJohn Marinowith portability to other conforming implementations of C99, you should 1779*e4b17023SJohn Marinouse only @code{@w{__VA_ARGS__}}. 1780*e4b17023SJohn Marino 1781*e4b17023SJohn MarinoPrevious versions of CPP implemented the comma-deletion extension 1782*e4b17023SJohn Marinomuch more generally. We have restricted it in this release to minimize 1783*e4b17023SJohn Marinothe differences from C99. To get the same effect with both this and 1784*e4b17023SJohn Marinoprevious versions of GCC, the token preceding the special @samp{##} must 1785*e4b17023SJohn Marinobe a comma, and there must be white space between that comma and 1786*e4b17023SJohn Marinowhatever comes immediately before it: 1787*e4b17023SJohn Marino 1788*e4b17023SJohn Marino@smallexample 1789*e4b17023SJohn Marino#define eprintf(format, args@dots{}) fprintf (stderr, format , ##args) 1790*e4b17023SJohn Marino@end smallexample 1791*e4b17023SJohn Marino 1792*e4b17023SJohn Marino@noindent 1793*e4b17023SJohn Marino@xref{Differences from previous versions}, for the gory details. 1794*e4b17023SJohn Marino 1795*e4b17023SJohn Marino@node Predefined Macros 1796*e4b17023SJohn Marino@section Predefined Macros 1797*e4b17023SJohn Marino 1798*e4b17023SJohn Marino@cindex predefined macros 1799*e4b17023SJohn MarinoSeveral object-like macros are predefined; you use them without 1800*e4b17023SJohn Marinosupplying their definitions. They fall into three classes: standard, 1801*e4b17023SJohn Marinocommon, and system-specific. 1802*e4b17023SJohn Marino 1803*e4b17023SJohn MarinoIn C++, there is a fourth category, the named operators. They act like 1804*e4b17023SJohn Marinopredefined macros, but you cannot undefine them. 1805*e4b17023SJohn Marino 1806*e4b17023SJohn Marino@menu 1807*e4b17023SJohn Marino* Standard Predefined Macros:: 1808*e4b17023SJohn Marino* Common Predefined Macros:: 1809*e4b17023SJohn Marino* System-specific Predefined Macros:: 1810*e4b17023SJohn Marino* C++ Named Operators:: 1811*e4b17023SJohn Marino@end menu 1812*e4b17023SJohn Marino 1813*e4b17023SJohn Marino@node Standard Predefined Macros 1814*e4b17023SJohn Marino@subsection Standard Predefined Macros 1815*e4b17023SJohn Marino@cindex standard predefined macros. 1816*e4b17023SJohn Marino 1817*e4b17023SJohn MarinoThe standard predefined macros are specified by the relevant 1818*e4b17023SJohn Marinolanguage standards, so they are available with all compilers that 1819*e4b17023SJohn Marinoimplement those standards. Older compilers may not provide all of 1820*e4b17023SJohn Marinothem. Their names all start with double underscores. 1821*e4b17023SJohn Marino 1822*e4b17023SJohn Marino@table @code 1823*e4b17023SJohn Marino@item __FILE__ 1824*e4b17023SJohn MarinoThis macro expands to the name of the current input file, in the form of 1825*e4b17023SJohn Marinoa C string constant. This is the path by which the preprocessor opened 1826*e4b17023SJohn Marinothe file, not the short name specified in @samp{#include} or as the 1827*e4b17023SJohn Marinoinput file name argument. For example, 1828*e4b17023SJohn Marino@code{"/usr/local/include/myheader.h"} is a possible expansion of this 1829*e4b17023SJohn Marinomacro. 1830*e4b17023SJohn Marino 1831*e4b17023SJohn Marino@item __LINE__ 1832*e4b17023SJohn MarinoThis macro expands to the current input line number, in the form of a 1833*e4b17023SJohn Marinodecimal integer constant. While we call it a predefined macro, it's 1834*e4b17023SJohn Marinoa pretty strange macro, since its ``definition'' changes with each 1835*e4b17023SJohn Marinonew line of source code. 1836*e4b17023SJohn Marino@end table 1837*e4b17023SJohn Marino 1838*e4b17023SJohn Marino@code{__FILE__} and @code{__LINE__} are useful in generating an error 1839*e4b17023SJohn Marinomessage to report an inconsistency detected by the program; the message 1840*e4b17023SJohn Marinocan state the source line at which the inconsistency was detected. For 1841*e4b17023SJohn Marinoexample, 1842*e4b17023SJohn Marino 1843*e4b17023SJohn Marino@smallexample 1844*e4b17023SJohn Marinofprintf (stderr, "Internal error: " 1845*e4b17023SJohn Marino "negative string length " 1846*e4b17023SJohn Marino "%d at %s, line %d.", 1847*e4b17023SJohn Marino length, __FILE__, __LINE__); 1848*e4b17023SJohn Marino@end smallexample 1849*e4b17023SJohn Marino 1850*e4b17023SJohn MarinoAn @samp{#include} directive changes the expansions of @code{__FILE__} 1851*e4b17023SJohn Marinoand @code{__LINE__} to correspond to the included file. At the end of 1852*e4b17023SJohn Marinothat file, when processing resumes on the input file that contained 1853*e4b17023SJohn Marinothe @samp{#include} directive, the expansions of @code{__FILE__} and 1854*e4b17023SJohn Marino@code{__LINE__} revert to the values they had before the 1855*e4b17023SJohn Marino@samp{#include} (but @code{__LINE__} is then incremented by one as 1856*e4b17023SJohn Marinoprocessing moves to the line after the @samp{#include}). 1857*e4b17023SJohn Marino 1858*e4b17023SJohn MarinoA @samp{#line} directive changes @code{__LINE__}, and may change 1859*e4b17023SJohn Marino@code{__FILE__} as well. @xref{Line Control}. 1860*e4b17023SJohn Marino 1861*e4b17023SJohn MarinoC99 introduces @code{__func__}, and GCC has provided @code{__FUNCTION__} 1862*e4b17023SJohn Marinofor a long time. Both of these are strings containing the name of the 1863*e4b17023SJohn Marinocurrent function (there are slight semantic differences; see the GCC 1864*e4b17023SJohn Marinomanual). Neither of them is a macro; the preprocessor does not know the 1865*e4b17023SJohn Marinoname of the current function. They tend to be useful in conjunction 1866*e4b17023SJohn Marinowith @code{__FILE__} and @code{__LINE__}, though. 1867*e4b17023SJohn Marino 1868*e4b17023SJohn Marino@table @code 1869*e4b17023SJohn Marino 1870*e4b17023SJohn Marino@item __DATE__ 1871*e4b17023SJohn MarinoThis macro expands to a string constant that describes the date on which 1872*e4b17023SJohn Marinothe preprocessor is being run. The string constant contains eleven 1873*e4b17023SJohn Marinocharacters and looks like @code{@w{"Feb 12 1996"}}. If the day of the 1874*e4b17023SJohn Marinomonth is less than 10, it is padded with a space on the left. 1875*e4b17023SJohn Marino 1876*e4b17023SJohn MarinoIf GCC cannot determine the current date, it will emit a warning message 1877*e4b17023SJohn Marino(once per compilation) and @code{__DATE__} will expand to 1878*e4b17023SJohn Marino@code{@w{"??? ?? ????"}}. 1879*e4b17023SJohn Marino 1880*e4b17023SJohn Marino@item __TIME__ 1881*e4b17023SJohn MarinoThis macro expands to a string constant that describes the time at 1882*e4b17023SJohn Marinowhich the preprocessor is being run. The string constant contains 1883*e4b17023SJohn Marinoeight characters and looks like @code{"23:59:01"}. 1884*e4b17023SJohn Marino 1885*e4b17023SJohn MarinoIf GCC cannot determine the current time, it will emit a warning message 1886*e4b17023SJohn Marino(once per compilation) and @code{__TIME__} will expand to 1887*e4b17023SJohn Marino@code{"??:??:??"}. 1888*e4b17023SJohn Marino 1889*e4b17023SJohn Marino@item __STDC__ 1890*e4b17023SJohn MarinoIn normal operation, this macro expands to the constant 1, to signify 1891*e4b17023SJohn Marinothat this compiler conforms to ISO Standard C@. If GNU CPP is used with 1892*e4b17023SJohn Marinoa compiler other than GCC, this is not necessarily true; however, the 1893*e4b17023SJohn Marinopreprocessor always conforms to the standard unless the 1894*e4b17023SJohn Marino@option{-traditional-cpp} option is used. 1895*e4b17023SJohn Marino 1896*e4b17023SJohn MarinoThis macro is not defined if the @option{-traditional-cpp} option is used. 1897*e4b17023SJohn Marino 1898*e4b17023SJohn MarinoOn some hosts, the system compiler uses a different convention, where 1899*e4b17023SJohn Marino@code{__STDC__} is normally 0, but is 1 if the user specifies strict 1900*e4b17023SJohn Marinoconformance to the C Standard. CPP follows the host convention when 1901*e4b17023SJohn Marinoprocessing system header files, but when processing user files 1902*e4b17023SJohn Marino@code{__STDC__} is always 1. This has been reported to cause problems; 1903*e4b17023SJohn Marinofor instance, some versions of Solaris provide X Windows headers that 1904*e4b17023SJohn Marinoexpect @code{__STDC__} to be either undefined or 1. @xref{Invocation}. 1905*e4b17023SJohn Marino 1906*e4b17023SJohn Marino@item __STDC_VERSION__ 1907*e4b17023SJohn MarinoThis macro expands to the C Standard's version number, a long integer 1908*e4b17023SJohn Marinoconstant of the form @code{@var{yyyy}@var{mm}L} where @var{yyyy} and 1909*e4b17023SJohn Marino@var{mm} are the year and month of the Standard version. This signifies 1910*e4b17023SJohn Marinowhich version of the C Standard the compiler conforms to. Like 1911*e4b17023SJohn Marino@code{__STDC__}, this is not necessarily accurate for the entire 1912*e4b17023SJohn Marinoimplementation, unless GNU CPP is being used with GCC@. 1913*e4b17023SJohn Marino 1914*e4b17023SJohn MarinoThe value @code{199409L} signifies the 1989 C standard as amended in 1915*e4b17023SJohn Marino1994, which is the current default; the value @code{199901L} signifies 1916*e4b17023SJohn Marinothe 1999 revision of the C standard. Support for the 1999 revision is 1917*e4b17023SJohn Marinonot yet complete. 1918*e4b17023SJohn Marino 1919*e4b17023SJohn MarinoThis macro is not defined if the @option{-traditional-cpp} option is 1920*e4b17023SJohn Marinoused, nor when compiling C++ or Objective-C@. 1921*e4b17023SJohn Marino 1922*e4b17023SJohn Marino@item __STDC_HOSTED__ 1923*e4b17023SJohn MarinoThis macro is defined, with value 1, if the compiler's target is a 1924*e4b17023SJohn Marino@dfn{hosted environment}. A hosted environment has the complete 1925*e4b17023SJohn Marinofacilities of the standard C library available. 1926*e4b17023SJohn Marino 1927*e4b17023SJohn Marino@item __cplusplus 1928*e4b17023SJohn MarinoThis macro is defined when the C++ compiler is in use. You can use 1929*e4b17023SJohn Marino@code{__cplusplus} to test whether a header is compiled by a C compiler 1930*e4b17023SJohn Marinoor a C++ compiler. This macro is similar to @code{__STDC_VERSION__}, in 1931*e4b17023SJohn Marinothat it expands to a version number. A fully conforming implementation 1932*e4b17023SJohn Marinoof the 1998 C++ standard will define this macro to @code{199711L}. The 1933*e4b17023SJohn MarinoGNU C++ compiler is not yet fully conforming, so it uses @code{1} 1934*e4b17023SJohn Marinoinstead. It is hoped to complete the implementation of standard C++ 1935*e4b17023SJohn Marinoin the near future. 1936*e4b17023SJohn Marino 1937*e4b17023SJohn Marino@item __OBJC__ 1938*e4b17023SJohn MarinoThis macro is defined, with value 1, when the Objective-C compiler is in 1939*e4b17023SJohn Marinouse. You can use @code{__OBJC__} to test whether a header is compiled 1940*e4b17023SJohn Marinoby a C compiler or an Objective-C compiler. 1941*e4b17023SJohn Marino 1942*e4b17023SJohn Marino@item __ASSEMBLER__ 1943*e4b17023SJohn MarinoThis macro is defined with value 1 when preprocessing assembly 1944*e4b17023SJohn Marinolanguage. 1945*e4b17023SJohn Marino 1946*e4b17023SJohn Marino@end table 1947*e4b17023SJohn Marino 1948*e4b17023SJohn Marino@node Common Predefined Macros 1949*e4b17023SJohn Marino@subsection Common Predefined Macros 1950*e4b17023SJohn Marino@cindex common predefined macros 1951*e4b17023SJohn Marino 1952*e4b17023SJohn MarinoThe common predefined macros are GNU C extensions. They are available 1953*e4b17023SJohn Marinowith the same meanings regardless of the machine or operating system on 1954*e4b17023SJohn Marinowhich you are using GNU C or GNU Fortran. Their names all start with 1955*e4b17023SJohn Marinodouble underscores. 1956*e4b17023SJohn Marino 1957*e4b17023SJohn Marino@table @code 1958*e4b17023SJohn Marino 1959*e4b17023SJohn Marino@item __COUNTER__ 1960*e4b17023SJohn MarinoThis macro expands to sequential integral values starting from 0. In 1961*e4b17023SJohn Marinoconjunction with the @code{##} operator, this provides a convenient means to 1962*e4b17023SJohn Marinogenerate unique identifiers. Care must be taken to ensure that 1963*e4b17023SJohn Marino@code{__COUNTER__} is not expanded prior to inclusion of precompiled headers 1964*e4b17023SJohn Marinowhich use it. Otherwise, the precompiled headers will not be used. 1965*e4b17023SJohn Marino 1966*e4b17023SJohn Marino@item __GFORTRAN__ 1967*e4b17023SJohn MarinoThe GNU Fortran compiler defines this. 1968*e4b17023SJohn Marino 1969*e4b17023SJohn Marino@item __GNUC__ 1970*e4b17023SJohn Marino@itemx __GNUC_MINOR__ 1971*e4b17023SJohn Marino@itemx __GNUC_PATCHLEVEL__ 1972*e4b17023SJohn MarinoThese macros are defined by all GNU compilers that use the C 1973*e4b17023SJohn Marinopreprocessor: C, C++, Objective-C and Fortran. Their values are the major 1974*e4b17023SJohn Marinoversion, minor version, and patch level of the compiler, as integer 1975*e4b17023SJohn Marinoconstants. For example, GCC 3.2.1 will define @code{__GNUC__} to 3, 1976*e4b17023SJohn Marino@code{__GNUC_MINOR__} to 2, and @code{__GNUC_PATCHLEVEL__} to 1. These 1977*e4b17023SJohn Marinomacros are also defined if you invoke the preprocessor directly. 1978*e4b17023SJohn Marino 1979*e4b17023SJohn Marino@code{__GNUC_PATCHLEVEL__} is new to GCC 3.0; it is also present in the 1980*e4b17023SJohn Marinowidely-used development snapshots leading up to 3.0 (which identify 1981*e4b17023SJohn Marinothemselves as GCC 2.96 or 2.97, depending on which snapshot you have). 1982*e4b17023SJohn Marino 1983*e4b17023SJohn MarinoIf all you need to know is whether or not your program is being compiled 1984*e4b17023SJohn Marinoby GCC, or a non-GCC compiler that claims to accept the GNU C dialects, 1985*e4b17023SJohn Marinoyou can simply test @code{__GNUC__}. If you need to write code 1986*e4b17023SJohn Marinowhich depends on a specific version, you must be more careful. Each 1987*e4b17023SJohn Marinotime the minor version is increased, the patch level is reset to zero; 1988*e4b17023SJohn Marinoeach time the major version is increased (which happens rarely), the 1989*e4b17023SJohn Marinominor version and patch level are reset. If you wish to use the 1990*e4b17023SJohn Marinopredefined macros directly in the conditional, you will need to write it 1991*e4b17023SJohn Marinolike this: 1992*e4b17023SJohn Marino 1993*e4b17023SJohn Marino@smallexample 1994*e4b17023SJohn Marino/* @r{Test for GCC > 3.2.0} */ 1995*e4b17023SJohn Marino#if __GNUC__ > 3 || \ 1996*e4b17023SJohn Marino (__GNUC__ == 3 && (__GNUC_MINOR__ > 2 || \ 1997*e4b17023SJohn Marino (__GNUC_MINOR__ == 2 && \ 1998*e4b17023SJohn Marino __GNUC_PATCHLEVEL__ > 0)) 1999*e4b17023SJohn Marino@end smallexample 2000*e4b17023SJohn Marino 2001*e4b17023SJohn Marino@noindent 2002*e4b17023SJohn MarinoAnother approach is to use the predefined macros to 2003*e4b17023SJohn Marinocalculate a single number, then compare that against a threshold: 2004*e4b17023SJohn Marino 2005*e4b17023SJohn Marino@smallexample 2006*e4b17023SJohn Marino#define GCC_VERSION (__GNUC__ * 10000 \ 2007*e4b17023SJohn Marino + __GNUC_MINOR__ * 100 \ 2008*e4b17023SJohn Marino + __GNUC_PATCHLEVEL__) 2009*e4b17023SJohn Marino@dots{} 2010*e4b17023SJohn Marino/* @r{Test for GCC > 3.2.0} */ 2011*e4b17023SJohn Marino#if GCC_VERSION > 30200 2012*e4b17023SJohn Marino@end smallexample 2013*e4b17023SJohn Marino 2014*e4b17023SJohn Marino@noindent 2015*e4b17023SJohn MarinoMany people find this form easier to understand. 2016*e4b17023SJohn Marino 2017*e4b17023SJohn Marino@item __GNUG__ 2018*e4b17023SJohn MarinoThe GNU C++ compiler defines this. Testing it is equivalent to 2019*e4b17023SJohn Marinotesting @code{@w{(__GNUC__ && __cplusplus)}}. 2020*e4b17023SJohn Marino 2021*e4b17023SJohn Marino@item __STRICT_ANSI__ 2022*e4b17023SJohn MarinoGCC defines this macro if and only if the @option{-ansi} switch, or a 2023*e4b17023SJohn Marino@option{-std} switch specifying strict conformance to some version of ISO C 2024*e4b17023SJohn Marinoor ISO C++, was specified when GCC was invoked. It is defined to @samp{1}. 2025*e4b17023SJohn MarinoThis macro exists primarily to direct GNU libc's header files to 2026*e4b17023SJohn Marinorestrict their definitions to the minimal set found in the 1989 C 2027*e4b17023SJohn Marinostandard. 2028*e4b17023SJohn Marino 2029*e4b17023SJohn Marino@item __BASE_FILE__ 2030*e4b17023SJohn MarinoThis macro expands to the name of the main input file, in the form 2031*e4b17023SJohn Marinoof a C string constant. This is the source file that was specified 2032*e4b17023SJohn Marinoon the command line of the preprocessor or C compiler. 2033*e4b17023SJohn Marino 2034*e4b17023SJohn Marino@item __INCLUDE_LEVEL__ 2035*e4b17023SJohn MarinoThis macro expands to a decimal integer constant that represents the 2036*e4b17023SJohn Marinodepth of nesting in include files. The value of this macro is 2037*e4b17023SJohn Marinoincremented on every @samp{#include} directive and decremented at the 2038*e4b17023SJohn Marinoend of every included file. It starts out at 0, its value within the 2039*e4b17023SJohn Marinobase file specified on the command line. 2040*e4b17023SJohn Marino 2041*e4b17023SJohn Marino@item __ELF__ 2042*e4b17023SJohn MarinoThis macro is defined if the target uses the ELF object format. 2043*e4b17023SJohn Marino 2044*e4b17023SJohn Marino@item __VERSION__ 2045*e4b17023SJohn MarinoThis macro expands to a string constant which describes the version of 2046*e4b17023SJohn Marinothe compiler in use. You should not rely on its contents having any 2047*e4b17023SJohn Marinoparticular form, but it can be counted on to contain at least the 2048*e4b17023SJohn Marinorelease number. 2049*e4b17023SJohn Marino 2050*e4b17023SJohn Marino@item __OPTIMIZE__ 2051*e4b17023SJohn Marino@itemx __OPTIMIZE_SIZE__ 2052*e4b17023SJohn Marino@itemx __NO_INLINE__ 2053*e4b17023SJohn MarinoThese macros describe the compilation mode. @code{__OPTIMIZE__} is 2054*e4b17023SJohn Marinodefined in all optimizing compilations. @code{__OPTIMIZE_SIZE__} is 2055*e4b17023SJohn Marinodefined if the compiler is optimizing for size, not speed. 2056*e4b17023SJohn Marino@code{__NO_INLINE__} is defined if no functions will be inlined into 2057*e4b17023SJohn Marinotheir callers (when not optimizing, or when inlining has been 2058*e4b17023SJohn Marinospecifically disabled by @option{-fno-inline}). 2059*e4b17023SJohn Marino 2060*e4b17023SJohn MarinoThese macros cause certain GNU header files to provide optimized 2061*e4b17023SJohn Marinodefinitions, using macros or inline functions, of system library 2062*e4b17023SJohn Marinofunctions. You should not use these macros in any way unless you make 2063*e4b17023SJohn Marinosure that programs will execute with the same effect whether or not they 2064*e4b17023SJohn Marinoare defined. If they are defined, their value is 1. 2065*e4b17023SJohn Marino 2066*e4b17023SJohn Marino@item __GNUC_GNU_INLINE__ 2067*e4b17023SJohn MarinoGCC defines this macro if functions declared @code{inline} will be 2068*e4b17023SJohn Marinohandled in GCC's traditional gnu90 mode. Object files will contain 2069*e4b17023SJohn Marinoexternally visible definitions of all functions declared @code{inline} 2070*e4b17023SJohn Marinowithout @code{extern} or @code{static}. They will not contain any 2071*e4b17023SJohn Marinodefinitions of any functions declared @code{extern inline}. 2072*e4b17023SJohn Marino 2073*e4b17023SJohn Marino@item __GNUC_STDC_INLINE__ 2074*e4b17023SJohn MarinoGCC defines this macro if functions declared @code{inline} will be 2075*e4b17023SJohn Marinohandled according to the ISO C99 standard. Object files will contain 2076*e4b17023SJohn Marinoexternally visible definitions of all functions declared @code{extern 2077*e4b17023SJohn Marinoinline}. They will not contain definitions of any functions declared 2078*e4b17023SJohn Marino@code{inline} without @code{extern}. 2079*e4b17023SJohn Marino 2080*e4b17023SJohn MarinoIf this macro is defined, GCC supports the @code{gnu_inline} function 2081*e4b17023SJohn Marinoattribute as a way to always get the gnu90 behavior. Support for 2082*e4b17023SJohn Marinothis and @code{__GNUC_GNU_INLINE__} was added in GCC 4.1.3. If 2083*e4b17023SJohn Marinoneither macro is defined, an older version of GCC is being used: 2084*e4b17023SJohn Marino@code{inline} functions will be compiled in gnu90 mode, and the 2085*e4b17023SJohn Marino@code{gnu_inline} function attribute will not be recognized. 2086*e4b17023SJohn Marino 2087*e4b17023SJohn Marino@item __CHAR_UNSIGNED__ 2088*e4b17023SJohn MarinoGCC defines this macro if and only if the data type @code{char} is 2089*e4b17023SJohn Marinounsigned on the target machine. It exists to cause the standard header 2090*e4b17023SJohn Marinofile @file{limits.h} to work correctly. You should not use this macro 2091*e4b17023SJohn Marinoyourself; instead, refer to the standard macros defined in @file{limits.h}. 2092*e4b17023SJohn Marino 2093*e4b17023SJohn Marino@item __WCHAR_UNSIGNED__ 2094*e4b17023SJohn MarinoLike @code{__CHAR_UNSIGNED__}, this macro is defined if and only if the 2095*e4b17023SJohn Marinodata type @code{wchar_t} is unsigned and the front-end is in C++ mode. 2096*e4b17023SJohn Marino 2097*e4b17023SJohn Marino@item __REGISTER_PREFIX__ 2098*e4b17023SJohn MarinoThis macro expands to a single token (not a string constant) which is 2099*e4b17023SJohn Marinothe prefix applied to CPU register names in assembly language for this 2100*e4b17023SJohn Marinotarget. You can use it to write assembly that is usable in multiple 2101*e4b17023SJohn Marinoenvironments. For example, in the @code{m68k-aout} environment it 2102*e4b17023SJohn Marinoexpands to nothing, but in the @code{m68k-coff} environment it expands 2103*e4b17023SJohn Marinoto a single @samp{%}. 2104*e4b17023SJohn Marino 2105*e4b17023SJohn Marino@item __USER_LABEL_PREFIX__ 2106*e4b17023SJohn MarinoThis macro expands to a single token which is the prefix applied to 2107*e4b17023SJohn Marinouser labels (symbols visible to C code) in assembly. For example, in 2108*e4b17023SJohn Marinothe @code{m68k-aout} environment it expands to an @samp{_}, but in the 2109*e4b17023SJohn Marino@code{m68k-coff} environment it expands to nothing. 2110*e4b17023SJohn Marino 2111*e4b17023SJohn MarinoThis macro will have the correct definition even if 2112*e4b17023SJohn Marino@option{-f(no-)underscores} is in use, but it will not be correct if 2113*e4b17023SJohn Marinotarget-specific options that adjust this prefix are used (e.g.@: the 2114*e4b17023SJohn MarinoOSF/rose @option{-mno-underscores} option). 2115*e4b17023SJohn Marino 2116*e4b17023SJohn Marino@item __SIZE_TYPE__ 2117*e4b17023SJohn Marino@itemx __PTRDIFF_TYPE__ 2118*e4b17023SJohn Marino@itemx __WCHAR_TYPE__ 2119*e4b17023SJohn Marino@itemx __WINT_TYPE__ 2120*e4b17023SJohn Marino@itemx __INTMAX_TYPE__ 2121*e4b17023SJohn Marino@itemx __UINTMAX_TYPE__ 2122*e4b17023SJohn Marino@itemx __SIG_ATOMIC_TYPE__ 2123*e4b17023SJohn Marino@itemx __INT8_TYPE__ 2124*e4b17023SJohn Marino@itemx __INT16_TYPE__ 2125*e4b17023SJohn Marino@itemx __INT32_TYPE__ 2126*e4b17023SJohn Marino@itemx __INT64_TYPE__ 2127*e4b17023SJohn Marino@itemx __UINT8_TYPE__ 2128*e4b17023SJohn Marino@itemx __UINT16_TYPE__ 2129*e4b17023SJohn Marino@itemx __UINT32_TYPE__ 2130*e4b17023SJohn Marino@itemx __UINT64_TYPE__ 2131*e4b17023SJohn Marino@itemx __INT_LEAST8_TYPE__ 2132*e4b17023SJohn Marino@itemx __INT_LEAST16_TYPE__ 2133*e4b17023SJohn Marino@itemx __INT_LEAST32_TYPE__ 2134*e4b17023SJohn Marino@itemx __INT_LEAST64_TYPE__ 2135*e4b17023SJohn Marino@itemx __UINT_LEAST8_TYPE__ 2136*e4b17023SJohn Marino@itemx __UINT_LEAST16_TYPE__ 2137*e4b17023SJohn Marino@itemx __UINT_LEAST32_TYPE__ 2138*e4b17023SJohn Marino@itemx __UINT_LEAST64_TYPE__ 2139*e4b17023SJohn Marino@itemx __INT_FAST8_TYPE__ 2140*e4b17023SJohn Marino@itemx __INT_FAST16_TYPE__ 2141*e4b17023SJohn Marino@itemx __INT_FAST32_TYPE__ 2142*e4b17023SJohn Marino@itemx __INT_FAST64_TYPE__ 2143*e4b17023SJohn Marino@itemx __UINT_FAST8_TYPE__ 2144*e4b17023SJohn Marino@itemx __UINT_FAST16_TYPE__ 2145*e4b17023SJohn Marino@itemx __UINT_FAST32_TYPE__ 2146*e4b17023SJohn Marino@itemx __UINT_FAST64_TYPE__ 2147*e4b17023SJohn Marino@itemx __INTPTR_TYPE__ 2148*e4b17023SJohn Marino@itemx __UINTPTR_TYPE__ 2149*e4b17023SJohn MarinoThese macros are defined to the correct underlying types for the 2150*e4b17023SJohn Marino@code{size_t}, @code{ptrdiff_t}, @code{wchar_t}, @code{wint_t}, 2151*e4b17023SJohn Marino@code{intmax_t}, @code{uintmax_t}, @code{sig_atomic_t}, @code{int8_t}, 2152*e4b17023SJohn Marino@code{int16_t}, @code{int32_t}, @code{int64_t}, @code{uint8_t}, 2153*e4b17023SJohn Marino@code{uint16_t}, @code{uint32_t}, @code{uint64_t}, 2154*e4b17023SJohn Marino@code{int_least8_t}, @code{int_least16_t}, @code{int_least32_t}, 2155*e4b17023SJohn Marino@code{int_least64_t}, @code{uint_least8_t}, @code{uint_least16_t}, 2156*e4b17023SJohn Marino@code{uint_least32_t}, @code{uint_least64_t}, @code{int_fast8_t}, 2157*e4b17023SJohn Marino@code{int_fast16_t}, @code{int_fast32_t}, @code{int_fast64_t}, 2158*e4b17023SJohn Marino@code{uint_fast8_t}, @code{uint_fast16_t}, @code{uint_fast32_t}, 2159*e4b17023SJohn Marino@code{uint_fast64_t}, @code{intptr_t}, and @code{uintptr_t} typedefs, 2160*e4b17023SJohn Marinorespectively. They exist to make the standard header files 2161*e4b17023SJohn Marino@file{stddef.h}, @file{stdint.h}, and @file{wchar.h} work correctly. 2162*e4b17023SJohn MarinoYou should not use these macros directly; instead, include the 2163*e4b17023SJohn Marinoappropriate headers and use the typedefs. Some of these macros may 2164*e4b17023SJohn Marinonot be defined on particular systems if GCC does not provide a 2165*e4b17023SJohn Marino@file{stdint.h} header on those systems. 2166*e4b17023SJohn Marino 2167*e4b17023SJohn Marino@item __CHAR_BIT__ 2168*e4b17023SJohn MarinoDefined to the number of bits used in the representation of the 2169*e4b17023SJohn Marino@code{char} data type. It exists to make the standard header given 2170*e4b17023SJohn Marinonumerical limits work correctly. You should not use 2171*e4b17023SJohn Marinothis macro directly; instead, include the appropriate headers. 2172*e4b17023SJohn Marino 2173*e4b17023SJohn Marino@item __SCHAR_MAX__ 2174*e4b17023SJohn Marino@itemx __WCHAR_MAX__ 2175*e4b17023SJohn Marino@itemx __SHRT_MAX__ 2176*e4b17023SJohn Marino@itemx __INT_MAX__ 2177*e4b17023SJohn Marino@itemx __LONG_MAX__ 2178*e4b17023SJohn Marino@itemx __LONG_LONG_MAX__ 2179*e4b17023SJohn Marino@itemx __WINT_MAX__ 2180*e4b17023SJohn Marino@itemx __SIZE_MAX__ 2181*e4b17023SJohn Marino@itemx __PTRDIFF_MAX__ 2182*e4b17023SJohn Marino@itemx __INTMAX_MAX__ 2183*e4b17023SJohn Marino@itemx __UINTMAX_MAX__ 2184*e4b17023SJohn Marino@itemx __SIG_ATOMIC_MAX__ 2185*e4b17023SJohn Marino@itemx __INT8_MAX__ 2186*e4b17023SJohn Marino@itemx __INT16_MAX__ 2187*e4b17023SJohn Marino@itemx __INT32_MAX__ 2188*e4b17023SJohn Marino@itemx __INT64_MAX__ 2189*e4b17023SJohn Marino@itemx __UINT8_MAX__ 2190*e4b17023SJohn Marino@itemx __UINT16_MAX__ 2191*e4b17023SJohn Marino@itemx __UINT32_MAX__ 2192*e4b17023SJohn Marino@itemx __UINT64_MAX__ 2193*e4b17023SJohn Marino@itemx __INT_LEAST8_MAX__ 2194*e4b17023SJohn Marino@itemx __INT_LEAST16_MAX__ 2195*e4b17023SJohn Marino@itemx __INT_LEAST32_MAX__ 2196*e4b17023SJohn Marino@itemx __INT_LEAST64_MAX__ 2197*e4b17023SJohn Marino@itemx __UINT_LEAST8_MAX__ 2198*e4b17023SJohn Marino@itemx __UINT_LEAST16_MAX__ 2199*e4b17023SJohn Marino@itemx __UINT_LEAST32_MAX__ 2200*e4b17023SJohn Marino@itemx __UINT_LEAST64_MAX__ 2201*e4b17023SJohn Marino@itemx __INT_FAST8_MAX__ 2202*e4b17023SJohn Marino@itemx __INT_FAST16_MAX__ 2203*e4b17023SJohn Marino@itemx __INT_FAST32_MAX__ 2204*e4b17023SJohn Marino@itemx __INT_FAST64_MAX__ 2205*e4b17023SJohn Marino@itemx __UINT_FAST8_MAX__ 2206*e4b17023SJohn Marino@itemx __UINT_FAST16_MAX__ 2207*e4b17023SJohn Marino@itemx __UINT_FAST32_MAX__ 2208*e4b17023SJohn Marino@itemx __UINT_FAST64_MAX__ 2209*e4b17023SJohn Marino@itemx __INTPTR_MAX__ 2210*e4b17023SJohn Marino@itemx __UINTPTR_MAX__ 2211*e4b17023SJohn Marino@itemx __WCHAR_MIN__ 2212*e4b17023SJohn Marino@itemx __WINT_MIN__ 2213*e4b17023SJohn Marino@itemx __SIG_ATOMIC_MIN__ 2214*e4b17023SJohn MarinoDefined to the maximum value of the @code{signed char}, @code{wchar_t}, 2215*e4b17023SJohn Marino@code{signed short}, 2216*e4b17023SJohn Marino@code{signed int}, @code{signed long}, @code{signed long long}, 2217*e4b17023SJohn Marino@code{wint_t}, @code{size_t}, @code{ptrdiff_t}, 2218*e4b17023SJohn Marino@code{intmax_t}, @code{uintmax_t}, @code{sig_atomic_t}, @code{int8_t}, 2219*e4b17023SJohn Marino@code{int16_t}, @code{int32_t}, @code{int64_t}, @code{uint8_t}, 2220*e4b17023SJohn Marino@code{uint16_t}, @code{uint32_t}, @code{uint64_t}, 2221*e4b17023SJohn Marino@code{int_least8_t}, @code{int_least16_t}, @code{int_least32_t}, 2222*e4b17023SJohn Marino@code{int_least64_t}, @code{uint_least8_t}, @code{uint_least16_t}, 2223*e4b17023SJohn Marino@code{uint_least32_t}, @code{uint_least64_t}, @code{int_fast8_t}, 2224*e4b17023SJohn Marino@code{int_fast16_t}, @code{int_fast32_t}, @code{int_fast64_t}, 2225*e4b17023SJohn Marino@code{uint_fast8_t}, @code{uint_fast16_t}, @code{uint_fast32_t}, 2226*e4b17023SJohn Marino@code{uint_fast64_t}, @code{intptr_t}, and @code{uintptr_t} types and 2227*e4b17023SJohn Marinoto the minimum value of the @code{wchar_t}, @code{wint_t}, and 2228*e4b17023SJohn Marino@code{sig_atomic_t} types respectively. They exist to make the 2229*e4b17023SJohn Marinostandard header given numerical limits work correctly. You should not 2230*e4b17023SJohn Marinouse these macros directly; instead, include the appropriate headers. 2231*e4b17023SJohn MarinoSome of these macros may not be defined on particular systems if GCC 2232*e4b17023SJohn Marinodoes not provide a @file{stdint.h} header on those systems. 2233*e4b17023SJohn Marino 2234*e4b17023SJohn Marino@item __INT8_C 2235*e4b17023SJohn Marino@itemx __INT16_C 2236*e4b17023SJohn Marino@itemx __INT32_C 2237*e4b17023SJohn Marino@itemx __INT64_C 2238*e4b17023SJohn Marino@itemx __UINT8_C 2239*e4b17023SJohn Marino@itemx __UINT16_C 2240*e4b17023SJohn Marino@itemx __UINT32_C 2241*e4b17023SJohn Marino@itemx __UINT64_C 2242*e4b17023SJohn Marino@itemx __INTMAX_C 2243*e4b17023SJohn Marino@itemx __UINTMAX_C 2244*e4b17023SJohn MarinoDefined to implementations of the standard @file{stdint.h} macros with 2245*e4b17023SJohn Marinothe same names without the leading @code{__}. They exist the make the 2246*e4b17023SJohn Marinoimplementation of that header work correctly. You should not use 2247*e4b17023SJohn Marinothese macros directly; instead, include the appropriate headers. Some 2248*e4b17023SJohn Marinoof these macros may not be defined on particular systems if GCC does 2249*e4b17023SJohn Marinonot provide a @file{stdint.h} header on those systems. 2250*e4b17023SJohn Marino 2251*e4b17023SJohn Marino@item __SIZEOF_INT__ 2252*e4b17023SJohn Marino@itemx __SIZEOF_LONG__ 2253*e4b17023SJohn Marino@itemx __SIZEOF_LONG_LONG__ 2254*e4b17023SJohn Marino@itemx __SIZEOF_SHORT__ 2255*e4b17023SJohn Marino@itemx __SIZEOF_POINTER__ 2256*e4b17023SJohn Marino@itemx __SIZEOF_FLOAT__ 2257*e4b17023SJohn Marino@itemx __SIZEOF_DOUBLE__ 2258*e4b17023SJohn Marino@itemx __SIZEOF_LONG_DOUBLE__ 2259*e4b17023SJohn Marino@itemx __SIZEOF_SIZE_T__ 2260*e4b17023SJohn Marino@itemx __SIZEOF_WCHAR_T__ 2261*e4b17023SJohn Marino@itemx __SIZEOF_WINT_T__ 2262*e4b17023SJohn Marino@itemx __SIZEOF_PTRDIFF_T__ 2263*e4b17023SJohn MarinoDefined to the number of bytes of the C standard data types: @code{int}, 2264*e4b17023SJohn Marino@code{long}, @code{long long}, @code{short}, @code{void *}, @code{float}, 2265*e4b17023SJohn Marino@code{double}, @code{long double}, @code{size_t}, @code{wchar_t}, @code{wint_t} 2266*e4b17023SJohn Marinoand @code{ptrdiff_t}. 2267*e4b17023SJohn Marino 2268*e4b17023SJohn Marino@item __BYTE_ORDER__ 2269*e4b17023SJohn Marino@itemx __ORDER_LITTLE_ENDIAN__ 2270*e4b17023SJohn Marino@itemx __ORDER_BIG_ENDIAN__ 2271*e4b17023SJohn Marino@itemx __ORDER_PDP_ENDIAN__ 2272*e4b17023SJohn Marino@code{__BYTE_ORDER__} is defined to one of the values 2273*e4b17023SJohn Marino@code{__ORDER_LITTLE_ENDIAN__}, @code{__ORDER_BIG_ENDIAN__}, or 2274*e4b17023SJohn Marino@code{__ORDER_PDP_ENDIAN__} to reflect the layout of multi-byte and 2275*e4b17023SJohn Marinomulti-word quantities in memory. If @code{__BYTE_ORDER__} is equal to 2276*e4b17023SJohn Marino@code{__ORDER_LITTLE_ENDIAN__} or @code{__ORDER_BIG_ENDIAN__}, then 2277*e4b17023SJohn Marinomulti-byte and multi-word quantities are laid out identically: the 2278*e4b17023SJohn Marinobyte (word) at the lowest address is the least significant or most 2279*e4b17023SJohn Marinosignificant byte (word) of the quantity, respectively. If 2280*e4b17023SJohn Marino@code{__BYTE_ORDER__} is equal to @code{__ORDER_PDP_ENDIAN__}, then 2281*e4b17023SJohn Marinobytes in 16-bit words are laid out in a little-endian fashion, whereas 2282*e4b17023SJohn Marinothe 16-bit subwords of a 32-bit quantity are laid out in big-endian 2283*e4b17023SJohn Marinofashion. 2284*e4b17023SJohn Marino 2285*e4b17023SJohn MarinoYou should use these macros for testing like this: 2286*e4b17023SJohn Marino 2287*e4b17023SJohn Marino@smallexample 2288*e4b17023SJohn Marino/* @r{Test for a little-endian machine} */ 2289*e4b17023SJohn Marino#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__ 2290*e4b17023SJohn Marino@end smallexample 2291*e4b17023SJohn Marino 2292*e4b17023SJohn Marino@item __FLOAT_WORD_ORDER__ 2293*e4b17023SJohn Marino@code{__FLOAT_WORD_ORDER__} is defined to one of the values 2294*e4b17023SJohn Marino@code{__ORDER_LITTLE_ENDIAN__} or @code{__ORDER_BIG_ENDIAN__} to reflect 2295*e4b17023SJohn Marinothe layout of the words of multi-word floating-point quantities. 2296*e4b17023SJohn Marino 2297*e4b17023SJohn Marino@item __DEPRECATED 2298*e4b17023SJohn MarinoThis macro is defined, with value 1, when compiling a C++ source file 2299*e4b17023SJohn Marinowith warnings about deprecated constructs enabled. These warnings are 2300*e4b17023SJohn Marinoenabled by default, but can be disabled with @option{-Wno-deprecated}. 2301*e4b17023SJohn Marino 2302*e4b17023SJohn Marino@item __EXCEPTIONS 2303*e4b17023SJohn MarinoThis macro is defined, with value 1, when compiling a C++ source file 2304*e4b17023SJohn Marinowith exceptions enabled. If @option{-fno-exceptions} is used when 2305*e4b17023SJohn Marinocompiling the file, then this macro is not defined. 2306*e4b17023SJohn Marino 2307*e4b17023SJohn Marino@item __GXX_RTTI 2308*e4b17023SJohn MarinoThis macro is defined, with value 1, when compiling a C++ source file 2309*e4b17023SJohn Marinowith runtime type identification enabled. If @option{-fno-rtti} is 2310*e4b17023SJohn Marinoused when compiling the file, then this macro is not defined. 2311*e4b17023SJohn Marino 2312*e4b17023SJohn Marino@item __USING_SJLJ_EXCEPTIONS__ 2313*e4b17023SJohn MarinoThis macro is defined, with value 1, if the compiler uses the old 2314*e4b17023SJohn Marinomechanism based on @code{setjmp} and @code{longjmp} for exception 2315*e4b17023SJohn Marinohandling. 2316*e4b17023SJohn Marino 2317*e4b17023SJohn Marino@item __GXX_EXPERIMENTAL_CXX0X__ 2318*e4b17023SJohn MarinoThis macro is defined when compiling a C++ source file with the option 2319*e4b17023SJohn Marino@option{-std=c++0x} or @option{-std=gnu++0x}. It indicates that some 2320*e4b17023SJohn Marinofeatures likely to be included in C++0x are available. Note that these 2321*e4b17023SJohn Marinofeatures are experimental, and may change or be removed in future 2322*e4b17023SJohn Marinoversions of GCC. 2323*e4b17023SJohn Marino 2324*e4b17023SJohn Marino@item __GXX_WEAK__ 2325*e4b17023SJohn MarinoThis macro is defined when compiling a C++ source file. It has the 2326*e4b17023SJohn Marinovalue 1 if the compiler will use weak symbols, COMDAT sections, or 2327*e4b17023SJohn Marinoother similar techniques to collapse symbols with ``vague linkage'' 2328*e4b17023SJohn Marinothat are defined in multiple translation units. If the compiler will 2329*e4b17023SJohn Marinonot collapse such symbols, this macro is defined with value 0. In 2330*e4b17023SJohn Marinogeneral, user code should not need to make use of this macro; the 2331*e4b17023SJohn Marinopurpose of this macro is to ease implementation of the C++ runtime 2332*e4b17023SJohn Marinolibrary provided with G++. 2333*e4b17023SJohn Marino 2334*e4b17023SJohn Marino@item __NEXT_RUNTIME__ 2335*e4b17023SJohn MarinoThis macro is defined, with value 1, if (and only if) the NeXT runtime 2336*e4b17023SJohn Marino(as in @option{-fnext-runtime}) is in use for Objective-C@. If the GNU 2337*e4b17023SJohn Marinoruntime is used, this macro is not defined, so that you can use this 2338*e4b17023SJohn Marinomacro to determine which runtime (NeXT or GNU) is being used. 2339*e4b17023SJohn Marino 2340*e4b17023SJohn Marino@item __LP64__ 2341*e4b17023SJohn Marino@itemx _LP64 2342*e4b17023SJohn MarinoThese macros are defined, with value 1, if (and only if) the compilation 2343*e4b17023SJohn Marinois for a target where @code{long int} and pointer both use 64-bits and 2344*e4b17023SJohn Marino@code{int} uses 32-bit. 2345*e4b17023SJohn Marino 2346*e4b17023SJohn Marino@item __SSP__ 2347*e4b17023SJohn MarinoThis macro is defined, with value 1, when @option{-fstack-protector} is in 2348*e4b17023SJohn Marinouse. 2349*e4b17023SJohn Marino 2350*e4b17023SJohn Marino@item __SSP_ALL__ 2351*e4b17023SJohn MarinoThis macro is defined, with value 2, when @option{-fstack-protector-all} is 2352*e4b17023SJohn Marinoin use. 2353*e4b17023SJohn Marino 2354*e4b17023SJohn Marino@item __TIMESTAMP__ 2355*e4b17023SJohn MarinoThis macro expands to a string constant that describes the date and time 2356*e4b17023SJohn Marinoof the last modification of the current source file. The string constant 2357*e4b17023SJohn Marinocontains abbreviated day of the week, month, day of the month, time in 2358*e4b17023SJohn Marinohh:mm:ss form, year and looks like @code{@w{"Sun Sep 16 01:03:52 1973"}}. 2359*e4b17023SJohn MarinoIf the day of the month is less than 10, it is padded with a space on the left. 2360*e4b17023SJohn Marino 2361*e4b17023SJohn MarinoIf GCC cannot determine the current date, it will emit a warning message 2362*e4b17023SJohn Marino(once per compilation) and @code{__TIMESTAMP__} will expand to 2363*e4b17023SJohn Marino@code{@w{"??? ??? ?? ??:??:?? ????"}}. 2364*e4b17023SJohn Marino 2365*e4b17023SJohn Marino@item __GCC_HAVE_SYNC_COMPARE_AND_SWAP_1 2366*e4b17023SJohn Marino@itemx __GCC_HAVE_SYNC_COMPARE_AND_SWAP_2 2367*e4b17023SJohn Marino@itemx __GCC_HAVE_SYNC_COMPARE_AND_SWAP_4 2368*e4b17023SJohn Marino@itemx __GCC_HAVE_SYNC_COMPARE_AND_SWAP_8 2369*e4b17023SJohn Marino@itemx __GCC_HAVE_SYNC_COMPARE_AND_SWAP_16 2370*e4b17023SJohn MarinoThese macros are defined when the target processor supports atomic compare 2371*e4b17023SJohn Marinoand swap operations on operands 1, 2, 4, 8 or 16 bytes in length, respectively. 2372*e4b17023SJohn Marino 2373*e4b17023SJohn Marino@item __GCC_HAVE_DWARF2_CFI_ASM 2374*e4b17023SJohn MarinoThis macro is defined when the compiler is emitting Dwarf2 CFI directives 2375*e4b17023SJohn Marinoto the assembler. When this is defined, it is possible to emit those same 2376*e4b17023SJohn Marinodirectives in inline assembly. 2377*e4b17023SJohn Marino 2378*e4b17023SJohn Marino@item __FP_FAST_FMA 2379*e4b17023SJohn Marino@itemx __FP_FAST_FMAF 2380*e4b17023SJohn Marino@itemx __FP_FAST_FMAL 2381*e4b17023SJohn MarinoThese macros are defined with value 1 if the backend supports the 2382*e4b17023SJohn Marino@code{fma}, @code{fmaf}, and @code{fmal} builtin functions, so that 2383*e4b17023SJohn Marinothe include file @file{math.h} can define the macros 2384*e4b17023SJohn Marino@code{FP_FAST_FMA}, @code{FP_FAST_FMAF}, and @code{FP_FAST_FMAL} 2385*e4b17023SJohn Marinofor compatibility with the 1999 C standard. 2386*e4b17023SJohn Marino@end table 2387*e4b17023SJohn Marino 2388*e4b17023SJohn Marino@node System-specific Predefined Macros 2389*e4b17023SJohn Marino@subsection System-specific Predefined Macros 2390*e4b17023SJohn Marino 2391*e4b17023SJohn Marino@cindex system-specific predefined macros 2392*e4b17023SJohn Marino@cindex predefined macros, system-specific 2393*e4b17023SJohn Marino@cindex reserved namespace 2394*e4b17023SJohn Marino 2395*e4b17023SJohn MarinoThe C preprocessor normally predefines several macros that indicate what 2396*e4b17023SJohn Marinotype of system and machine is in use. They are obviously different on 2397*e4b17023SJohn Marinoeach target supported by GCC@. This manual, being for all systems and 2398*e4b17023SJohn Marinomachines, cannot tell you what their names are, but you can use 2399*e4b17023SJohn Marino@command{cpp -dM} to see them all. @xref{Invocation}. All system-specific 2400*e4b17023SJohn Marinopredefined macros expand to the constant 1, so you can test them with 2401*e4b17023SJohn Marinoeither @samp{#ifdef} or @samp{#if}. 2402*e4b17023SJohn Marino 2403*e4b17023SJohn MarinoThe C standard requires that all system-specific macros be part of the 2404*e4b17023SJohn Marino@dfn{reserved namespace}. All names which begin with two underscores, 2405*e4b17023SJohn Marinoor an underscore and a capital letter, are reserved for the compiler and 2406*e4b17023SJohn Marinolibrary to use as they wish. However, historically system-specific 2407*e4b17023SJohn Marinomacros have had names with no special prefix; for instance, it is common 2408*e4b17023SJohn Marinoto find @code{unix} defined on Unix systems. For all such macros, GCC 2409*e4b17023SJohn Marinoprovides a parallel macro with two underscores added at the beginning 2410*e4b17023SJohn Marinoand the end. If @code{unix} is defined, @code{__unix__} will be defined 2411*e4b17023SJohn Marinotoo. There will never be more than two underscores; the parallel of 2412*e4b17023SJohn Marino@code{_mips} is @code{__mips__}. 2413*e4b17023SJohn Marino 2414*e4b17023SJohn MarinoWhen the @option{-ansi} option, or any @option{-std} option that 2415*e4b17023SJohn Marinorequests strict conformance, is given to the compiler, all the 2416*e4b17023SJohn Marinosystem-specific predefined macros outside the reserved namespace are 2417*e4b17023SJohn Marinosuppressed. The parallel macros, inside the reserved namespace, remain 2418*e4b17023SJohn Marinodefined. 2419*e4b17023SJohn Marino 2420*e4b17023SJohn MarinoWe are slowly phasing out all predefined macros which are outside the 2421*e4b17023SJohn Marinoreserved namespace. You should never use them in new programs, and we 2422*e4b17023SJohn Marinoencourage you to correct older code to use the parallel macros whenever 2423*e4b17023SJohn Marinoyou find it. We don't recommend you use the system-specific macros that 2424*e4b17023SJohn Marinoare in the reserved namespace, either. It is better in the long run to 2425*e4b17023SJohn Marinocheck specifically for features you need, using a tool such as 2426*e4b17023SJohn Marino@command{autoconf}. 2427*e4b17023SJohn Marino 2428*e4b17023SJohn Marino@node C++ Named Operators 2429*e4b17023SJohn Marino@subsection C++ Named Operators 2430*e4b17023SJohn Marino@cindex named operators 2431*e4b17023SJohn Marino@cindex C++ named operators 2432*e4b17023SJohn Marino@cindex @file{iso646.h} 2433*e4b17023SJohn Marino 2434*e4b17023SJohn MarinoIn C++, there are eleven keywords which are simply alternate spellings 2435*e4b17023SJohn Marinoof operators normally written with punctuation. These keywords are 2436*e4b17023SJohn Marinotreated as such even in the preprocessor. They function as operators in 2437*e4b17023SJohn Marino@samp{#if}, and they cannot be defined as macros or poisoned. In C, you 2438*e4b17023SJohn Marinocan request that those keywords take their C++ meaning by including 2439*e4b17023SJohn Marino@file{iso646.h}. That header defines each one as a normal object-like 2440*e4b17023SJohn Marinomacro expanding to the appropriate punctuator. 2441*e4b17023SJohn Marino 2442*e4b17023SJohn MarinoThese are the named operators and their corresponding punctuators: 2443*e4b17023SJohn Marino 2444*e4b17023SJohn Marino@multitable {Named Operator} {Punctuator} 2445*e4b17023SJohn Marino@item Named Operator @tab Punctuator 2446*e4b17023SJohn Marino@item @code{and} @tab @code{&&} 2447*e4b17023SJohn Marino@item @code{and_eq} @tab @code{&=} 2448*e4b17023SJohn Marino@item @code{bitand} @tab @code{&} 2449*e4b17023SJohn Marino@item @code{bitor} @tab @code{|} 2450*e4b17023SJohn Marino@item @code{compl} @tab @code{~} 2451*e4b17023SJohn Marino@item @code{not} @tab @code{!} 2452*e4b17023SJohn Marino@item @code{not_eq} @tab @code{!=} 2453*e4b17023SJohn Marino@item @code{or} @tab @code{||} 2454*e4b17023SJohn Marino@item @code{or_eq} @tab @code{|=} 2455*e4b17023SJohn Marino@item @code{xor} @tab @code{^} 2456*e4b17023SJohn Marino@item @code{xor_eq} @tab @code{^=} 2457*e4b17023SJohn Marino@end multitable 2458*e4b17023SJohn Marino 2459*e4b17023SJohn Marino@node Undefining and Redefining Macros 2460*e4b17023SJohn Marino@section Undefining and Redefining Macros 2461*e4b17023SJohn Marino@cindex undefining macros 2462*e4b17023SJohn Marino@cindex redefining macros 2463*e4b17023SJohn Marino@findex #undef 2464*e4b17023SJohn Marino 2465*e4b17023SJohn MarinoIf a macro ceases to be useful, it may be @dfn{undefined} with the 2466*e4b17023SJohn Marino@samp{#undef} directive. @samp{#undef} takes a single argument, the 2467*e4b17023SJohn Marinoname of the macro to undefine. You use the bare macro name, even if the 2468*e4b17023SJohn Marinomacro is function-like. It is an error if anything appears on the line 2469*e4b17023SJohn Marinoafter the macro name. @samp{#undef} has no effect if the name is not a 2470*e4b17023SJohn Marinomacro. 2471*e4b17023SJohn Marino 2472*e4b17023SJohn Marino@smallexample 2473*e4b17023SJohn Marino#define FOO 4 2474*e4b17023SJohn Marinox = FOO; @expansion{} x = 4; 2475*e4b17023SJohn Marino#undef FOO 2476*e4b17023SJohn Marinox = FOO; @expansion{} x = FOO; 2477*e4b17023SJohn Marino@end smallexample 2478*e4b17023SJohn Marino 2479*e4b17023SJohn MarinoOnce a macro has been undefined, that identifier may be @dfn{redefined} 2480*e4b17023SJohn Marinoas a macro by a subsequent @samp{#define} directive. The new definition 2481*e4b17023SJohn Marinoneed not have any resemblance to the old definition. 2482*e4b17023SJohn Marino 2483*e4b17023SJohn MarinoHowever, if an identifier which is currently a macro is redefined, then 2484*e4b17023SJohn Marinothe new definition must be @dfn{effectively the same} as the old one. 2485*e4b17023SJohn MarinoTwo macro definitions are effectively the same if: 2486*e4b17023SJohn Marino@itemize @bullet 2487*e4b17023SJohn Marino@item Both are the same type of macro (object- or function-like). 2488*e4b17023SJohn Marino@item All the tokens of the replacement list are the same. 2489*e4b17023SJohn Marino@item If there are any parameters, they are the same. 2490*e4b17023SJohn Marino@item Whitespace appears in the same places in both. It need not be 2491*e4b17023SJohn Marinoexactly the same amount of whitespace, though. Remember that comments 2492*e4b17023SJohn Marinocount as whitespace. 2493*e4b17023SJohn Marino@end itemize 2494*e4b17023SJohn Marino 2495*e4b17023SJohn Marino@noindent 2496*e4b17023SJohn MarinoThese definitions are effectively the same: 2497*e4b17023SJohn Marino@smallexample 2498*e4b17023SJohn Marino#define FOUR (2 + 2) 2499*e4b17023SJohn Marino#define FOUR (2 + 2) 2500*e4b17023SJohn Marino#define FOUR (2 /* @r{two} */ + 2) 2501*e4b17023SJohn Marino@end smallexample 2502*e4b17023SJohn Marino@noindent 2503*e4b17023SJohn Marinobut these are not: 2504*e4b17023SJohn Marino@smallexample 2505*e4b17023SJohn Marino#define FOUR (2 + 2) 2506*e4b17023SJohn Marino#define FOUR ( 2+2 ) 2507*e4b17023SJohn Marino#define FOUR (2 * 2) 2508*e4b17023SJohn Marino#define FOUR(score,and,seven,years,ago) (2 + 2) 2509*e4b17023SJohn Marino@end smallexample 2510*e4b17023SJohn Marino 2511*e4b17023SJohn MarinoIf a macro is redefined with a definition that is not effectively the 2512*e4b17023SJohn Marinosame as the old one, the preprocessor issues a warning and changes the 2513*e4b17023SJohn Marinomacro to use the new definition. If the new definition is effectively 2514*e4b17023SJohn Marinothe same, the redefinition is silently ignored. This allows, for 2515*e4b17023SJohn Marinoinstance, two different headers to define a common macro. The 2516*e4b17023SJohn Marinopreprocessor will only complain if the definitions do not match. 2517*e4b17023SJohn Marino 2518*e4b17023SJohn Marino@node Directives Within Macro Arguments 2519*e4b17023SJohn Marino@section Directives Within Macro Arguments 2520*e4b17023SJohn Marino@cindex macro arguments and directives 2521*e4b17023SJohn Marino 2522*e4b17023SJohn MarinoOccasionally it is convenient to use preprocessor directives within 2523*e4b17023SJohn Marinothe arguments of a macro. The C and C++ standards declare that 2524*e4b17023SJohn Marinobehavior in these cases is undefined. 2525*e4b17023SJohn Marino 2526*e4b17023SJohn MarinoVersions of CPP prior to 3.2 would reject such constructs with an 2527*e4b17023SJohn Marinoerror message. This was the only syntactic difference between normal 2528*e4b17023SJohn Marinofunctions and function-like macros, so it seemed attractive to remove 2529*e4b17023SJohn Marinothis limitation, and people would often be surprised that they could 2530*e4b17023SJohn Marinonot use macros in this way. Moreover, sometimes people would use 2531*e4b17023SJohn Marinoconditional compilation in the argument list to a normal library 2532*e4b17023SJohn Marinofunction like @samp{printf}, only to find that after a library upgrade 2533*e4b17023SJohn Marino@samp{printf} had changed to be a function-like macro, and their code 2534*e4b17023SJohn Marinowould no longer compile. So from version 3.2 we changed CPP to 2535*e4b17023SJohn Marinosuccessfully process arbitrary directives within macro arguments in 2536*e4b17023SJohn Marinoexactly the same way as it would have processed the directive were the 2537*e4b17023SJohn Marinofunction-like macro invocation not present. 2538*e4b17023SJohn Marino 2539*e4b17023SJohn MarinoIf, within a macro invocation, that macro is redefined, then the new 2540*e4b17023SJohn Marinodefinition takes effect in time for argument pre-expansion, but the 2541*e4b17023SJohn Marinooriginal definition is still used for argument replacement. Here is a 2542*e4b17023SJohn Marinopathological example: 2543*e4b17023SJohn Marino 2544*e4b17023SJohn Marino@smallexample 2545*e4b17023SJohn Marino#define f(x) x x 2546*e4b17023SJohn Marinof (1 2547*e4b17023SJohn Marino#undef f 2548*e4b17023SJohn Marino#define f 2 2549*e4b17023SJohn Marinof) 2550*e4b17023SJohn Marino@end smallexample 2551*e4b17023SJohn Marino 2552*e4b17023SJohn Marino@noindent 2553*e4b17023SJohn Marinowhich expands to 2554*e4b17023SJohn Marino 2555*e4b17023SJohn Marino@smallexample 2556*e4b17023SJohn Marino1 2 1 2 2557*e4b17023SJohn Marino@end smallexample 2558*e4b17023SJohn Marino 2559*e4b17023SJohn Marino@noindent 2560*e4b17023SJohn Marinowith the semantics described above. 2561*e4b17023SJohn Marino 2562*e4b17023SJohn Marino@node Macro Pitfalls 2563*e4b17023SJohn Marino@section Macro Pitfalls 2564*e4b17023SJohn Marino@cindex problems with macros 2565*e4b17023SJohn Marino@cindex pitfalls of macros 2566*e4b17023SJohn Marino 2567*e4b17023SJohn MarinoIn this section we describe some special rules that apply to macros and 2568*e4b17023SJohn Marinomacro expansion, and point out certain cases in which the rules have 2569*e4b17023SJohn Marinocounter-intuitive consequences that you must watch out for. 2570*e4b17023SJohn Marino 2571*e4b17023SJohn Marino@menu 2572*e4b17023SJohn Marino* Misnesting:: 2573*e4b17023SJohn Marino* Operator Precedence Problems:: 2574*e4b17023SJohn Marino* Swallowing the Semicolon:: 2575*e4b17023SJohn Marino* Duplication of Side Effects:: 2576*e4b17023SJohn Marino* Self-Referential Macros:: 2577*e4b17023SJohn Marino* Argument Prescan:: 2578*e4b17023SJohn Marino* Newlines in Arguments:: 2579*e4b17023SJohn Marino@end menu 2580*e4b17023SJohn Marino 2581*e4b17023SJohn Marino@node Misnesting 2582*e4b17023SJohn Marino@subsection Misnesting 2583*e4b17023SJohn Marino 2584*e4b17023SJohn MarinoWhen a macro is called with arguments, the arguments are substituted 2585*e4b17023SJohn Marinointo the macro body and the result is checked, together with the rest of 2586*e4b17023SJohn Marinothe input file, for more macro calls. It is possible to piece together 2587*e4b17023SJohn Marinoa macro call coming partially from the macro body and partially from the 2588*e4b17023SJohn Marinoarguments. For example, 2589*e4b17023SJohn Marino 2590*e4b17023SJohn Marino@smallexample 2591*e4b17023SJohn Marino#define twice(x) (2*(x)) 2592*e4b17023SJohn Marino#define call_with_1(x) x(1) 2593*e4b17023SJohn Marinocall_with_1 (twice) 2594*e4b17023SJohn Marino @expansion{} twice(1) 2595*e4b17023SJohn Marino @expansion{} (2*(1)) 2596*e4b17023SJohn Marino@end smallexample 2597*e4b17023SJohn Marino 2598*e4b17023SJohn MarinoMacro definitions do not have to have balanced parentheses. By writing 2599*e4b17023SJohn Marinoan unbalanced open parenthesis in a macro body, it is possible to create 2600*e4b17023SJohn Marinoa macro call that begins inside the macro body but ends outside of it. 2601*e4b17023SJohn MarinoFor example, 2602*e4b17023SJohn Marino 2603*e4b17023SJohn Marino@smallexample 2604*e4b17023SJohn Marino#define strange(file) fprintf (file, "%s %d", 2605*e4b17023SJohn Marino@dots{} 2606*e4b17023SJohn Marinostrange(stderr) p, 35) 2607*e4b17023SJohn Marino @expansion{} fprintf (stderr, "%s %d", p, 35) 2608*e4b17023SJohn Marino@end smallexample 2609*e4b17023SJohn Marino 2610*e4b17023SJohn MarinoThe ability to piece together a macro call can be useful, but the use of 2611*e4b17023SJohn Marinounbalanced open parentheses in a macro body is just confusing, and 2612*e4b17023SJohn Marinoshould be avoided. 2613*e4b17023SJohn Marino 2614*e4b17023SJohn Marino@node Operator Precedence Problems 2615*e4b17023SJohn Marino@subsection Operator Precedence Problems 2616*e4b17023SJohn Marino@cindex parentheses in macro bodies 2617*e4b17023SJohn Marino 2618*e4b17023SJohn MarinoYou may have noticed that in most of the macro definition examples shown 2619*e4b17023SJohn Marinoabove, each occurrence of a macro argument name had parentheses around 2620*e4b17023SJohn Marinoit. In addition, another pair of parentheses usually surround the 2621*e4b17023SJohn Marinoentire macro definition. Here is why it is best to write macros that 2622*e4b17023SJohn Marinoway. 2623*e4b17023SJohn Marino 2624*e4b17023SJohn MarinoSuppose you define a macro as follows, 2625*e4b17023SJohn Marino 2626*e4b17023SJohn Marino@smallexample 2627*e4b17023SJohn Marino#define ceil_div(x, y) (x + y - 1) / y 2628*e4b17023SJohn Marino@end smallexample 2629*e4b17023SJohn Marino 2630*e4b17023SJohn Marino@noindent 2631*e4b17023SJohn Marinowhose purpose is to divide, rounding up. (One use for this operation is 2632*e4b17023SJohn Marinoto compute how many @code{int} objects are needed to hold a certain 2633*e4b17023SJohn Marinonumber of @code{char} objects.) Then suppose it is used as follows: 2634*e4b17023SJohn Marino 2635*e4b17023SJohn Marino@smallexample 2636*e4b17023SJohn Marinoa = ceil_div (b & c, sizeof (int)); 2637*e4b17023SJohn Marino @expansion{} a = (b & c + sizeof (int) - 1) / sizeof (int); 2638*e4b17023SJohn Marino@end smallexample 2639*e4b17023SJohn Marino 2640*e4b17023SJohn Marino@noindent 2641*e4b17023SJohn MarinoThis does not do what is intended. The operator-precedence rules of 2642*e4b17023SJohn MarinoC make it equivalent to this: 2643*e4b17023SJohn Marino 2644*e4b17023SJohn Marino@smallexample 2645*e4b17023SJohn Marinoa = (b & (c + sizeof (int) - 1)) / sizeof (int); 2646*e4b17023SJohn Marino@end smallexample 2647*e4b17023SJohn Marino 2648*e4b17023SJohn Marino@noindent 2649*e4b17023SJohn MarinoWhat we want is this: 2650*e4b17023SJohn Marino 2651*e4b17023SJohn Marino@smallexample 2652*e4b17023SJohn Marinoa = ((b & c) + sizeof (int) - 1)) / sizeof (int); 2653*e4b17023SJohn Marino@end smallexample 2654*e4b17023SJohn Marino 2655*e4b17023SJohn Marino@noindent 2656*e4b17023SJohn MarinoDefining the macro as 2657*e4b17023SJohn Marino 2658*e4b17023SJohn Marino@smallexample 2659*e4b17023SJohn Marino#define ceil_div(x, y) ((x) + (y) - 1) / (y) 2660*e4b17023SJohn Marino@end smallexample 2661*e4b17023SJohn Marino 2662*e4b17023SJohn Marino@noindent 2663*e4b17023SJohn Marinoprovides the desired result. 2664*e4b17023SJohn Marino 2665*e4b17023SJohn MarinoUnintended grouping can result in another way. Consider @code{sizeof 2666*e4b17023SJohn Marinoceil_div(1, 2)}. That has the appearance of a C expression that would 2667*e4b17023SJohn Marinocompute the size of the type of @code{ceil_div (1, 2)}, but in fact it 2668*e4b17023SJohn Marinomeans something very different. Here is what it expands to: 2669*e4b17023SJohn Marino 2670*e4b17023SJohn Marino@smallexample 2671*e4b17023SJohn Marinosizeof ((1) + (2) - 1) / (2) 2672*e4b17023SJohn Marino@end smallexample 2673*e4b17023SJohn Marino 2674*e4b17023SJohn Marino@noindent 2675*e4b17023SJohn MarinoThis would take the size of an integer and divide it by two. The 2676*e4b17023SJohn Marinoprecedence rules have put the division outside the @code{sizeof} when it 2677*e4b17023SJohn Marinowas intended to be inside. 2678*e4b17023SJohn Marino 2679*e4b17023SJohn MarinoParentheses around the entire macro definition prevent such problems. 2680*e4b17023SJohn MarinoHere, then, is the recommended way to define @code{ceil_div}: 2681*e4b17023SJohn Marino 2682*e4b17023SJohn Marino@smallexample 2683*e4b17023SJohn Marino#define ceil_div(x, y) (((x) + (y) - 1) / (y)) 2684*e4b17023SJohn Marino@end smallexample 2685*e4b17023SJohn Marino 2686*e4b17023SJohn Marino@node Swallowing the Semicolon 2687*e4b17023SJohn Marino@subsection Swallowing the Semicolon 2688*e4b17023SJohn Marino@cindex semicolons (after macro calls) 2689*e4b17023SJohn Marino 2690*e4b17023SJohn MarinoOften it is desirable to define a macro that expands into a compound 2691*e4b17023SJohn Marinostatement. Consider, for example, the following macro, that advances a 2692*e4b17023SJohn Marinopointer (the argument @code{p} says where to find it) across whitespace 2693*e4b17023SJohn Marinocharacters: 2694*e4b17023SJohn Marino 2695*e4b17023SJohn Marino@smallexample 2696*e4b17023SJohn Marino#define SKIP_SPACES(p, limit) \ 2697*e4b17023SJohn Marino@{ char *lim = (limit); \ 2698*e4b17023SJohn Marino while (p < lim) @{ \ 2699*e4b17023SJohn Marino if (*p++ != ' ') @{ \ 2700*e4b17023SJohn Marino p--; break; @}@}@} 2701*e4b17023SJohn Marino@end smallexample 2702*e4b17023SJohn Marino 2703*e4b17023SJohn Marino@noindent 2704*e4b17023SJohn MarinoHere backslash-newline is used to split the macro definition, which must 2705*e4b17023SJohn Marinobe a single logical line, so that it resembles the way such code would 2706*e4b17023SJohn Marinobe laid out if not part of a macro definition. 2707*e4b17023SJohn Marino 2708*e4b17023SJohn MarinoA call to this macro might be @code{SKIP_SPACES (p, lim)}. Strictly 2709*e4b17023SJohn Marinospeaking, the call expands to a compound statement, which is a complete 2710*e4b17023SJohn Marinostatement with no need for a semicolon to end it. However, since it 2711*e4b17023SJohn Marinolooks like a function call, it minimizes confusion if you can use it 2712*e4b17023SJohn Marinolike a function call, writing a semicolon afterward, as in 2713*e4b17023SJohn Marino@code{SKIP_SPACES (p, lim);} 2714*e4b17023SJohn Marino 2715*e4b17023SJohn MarinoThis can cause trouble before @code{else} statements, because the 2716*e4b17023SJohn Marinosemicolon is actually a null statement. Suppose you write 2717*e4b17023SJohn Marino 2718*e4b17023SJohn Marino@smallexample 2719*e4b17023SJohn Marinoif (*p != 0) 2720*e4b17023SJohn Marino SKIP_SPACES (p, lim); 2721*e4b17023SJohn Marinoelse @dots{} 2722*e4b17023SJohn Marino@end smallexample 2723*e4b17023SJohn Marino 2724*e4b17023SJohn Marino@noindent 2725*e4b17023SJohn MarinoThe presence of two statements---the compound statement and a null 2726*e4b17023SJohn Marinostatement---in between the @code{if} condition and the @code{else} 2727*e4b17023SJohn Marinomakes invalid C code. 2728*e4b17023SJohn Marino 2729*e4b17023SJohn MarinoThe definition of the macro @code{SKIP_SPACES} can be altered to solve 2730*e4b17023SJohn Marinothis problem, using a @code{do @dots{} while} statement. Here is how: 2731*e4b17023SJohn Marino 2732*e4b17023SJohn Marino@smallexample 2733*e4b17023SJohn Marino#define SKIP_SPACES(p, limit) \ 2734*e4b17023SJohn Marinodo @{ char *lim = (limit); \ 2735*e4b17023SJohn Marino while (p < lim) @{ \ 2736*e4b17023SJohn Marino if (*p++ != ' ') @{ \ 2737*e4b17023SJohn Marino p--; break; @}@}@} \ 2738*e4b17023SJohn Marinowhile (0) 2739*e4b17023SJohn Marino@end smallexample 2740*e4b17023SJohn Marino 2741*e4b17023SJohn MarinoNow @code{SKIP_SPACES (p, lim);} expands into 2742*e4b17023SJohn Marino 2743*e4b17023SJohn Marino@smallexample 2744*e4b17023SJohn Marinodo @{@dots{}@} while (0); 2745*e4b17023SJohn Marino@end smallexample 2746*e4b17023SJohn Marino 2747*e4b17023SJohn Marino@noindent 2748*e4b17023SJohn Marinowhich is one statement. The loop executes exactly once; most compilers 2749*e4b17023SJohn Marinogenerate no extra code for it. 2750*e4b17023SJohn Marino 2751*e4b17023SJohn Marino@node Duplication of Side Effects 2752*e4b17023SJohn Marino@subsection Duplication of Side Effects 2753*e4b17023SJohn Marino 2754*e4b17023SJohn Marino@cindex side effects (in macro arguments) 2755*e4b17023SJohn Marino@cindex unsafe macros 2756*e4b17023SJohn MarinoMany C programs define a macro @code{min}, for ``minimum'', like this: 2757*e4b17023SJohn Marino 2758*e4b17023SJohn Marino@smallexample 2759*e4b17023SJohn Marino#define min(X, Y) ((X) < (Y) ? (X) : (Y)) 2760*e4b17023SJohn Marino@end smallexample 2761*e4b17023SJohn Marino 2762*e4b17023SJohn MarinoWhen you use this macro with an argument containing a side effect, 2763*e4b17023SJohn Marinoas shown here, 2764*e4b17023SJohn Marino 2765*e4b17023SJohn Marino@smallexample 2766*e4b17023SJohn Marinonext = min (x + y, foo (z)); 2767*e4b17023SJohn Marino@end smallexample 2768*e4b17023SJohn Marino 2769*e4b17023SJohn Marino@noindent 2770*e4b17023SJohn Marinoit expands as follows: 2771*e4b17023SJohn Marino 2772*e4b17023SJohn Marino@smallexample 2773*e4b17023SJohn Marinonext = ((x + y) < (foo (z)) ? (x + y) : (foo (z))); 2774*e4b17023SJohn Marino@end smallexample 2775*e4b17023SJohn Marino 2776*e4b17023SJohn Marino@noindent 2777*e4b17023SJohn Marinowhere @code{x + y} has been substituted for @code{X} and @code{foo (z)} 2778*e4b17023SJohn Marinofor @code{Y}. 2779*e4b17023SJohn Marino 2780*e4b17023SJohn MarinoThe function @code{foo} is used only once in the statement as it appears 2781*e4b17023SJohn Marinoin the program, but the expression @code{foo (z)} has been substituted 2782*e4b17023SJohn Marinotwice into the macro expansion. As a result, @code{foo} might be called 2783*e4b17023SJohn Marinotwo times when the statement is executed. If it has side effects or if 2784*e4b17023SJohn Marinoit takes a long time to compute, the results might not be what you 2785*e4b17023SJohn Marinointended. We say that @code{min} is an @dfn{unsafe} macro. 2786*e4b17023SJohn Marino 2787*e4b17023SJohn MarinoThe best solution to this problem is to define @code{min} in a way that 2788*e4b17023SJohn Marinocomputes the value of @code{foo (z)} only once. The C language offers 2789*e4b17023SJohn Marinono standard way to do this, but it can be done with GNU extensions as 2790*e4b17023SJohn Marinofollows: 2791*e4b17023SJohn Marino 2792*e4b17023SJohn Marino@smallexample 2793*e4b17023SJohn Marino#define min(X, Y) \ 2794*e4b17023SJohn Marino(@{ typeof (X) x_ = (X); \ 2795*e4b17023SJohn Marino typeof (Y) y_ = (Y); \ 2796*e4b17023SJohn Marino (x_ < y_) ? x_ : y_; @}) 2797*e4b17023SJohn Marino@end smallexample 2798*e4b17023SJohn Marino 2799*e4b17023SJohn MarinoThe @samp{(@{ @dots{} @})} notation produces a compound statement that 2800*e4b17023SJohn Marinoacts as an expression. Its value is the value of its last statement. 2801*e4b17023SJohn MarinoThis permits us to define local variables and assign each argument to 2802*e4b17023SJohn Marinoone. The local variables have underscores after their names to reduce 2803*e4b17023SJohn Marinothe risk of conflict with an identifier of wider scope (it is impossible 2804*e4b17023SJohn Marinoto avoid this entirely). Now each argument is evaluated exactly once. 2805*e4b17023SJohn Marino 2806*e4b17023SJohn MarinoIf you do not wish to use GNU C extensions, the only solution is to be 2807*e4b17023SJohn Marinocareful when @emph{using} the macro @code{min}. For example, you can 2808*e4b17023SJohn Marinocalculate the value of @code{foo (z)}, save it in a variable, and use 2809*e4b17023SJohn Marinothat variable in @code{min}: 2810*e4b17023SJohn Marino 2811*e4b17023SJohn Marino@smallexample 2812*e4b17023SJohn Marino@group 2813*e4b17023SJohn Marino#define min(X, Y) ((X) < (Y) ? (X) : (Y)) 2814*e4b17023SJohn Marino@dots{} 2815*e4b17023SJohn Marino@{ 2816*e4b17023SJohn Marino int tem = foo (z); 2817*e4b17023SJohn Marino next = min (x + y, tem); 2818*e4b17023SJohn Marino@} 2819*e4b17023SJohn Marino@end group 2820*e4b17023SJohn Marino@end smallexample 2821*e4b17023SJohn Marino 2822*e4b17023SJohn Marino@noindent 2823*e4b17023SJohn Marino(where we assume that @code{foo} returns type @code{int}). 2824*e4b17023SJohn Marino 2825*e4b17023SJohn Marino@node Self-Referential Macros 2826*e4b17023SJohn Marino@subsection Self-Referential Macros 2827*e4b17023SJohn Marino@cindex self-reference 2828*e4b17023SJohn Marino 2829*e4b17023SJohn MarinoA @dfn{self-referential} macro is one whose name appears in its 2830*e4b17023SJohn Marinodefinition. Recall that all macro definitions are rescanned for more 2831*e4b17023SJohn Marinomacros to replace. If the self-reference were considered a use of the 2832*e4b17023SJohn Marinomacro, it would produce an infinitely large expansion. To prevent this, 2833*e4b17023SJohn Marinothe self-reference is not considered a macro call. It is passed into 2834*e4b17023SJohn Marinothe preprocessor output unchanged. Consider an example: 2835*e4b17023SJohn Marino 2836*e4b17023SJohn Marino@smallexample 2837*e4b17023SJohn Marino#define foo (4 + foo) 2838*e4b17023SJohn Marino@end smallexample 2839*e4b17023SJohn Marino 2840*e4b17023SJohn Marino@noindent 2841*e4b17023SJohn Marinowhere @code{foo} is also a variable in your program. 2842*e4b17023SJohn Marino 2843*e4b17023SJohn MarinoFollowing the ordinary rules, each reference to @code{foo} will expand 2844*e4b17023SJohn Marinointo @code{(4 + foo)}; then this will be rescanned and will expand into 2845*e4b17023SJohn Marino@code{(4 + (4 + foo))}; and so on until the computer runs out of memory. 2846*e4b17023SJohn Marino 2847*e4b17023SJohn MarinoThe self-reference rule cuts this process short after one step, at 2848*e4b17023SJohn Marino@code{(4 + foo)}. Therefore, this macro definition has the possibly 2849*e4b17023SJohn Marinouseful effect of causing the program to add 4 to the value of @code{foo} 2850*e4b17023SJohn Marinowherever @code{foo} is referred to. 2851*e4b17023SJohn Marino 2852*e4b17023SJohn MarinoIn most cases, it is a bad idea to take advantage of this feature. A 2853*e4b17023SJohn Marinoperson reading the program who sees that @code{foo} is a variable will 2854*e4b17023SJohn Marinonot expect that it is a macro as well. The reader will come across the 2855*e4b17023SJohn Marinoidentifier @code{foo} in the program and think its value should be that 2856*e4b17023SJohn Marinoof the variable @code{foo}, whereas in fact the value is four greater. 2857*e4b17023SJohn Marino 2858*e4b17023SJohn MarinoOne common, useful use of self-reference is to create a macro which 2859*e4b17023SJohn Marinoexpands to itself. If you write 2860*e4b17023SJohn Marino 2861*e4b17023SJohn Marino@smallexample 2862*e4b17023SJohn Marino#define EPERM EPERM 2863*e4b17023SJohn Marino@end smallexample 2864*e4b17023SJohn Marino 2865*e4b17023SJohn Marino@noindent 2866*e4b17023SJohn Marinothen the macro @code{EPERM} expands to @code{EPERM}. Effectively, it is 2867*e4b17023SJohn Marinoleft alone by the preprocessor whenever it's used in running text. You 2868*e4b17023SJohn Marinocan tell that it's a macro with @samp{#ifdef}. You might do this if you 2869*e4b17023SJohn Marinowant to define numeric constants with an @code{enum}, but have 2870*e4b17023SJohn Marino@samp{#ifdef} be true for each constant. 2871*e4b17023SJohn Marino 2872*e4b17023SJohn MarinoIf a macro @code{x} expands to use a macro @code{y}, and the expansion of 2873*e4b17023SJohn Marino@code{y} refers to the macro @code{x}, that is an @dfn{indirect 2874*e4b17023SJohn Marinoself-reference} of @code{x}. @code{x} is not expanded in this case 2875*e4b17023SJohn Marinoeither. Thus, if we have 2876*e4b17023SJohn Marino 2877*e4b17023SJohn Marino@smallexample 2878*e4b17023SJohn Marino#define x (4 + y) 2879*e4b17023SJohn Marino#define y (2 * x) 2880*e4b17023SJohn Marino@end smallexample 2881*e4b17023SJohn Marino 2882*e4b17023SJohn Marino@noindent 2883*e4b17023SJohn Marinothen @code{x} and @code{y} expand as follows: 2884*e4b17023SJohn Marino 2885*e4b17023SJohn Marino@smallexample 2886*e4b17023SJohn Marino@group 2887*e4b17023SJohn Marinox @expansion{} (4 + y) 2888*e4b17023SJohn Marino @expansion{} (4 + (2 * x)) 2889*e4b17023SJohn Marino 2890*e4b17023SJohn Marinoy @expansion{} (2 * x) 2891*e4b17023SJohn Marino @expansion{} (2 * (4 + y)) 2892*e4b17023SJohn Marino@end group 2893*e4b17023SJohn Marino@end smallexample 2894*e4b17023SJohn Marino 2895*e4b17023SJohn Marino@noindent 2896*e4b17023SJohn MarinoEach macro is expanded when it appears in the definition of the other 2897*e4b17023SJohn Marinomacro, but not when it indirectly appears in its own definition. 2898*e4b17023SJohn Marino 2899*e4b17023SJohn Marino@node Argument Prescan 2900*e4b17023SJohn Marino@subsection Argument Prescan 2901*e4b17023SJohn Marino@cindex expansion of arguments 2902*e4b17023SJohn Marino@cindex macro argument expansion 2903*e4b17023SJohn Marino@cindex prescan of macro arguments 2904*e4b17023SJohn Marino 2905*e4b17023SJohn MarinoMacro arguments are completely macro-expanded before they are 2906*e4b17023SJohn Marinosubstituted into a macro body, unless they are stringified or pasted 2907*e4b17023SJohn Marinowith other tokens. After substitution, the entire macro body, including 2908*e4b17023SJohn Marinothe substituted arguments, is scanned again for macros to be expanded. 2909*e4b17023SJohn MarinoThe result is that the arguments are scanned @emph{twice} to expand 2910*e4b17023SJohn Marinomacro calls in them. 2911*e4b17023SJohn Marino 2912*e4b17023SJohn MarinoMost of the time, this has no effect. If the argument contained any 2913*e4b17023SJohn Marinomacro calls, they are expanded during the first scan. The result 2914*e4b17023SJohn Marinotherefore contains no macro calls, so the second scan does not change 2915*e4b17023SJohn Marinoit. If the argument were substituted as given, with no prescan, the 2916*e4b17023SJohn Marinosingle remaining scan would find the same macro calls and produce the 2917*e4b17023SJohn Marinosame results. 2918*e4b17023SJohn Marino 2919*e4b17023SJohn MarinoYou might expect the double scan to change the results when a 2920*e4b17023SJohn Marinoself-referential macro is used in an argument of another macro 2921*e4b17023SJohn Marino(@pxref{Self-Referential Macros}): the self-referential macro would be 2922*e4b17023SJohn Marinoexpanded once in the first scan, and a second time in the second scan. 2923*e4b17023SJohn MarinoHowever, this is not what happens. The self-references that do not 2924*e4b17023SJohn Marinoexpand in the first scan are marked so that they will not expand in the 2925*e4b17023SJohn Marinosecond scan either. 2926*e4b17023SJohn Marino 2927*e4b17023SJohn MarinoYou might wonder, ``Why mention the prescan, if it makes no difference? 2928*e4b17023SJohn MarinoAnd why not skip it and make the preprocessor faster?'' The answer is 2929*e4b17023SJohn Marinothat the prescan does make a difference in three special cases: 2930*e4b17023SJohn Marino 2931*e4b17023SJohn Marino@itemize @bullet 2932*e4b17023SJohn Marino@item 2933*e4b17023SJohn MarinoNested calls to a macro. 2934*e4b17023SJohn Marino 2935*e4b17023SJohn MarinoWe say that @dfn{nested} calls to a macro occur when a macro's argument 2936*e4b17023SJohn Marinocontains a call to that very macro. For example, if @code{f} is a macro 2937*e4b17023SJohn Marinothat expects one argument, @code{f (f (1))} is a nested pair of calls to 2938*e4b17023SJohn Marino@code{f}. The desired expansion is made by expanding @code{f (1)} and 2939*e4b17023SJohn Marinosubstituting that into the definition of @code{f}. The prescan causes 2940*e4b17023SJohn Marinothe expected result to happen. Without the prescan, @code{f (1)} itself 2941*e4b17023SJohn Marinowould be substituted as an argument, and the inner use of @code{f} would 2942*e4b17023SJohn Marinoappear during the main scan as an indirect self-reference and would not 2943*e4b17023SJohn Marinobe expanded. 2944*e4b17023SJohn Marino 2945*e4b17023SJohn Marino@item 2946*e4b17023SJohn MarinoMacros that call other macros that stringify or concatenate. 2947*e4b17023SJohn Marino 2948*e4b17023SJohn MarinoIf an argument is stringified or concatenated, the prescan does not 2949*e4b17023SJohn Marinooccur. If you @emph{want} to expand a macro, then stringify or 2950*e4b17023SJohn Marinoconcatenate its expansion, you can do that by causing one macro to call 2951*e4b17023SJohn Marinoanother macro that does the stringification or concatenation. For 2952*e4b17023SJohn Marinoinstance, if you have 2953*e4b17023SJohn Marino 2954*e4b17023SJohn Marino@smallexample 2955*e4b17023SJohn Marino#define AFTERX(x) X_ ## x 2956*e4b17023SJohn Marino#define XAFTERX(x) AFTERX(x) 2957*e4b17023SJohn Marino#define TABLESIZE 1024 2958*e4b17023SJohn Marino#define BUFSIZE TABLESIZE 2959*e4b17023SJohn Marino@end smallexample 2960*e4b17023SJohn Marino 2961*e4b17023SJohn Marinothen @code{AFTERX(BUFSIZE)} expands to @code{X_BUFSIZE}, and 2962*e4b17023SJohn Marino@code{XAFTERX(BUFSIZE)} expands to @code{X_1024}. (Not to 2963*e4b17023SJohn Marino@code{X_TABLESIZE}. Prescan always does a complete expansion.) 2964*e4b17023SJohn Marino 2965*e4b17023SJohn Marino@item 2966*e4b17023SJohn MarinoMacros used in arguments, whose expansions contain unshielded commas. 2967*e4b17023SJohn Marino 2968*e4b17023SJohn MarinoThis can cause a macro expanded on the second scan to be called with the 2969*e4b17023SJohn Marinowrong number of arguments. Here is an example: 2970*e4b17023SJohn Marino 2971*e4b17023SJohn Marino@smallexample 2972*e4b17023SJohn Marino#define foo a,b 2973*e4b17023SJohn Marino#define bar(x) lose(x) 2974*e4b17023SJohn Marino#define lose(x) (1 + (x)) 2975*e4b17023SJohn Marino@end smallexample 2976*e4b17023SJohn Marino 2977*e4b17023SJohn MarinoWe would like @code{bar(foo)} to turn into @code{(1 + (foo))}, which 2978*e4b17023SJohn Marinowould then turn into @code{(1 + (a,b))}. Instead, @code{bar(foo)} 2979*e4b17023SJohn Marinoexpands into @code{lose(a,b)}, and you get an error because @code{lose} 2980*e4b17023SJohn Marinorequires a single argument. In this case, the problem is easily solved 2981*e4b17023SJohn Marinoby the same parentheses that ought to be used to prevent misnesting of 2982*e4b17023SJohn Marinoarithmetic operations: 2983*e4b17023SJohn Marino 2984*e4b17023SJohn Marino@smallexample 2985*e4b17023SJohn Marino#define foo (a,b) 2986*e4b17023SJohn Marino@exdent or 2987*e4b17023SJohn Marino#define bar(x) lose((x)) 2988*e4b17023SJohn Marino@end smallexample 2989*e4b17023SJohn Marino 2990*e4b17023SJohn MarinoThe extra pair of parentheses prevents the comma in @code{foo}'s 2991*e4b17023SJohn Marinodefinition from being interpreted as an argument separator. 2992*e4b17023SJohn Marino 2993*e4b17023SJohn Marino@end itemize 2994*e4b17023SJohn Marino 2995*e4b17023SJohn Marino@node Newlines in Arguments 2996*e4b17023SJohn Marino@subsection Newlines in Arguments 2997*e4b17023SJohn Marino@cindex newlines in macro arguments 2998*e4b17023SJohn Marino 2999*e4b17023SJohn MarinoThe invocation of a function-like macro can extend over many logical 3000*e4b17023SJohn Marinolines. However, in the present implementation, the entire expansion 3001*e4b17023SJohn Marinocomes out on one line. Thus line numbers emitted by the compiler or 3002*e4b17023SJohn Marinodebugger refer to the line the invocation started on, which might be 3003*e4b17023SJohn Marinodifferent to the line containing the argument causing the problem. 3004*e4b17023SJohn Marino 3005*e4b17023SJohn MarinoHere is an example illustrating this: 3006*e4b17023SJohn Marino 3007*e4b17023SJohn Marino@smallexample 3008*e4b17023SJohn Marino#define ignore_second_arg(a,b,c) a; c 3009*e4b17023SJohn Marino 3010*e4b17023SJohn Marinoignore_second_arg (foo (), 3011*e4b17023SJohn Marino ignored (), 3012*e4b17023SJohn Marino syntax error); 3013*e4b17023SJohn Marino@end smallexample 3014*e4b17023SJohn Marino 3015*e4b17023SJohn Marino@noindent 3016*e4b17023SJohn MarinoThe syntax error triggered by the tokens @code{syntax error} results in 3017*e4b17023SJohn Marinoan error message citing line three---the line of ignore_second_arg--- 3018*e4b17023SJohn Marinoeven though the problematic code comes from line five. 3019*e4b17023SJohn Marino 3020*e4b17023SJohn MarinoWe consider this a bug, and intend to fix it in the near future. 3021*e4b17023SJohn Marino 3022*e4b17023SJohn Marino@node Conditionals 3023*e4b17023SJohn Marino@chapter Conditionals 3024*e4b17023SJohn Marino@cindex conditionals 3025*e4b17023SJohn Marino 3026*e4b17023SJohn MarinoA @dfn{conditional} is a directive that instructs the preprocessor to 3027*e4b17023SJohn Marinoselect whether or not to include a chunk of code in the final token 3028*e4b17023SJohn Marinostream passed to the compiler. Preprocessor conditionals can test 3029*e4b17023SJohn Marinoarithmetic expressions, or whether a name is defined as a macro, or both 3030*e4b17023SJohn Marinosimultaneously using the special @code{defined} operator. 3031*e4b17023SJohn Marino 3032*e4b17023SJohn MarinoA conditional in the C preprocessor resembles in some ways an @code{if} 3033*e4b17023SJohn Marinostatement in C, but it is important to understand the difference between 3034*e4b17023SJohn Marinothem. The condition in an @code{if} statement is tested during the 3035*e4b17023SJohn Marinoexecution of your program. Its purpose is to allow your program to 3036*e4b17023SJohn Marinobehave differently from run to run, depending on the data it is 3037*e4b17023SJohn Marinooperating on. The condition in a preprocessing conditional directive is 3038*e4b17023SJohn Marinotested when your program is compiled. Its purpose is to allow different 3039*e4b17023SJohn Marinocode to be included in the program depending on the situation at the 3040*e4b17023SJohn Marinotime of compilation. 3041*e4b17023SJohn Marino 3042*e4b17023SJohn MarinoHowever, the distinction is becoming less clear. Modern compilers often 3043*e4b17023SJohn Marinodo test @code{if} statements when a program is compiled, if their 3044*e4b17023SJohn Marinoconditions are known not to vary at run time, and eliminate code which 3045*e4b17023SJohn Marinocan never be executed. If you can count on your compiler to do this, 3046*e4b17023SJohn Marinoyou may find that your program is more readable if you use @code{if} 3047*e4b17023SJohn Marinostatements with constant conditions (perhaps determined by macros). Of 3048*e4b17023SJohn Marinocourse, you can only use this to exclude code, not type definitions or 3049*e4b17023SJohn Marinoother preprocessing directives, and you can only do it if the code 3050*e4b17023SJohn Marinoremains syntactically valid when it is not to be used. 3051*e4b17023SJohn Marino 3052*e4b17023SJohn MarinoGCC version 3 eliminates this kind of never-executed code even when 3053*e4b17023SJohn Marinonot optimizing. Older versions did it only when optimizing. 3054*e4b17023SJohn Marino 3055*e4b17023SJohn Marino@menu 3056*e4b17023SJohn Marino* Conditional Uses:: 3057*e4b17023SJohn Marino* Conditional Syntax:: 3058*e4b17023SJohn Marino* Deleted Code:: 3059*e4b17023SJohn Marino@end menu 3060*e4b17023SJohn Marino 3061*e4b17023SJohn Marino@node Conditional Uses 3062*e4b17023SJohn Marino@section Conditional Uses 3063*e4b17023SJohn Marino 3064*e4b17023SJohn MarinoThere are three general reasons to use a conditional. 3065*e4b17023SJohn Marino 3066*e4b17023SJohn Marino@itemize @bullet 3067*e4b17023SJohn Marino@item 3068*e4b17023SJohn MarinoA program may need to use different code depending on the machine or 3069*e4b17023SJohn Marinooperating system it is to run on. In some cases the code for one 3070*e4b17023SJohn Marinooperating system may be erroneous on another operating system; for 3071*e4b17023SJohn Marinoexample, it might refer to data types or constants that do not exist on 3072*e4b17023SJohn Marinothe other system. When this happens, it is not enough to avoid 3073*e4b17023SJohn Marinoexecuting the invalid code. Its mere presence will cause the compiler 3074*e4b17023SJohn Marinoto reject the program. With a preprocessing conditional, the offending 3075*e4b17023SJohn Marinocode can be effectively excised from the program when it is not valid. 3076*e4b17023SJohn Marino 3077*e4b17023SJohn Marino@item 3078*e4b17023SJohn MarinoYou may want to be able to compile the same source file into two 3079*e4b17023SJohn Marinodifferent programs. One version might make frequent time-consuming 3080*e4b17023SJohn Marinoconsistency checks on its intermediate data, or print the values of 3081*e4b17023SJohn Marinothose data for debugging, and the other not. 3082*e4b17023SJohn Marino 3083*e4b17023SJohn Marino@item 3084*e4b17023SJohn MarinoA conditional whose condition is always false is one way to exclude code 3085*e4b17023SJohn Marinofrom the program but keep it as a sort of comment for future reference. 3086*e4b17023SJohn Marino@end itemize 3087*e4b17023SJohn Marino 3088*e4b17023SJohn MarinoSimple programs that do not need system-specific logic or complex 3089*e4b17023SJohn Marinodebugging hooks generally will not need to use preprocessing 3090*e4b17023SJohn Marinoconditionals. 3091*e4b17023SJohn Marino 3092*e4b17023SJohn Marino@node Conditional Syntax 3093*e4b17023SJohn Marino@section Conditional Syntax 3094*e4b17023SJohn Marino 3095*e4b17023SJohn Marino@findex #if 3096*e4b17023SJohn MarinoA conditional in the C preprocessor begins with a @dfn{conditional 3097*e4b17023SJohn Marinodirective}: @samp{#if}, @samp{#ifdef} or @samp{#ifndef}. 3098*e4b17023SJohn Marino 3099*e4b17023SJohn Marino@menu 3100*e4b17023SJohn Marino* Ifdef:: 3101*e4b17023SJohn Marino* If:: 3102*e4b17023SJohn Marino* Defined:: 3103*e4b17023SJohn Marino* Else:: 3104*e4b17023SJohn Marino* Elif:: 3105*e4b17023SJohn Marino@end menu 3106*e4b17023SJohn Marino 3107*e4b17023SJohn Marino@node Ifdef 3108*e4b17023SJohn Marino@subsection Ifdef 3109*e4b17023SJohn Marino@findex #ifdef 3110*e4b17023SJohn Marino@findex #endif 3111*e4b17023SJohn Marino 3112*e4b17023SJohn MarinoThe simplest sort of conditional is 3113*e4b17023SJohn Marino 3114*e4b17023SJohn Marino@smallexample 3115*e4b17023SJohn Marino@group 3116*e4b17023SJohn Marino#ifdef @var{MACRO} 3117*e4b17023SJohn Marino 3118*e4b17023SJohn Marino@var{controlled text} 3119*e4b17023SJohn Marino 3120*e4b17023SJohn Marino#endif /* @var{MACRO} */ 3121*e4b17023SJohn Marino@end group 3122*e4b17023SJohn Marino@end smallexample 3123*e4b17023SJohn Marino 3124*e4b17023SJohn Marino@cindex conditional group 3125*e4b17023SJohn MarinoThis block is called a @dfn{conditional group}. @var{controlled text} 3126*e4b17023SJohn Marinowill be included in the output of the preprocessor if and only if 3127*e4b17023SJohn Marino@var{MACRO} is defined. We say that the conditional @dfn{succeeds} if 3128*e4b17023SJohn Marino@var{MACRO} is defined, @dfn{fails} if it is not. 3129*e4b17023SJohn Marino 3130*e4b17023SJohn MarinoThe @var{controlled text} inside of a conditional can include 3131*e4b17023SJohn Marinopreprocessing directives. They are executed only if the conditional 3132*e4b17023SJohn Marinosucceeds. You can nest conditional groups inside other conditional 3133*e4b17023SJohn Marinogroups, but they must be completely nested. In other words, 3134*e4b17023SJohn Marino@samp{#endif} always matches the nearest @samp{#ifdef} (or 3135*e4b17023SJohn Marino@samp{#ifndef}, or @samp{#if}). Also, you cannot start a conditional 3136*e4b17023SJohn Marinogroup in one file and end it in another. 3137*e4b17023SJohn Marino 3138*e4b17023SJohn MarinoEven if a conditional fails, the @var{controlled text} inside it is 3139*e4b17023SJohn Marinostill run through initial transformations and tokenization. Therefore, 3140*e4b17023SJohn Marinoit must all be lexically valid C@. Normally the only way this matters is 3141*e4b17023SJohn Marinothat all comments and string literals inside a failing conditional group 3142*e4b17023SJohn Marinomust still be properly ended. 3143*e4b17023SJohn Marino 3144*e4b17023SJohn MarinoThe comment following the @samp{#endif} is not required, but it is a 3145*e4b17023SJohn Marinogood practice if there is a lot of @var{controlled text}, because it 3146*e4b17023SJohn Marinohelps people match the @samp{#endif} to the corresponding @samp{#ifdef}. 3147*e4b17023SJohn MarinoOlder programs sometimes put @var{MACRO} directly after the 3148*e4b17023SJohn Marino@samp{#endif} without enclosing it in a comment. This is invalid code 3149*e4b17023SJohn Marinoaccording to the C standard. CPP accepts it with a warning. It 3150*e4b17023SJohn Marinonever affects which @samp{#ifndef} the @samp{#endif} matches. 3151*e4b17023SJohn Marino 3152*e4b17023SJohn Marino@findex #ifndef 3153*e4b17023SJohn MarinoSometimes you wish to use some code if a macro is @emph{not} defined. 3154*e4b17023SJohn MarinoYou can do this by writing @samp{#ifndef} instead of @samp{#ifdef}. 3155*e4b17023SJohn MarinoOne common use of @samp{#ifndef} is to include code only the first 3156*e4b17023SJohn Marinotime a header file is included. @xref{Once-Only Headers}. 3157*e4b17023SJohn Marino 3158*e4b17023SJohn MarinoMacro definitions can vary between compilations for several reasons. 3159*e4b17023SJohn MarinoHere are some samples. 3160*e4b17023SJohn Marino 3161*e4b17023SJohn Marino@itemize @bullet 3162*e4b17023SJohn Marino@item 3163*e4b17023SJohn MarinoSome macros are predefined on each kind of machine 3164*e4b17023SJohn Marino(@pxref{System-specific Predefined Macros}). This allows you to provide 3165*e4b17023SJohn Marinocode specially tuned for a particular machine. 3166*e4b17023SJohn Marino 3167*e4b17023SJohn Marino@item 3168*e4b17023SJohn MarinoSystem header files define more macros, associated with the features 3169*e4b17023SJohn Marinothey implement. You can test these macros with conditionals to avoid 3170*e4b17023SJohn Marinousing a system feature on a machine where it is not implemented. 3171*e4b17023SJohn Marino 3172*e4b17023SJohn Marino@item 3173*e4b17023SJohn MarinoMacros can be defined or undefined with the @option{-D} and @option{-U} 3174*e4b17023SJohn Marinocommand line options when you compile the program. You can arrange to 3175*e4b17023SJohn Marinocompile the same source file into two different programs by choosing a 3176*e4b17023SJohn Marinomacro name to specify which program you want, writing conditionals to 3177*e4b17023SJohn Marinotest whether or how this macro is defined, and then controlling the 3178*e4b17023SJohn Marinostate of the macro with command line options, perhaps set in the 3179*e4b17023SJohn MarinoMakefile. @xref{Invocation}. 3180*e4b17023SJohn Marino 3181*e4b17023SJohn Marino@item 3182*e4b17023SJohn MarinoYour program might have a special header file (often called 3183*e4b17023SJohn Marino@file{config.h}) that is adjusted when the program is compiled. It can 3184*e4b17023SJohn Marinodefine or not define macros depending on the features of the system and 3185*e4b17023SJohn Marinothe desired capabilities of the program. The adjustment can be 3186*e4b17023SJohn Marinoautomated by a tool such as @command{autoconf}, or done by hand. 3187*e4b17023SJohn Marino@end itemize 3188*e4b17023SJohn Marino 3189*e4b17023SJohn Marino@node If 3190*e4b17023SJohn Marino@subsection If 3191*e4b17023SJohn Marino 3192*e4b17023SJohn MarinoThe @samp{#if} directive allows you to test the value of an arithmetic 3193*e4b17023SJohn Marinoexpression, rather than the mere existence of one macro. Its syntax is 3194*e4b17023SJohn Marino 3195*e4b17023SJohn Marino@smallexample 3196*e4b17023SJohn Marino@group 3197*e4b17023SJohn Marino#if @var{expression} 3198*e4b17023SJohn Marino 3199*e4b17023SJohn Marino@var{controlled text} 3200*e4b17023SJohn Marino 3201*e4b17023SJohn Marino#endif /* @var{expression} */ 3202*e4b17023SJohn Marino@end group 3203*e4b17023SJohn Marino@end smallexample 3204*e4b17023SJohn Marino 3205*e4b17023SJohn Marino@var{expression} is a C expression of integer type, subject to stringent 3206*e4b17023SJohn Marinorestrictions. It may contain 3207*e4b17023SJohn Marino 3208*e4b17023SJohn Marino@itemize @bullet 3209*e4b17023SJohn Marino@item 3210*e4b17023SJohn MarinoInteger constants. 3211*e4b17023SJohn Marino 3212*e4b17023SJohn Marino@item 3213*e4b17023SJohn MarinoCharacter constants, which are interpreted as they would be in normal 3214*e4b17023SJohn Marinocode. 3215*e4b17023SJohn Marino 3216*e4b17023SJohn Marino@item 3217*e4b17023SJohn MarinoArithmetic operators for addition, subtraction, multiplication, 3218*e4b17023SJohn Marinodivision, bitwise operations, shifts, comparisons, and logical 3219*e4b17023SJohn Marinooperations (@code{&&} and @code{||}). The latter two obey the usual 3220*e4b17023SJohn Marinoshort-circuiting rules of standard C@. 3221*e4b17023SJohn Marino 3222*e4b17023SJohn Marino@item 3223*e4b17023SJohn MarinoMacros. All macros in the expression are expanded before actual 3224*e4b17023SJohn Marinocomputation of the expression's value begins. 3225*e4b17023SJohn Marino 3226*e4b17023SJohn Marino@item 3227*e4b17023SJohn MarinoUses of the @code{defined} operator, which lets you check whether macros 3228*e4b17023SJohn Marinoare defined in the middle of an @samp{#if}. 3229*e4b17023SJohn Marino 3230*e4b17023SJohn Marino@item 3231*e4b17023SJohn MarinoIdentifiers that are not macros, which are all considered to be the 3232*e4b17023SJohn Marinonumber zero. This allows you to write @code{@w{#if MACRO}} instead of 3233*e4b17023SJohn Marino@code{@w{#ifdef MACRO}}, if you know that MACRO, when defined, will 3234*e4b17023SJohn Marinoalways have a nonzero value. Function-like macros used without their 3235*e4b17023SJohn Marinofunction call parentheses are also treated as zero. 3236*e4b17023SJohn Marino 3237*e4b17023SJohn MarinoIn some contexts this shortcut is undesirable. The @option{-Wundef} 3238*e4b17023SJohn Marinooption causes GCC to warn whenever it encounters an identifier which is 3239*e4b17023SJohn Marinonot a macro in an @samp{#if}. 3240*e4b17023SJohn Marino@end itemize 3241*e4b17023SJohn Marino 3242*e4b17023SJohn MarinoThe preprocessor does not know anything about types in the language. 3243*e4b17023SJohn MarinoTherefore, @code{sizeof} operators are not recognized in @samp{#if}, and 3244*e4b17023SJohn Marinoneither are @code{enum} constants. They will be taken as identifiers 3245*e4b17023SJohn Marinowhich are not macros, and replaced by zero. In the case of 3246*e4b17023SJohn Marino@code{sizeof}, this is likely to cause the expression to be invalid. 3247*e4b17023SJohn Marino 3248*e4b17023SJohn MarinoThe preprocessor calculates the value of @var{expression}. It carries 3249*e4b17023SJohn Marinoout all calculations in the widest integer type known to the compiler; 3250*e4b17023SJohn Marinoon most machines supported by GCC this is 64 bits. This is not the same 3251*e4b17023SJohn Marinorule as the compiler uses to calculate the value of a constant 3252*e4b17023SJohn Marinoexpression, and may give different results in some cases. If the value 3253*e4b17023SJohn Marinocomes out to be nonzero, the @samp{#if} succeeds and the @var{controlled 3254*e4b17023SJohn Marinotext} is included; otherwise it is skipped. 3255*e4b17023SJohn Marino 3256*e4b17023SJohn Marino@node Defined 3257*e4b17023SJohn Marino@subsection Defined 3258*e4b17023SJohn Marino 3259*e4b17023SJohn Marino@cindex @code{defined} 3260*e4b17023SJohn MarinoThe special operator @code{defined} is used in @samp{#if} and 3261*e4b17023SJohn Marino@samp{#elif} expressions to test whether a certain name is defined as a 3262*e4b17023SJohn Marinomacro. @code{defined @var{name}} and @code{defined (@var{name})} are 3263*e4b17023SJohn Marinoboth expressions whose value is 1 if @var{name} is defined as a macro at 3264*e4b17023SJohn Marinothe current point in the program, and 0 otherwise. Thus, @code{@w{#if 3265*e4b17023SJohn Marinodefined MACRO}} is precisely equivalent to @code{@w{#ifdef MACRO}}. 3266*e4b17023SJohn Marino 3267*e4b17023SJohn Marino@code{defined} is useful when you wish to test more than one macro for 3268*e4b17023SJohn Marinoexistence at once. For example, 3269*e4b17023SJohn Marino 3270*e4b17023SJohn Marino@smallexample 3271*e4b17023SJohn Marino#if defined (__vax__) || defined (__ns16000__) 3272*e4b17023SJohn Marino@end smallexample 3273*e4b17023SJohn Marino 3274*e4b17023SJohn Marino@noindent 3275*e4b17023SJohn Marinowould succeed if either of the names @code{__vax__} or 3276*e4b17023SJohn Marino@code{__ns16000__} is defined as a macro. 3277*e4b17023SJohn Marino 3278*e4b17023SJohn MarinoConditionals written like this: 3279*e4b17023SJohn Marino 3280*e4b17023SJohn Marino@smallexample 3281*e4b17023SJohn Marino#if defined BUFSIZE && BUFSIZE >= 1024 3282*e4b17023SJohn Marino@end smallexample 3283*e4b17023SJohn Marino 3284*e4b17023SJohn Marino@noindent 3285*e4b17023SJohn Marinocan generally be simplified to just @code{@w{#if BUFSIZE >= 1024}}, 3286*e4b17023SJohn Marinosince if @code{BUFSIZE} is not defined, it will be interpreted as having 3287*e4b17023SJohn Marinothe value zero. 3288*e4b17023SJohn Marino 3289*e4b17023SJohn MarinoIf the @code{defined} operator appears as a result of a macro expansion, 3290*e4b17023SJohn Marinothe C standard says the behavior is undefined. GNU cpp treats it as a 3291*e4b17023SJohn Marinogenuine @code{defined} operator and evaluates it normally. It will warn 3292*e4b17023SJohn Marinowherever your code uses this feature if you use the command-line option 3293*e4b17023SJohn Marino@option{-pedantic}, since other compilers may handle it differently. 3294*e4b17023SJohn Marino 3295*e4b17023SJohn Marino@node Else 3296*e4b17023SJohn Marino@subsection Else 3297*e4b17023SJohn Marino 3298*e4b17023SJohn Marino@findex #else 3299*e4b17023SJohn MarinoThe @samp{#else} directive can be added to a conditional to provide 3300*e4b17023SJohn Marinoalternative text to be used if the condition fails. This is what it 3301*e4b17023SJohn Marinolooks like: 3302*e4b17023SJohn Marino 3303*e4b17023SJohn Marino@smallexample 3304*e4b17023SJohn Marino@group 3305*e4b17023SJohn Marino#if @var{expression} 3306*e4b17023SJohn Marino@var{text-if-true} 3307*e4b17023SJohn Marino#else /* Not @var{expression} */ 3308*e4b17023SJohn Marino@var{text-if-false} 3309*e4b17023SJohn Marino#endif /* Not @var{expression} */ 3310*e4b17023SJohn Marino@end group 3311*e4b17023SJohn Marino@end smallexample 3312*e4b17023SJohn Marino 3313*e4b17023SJohn Marino@noindent 3314*e4b17023SJohn MarinoIf @var{expression} is nonzero, the @var{text-if-true} is included and 3315*e4b17023SJohn Marinothe @var{text-if-false} is skipped. If @var{expression} is zero, the 3316*e4b17023SJohn Marinoopposite happens. 3317*e4b17023SJohn Marino 3318*e4b17023SJohn MarinoYou can use @samp{#else} with @samp{#ifdef} and @samp{#ifndef}, too. 3319*e4b17023SJohn Marino 3320*e4b17023SJohn Marino@node Elif 3321*e4b17023SJohn Marino@subsection Elif 3322*e4b17023SJohn Marino 3323*e4b17023SJohn Marino@findex #elif 3324*e4b17023SJohn MarinoOne common case of nested conditionals is used to check for more than two 3325*e4b17023SJohn Marinopossible alternatives. For example, you might have 3326*e4b17023SJohn Marino 3327*e4b17023SJohn Marino@smallexample 3328*e4b17023SJohn Marino#if X == 1 3329*e4b17023SJohn Marino@dots{} 3330*e4b17023SJohn Marino#else /* X != 1 */ 3331*e4b17023SJohn Marino#if X == 2 3332*e4b17023SJohn Marino@dots{} 3333*e4b17023SJohn Marino#else /* X != 2 */ 3334*e4b17023SJohn Marino@dots{} 3335*e4b17023SJohn Marino#endif /* X != 2 */ 3336*e4b17023SJohn Marino#endif /* X != 1 */ 3337*e4b17023SJohn Marino@end smallexample 3338*e4b17023SJohn Marino 3339*e4b17023SJohn MarinoAnother conditional directive, @samp{#elif}, allows this to be 3340*e4b17023SJohn Marinoabbreviated as follows: 3341*e4b17023SJohn Marino 3342*e4b17023SJohn Marino@smallexample 3343*e4b17023SJohn Marino#if X == 1 3344*e4b17023SJohn Marino@dots{} 3345*e4b17023SJohn Marino#elif X == 2 3346*e4b17023SJohn Marino@dots{} 3347*e4b17023SJohn Marino#else /* X != 2 and X != 1*/ 3348*e4b17023SJohn Marino@dots{} 3349*e4b17023SJohn Marino#endif /* X != 2 and X != 1*/ 3350*e4b17023SJohn Marino@end smallexample 3351*e4b17023SJohn Marino 3352*e4b17023SJohn Marino@samp{#elif} stands for ``else if''. Like @samp{#else}, it goes in the 3353*e4b17023SJohn Marinomiddle of a conditional group and subdivides it; it does not require a 3354*e4b17023SJohn Marinomatching @samp{#endif} of its own. Like @samp{#if}, the @samp{#elif} 3355*e4b17023SJohn Marinodirective includes an expression to be tested. The text following the 3356*e4b17023SJohn Marino@samp{#elif} is processed only if the original @samp{#if}-condition 3357*e4b17023SJohn Marinofailed and the @samp{#elif} condition succeeds. 3358*e4b17023SJohn Marino 3359*e4b17023SJohn MarinoMore than one @samp{#elif} can go in the same conditional group. Then 3360*e4b17023SJohn Marinothe text after each @samp{#elif} is processed only if the @samp{#elif} 3361*e4b17023SJohn Marinocondition succeeds after the original @samp{#if} and all previous 3362*e4b17023SJohn Marino@samp{#elif} directives within it have failed. 3363*e4b17023SJohn Marino 3364*e4b17023SJohn Marino@samp{#else} is allowed after any number of @samp{#elif} directives, but 3365*e4b17023SJohn Marino@samp{#elif} may not follow @samp{#else}. 3366*e4b17023SJohn Marino 3367*e4b17023SJohn Marino@node Deleted Code 3368*e4b17023SJohn Marino@section Deleted Code 3369*e4b17023SJohn Marino@cindex commenting out code 3370*e4b17023SJohn Marino 3371*e4b17023SJohn MarinoIf you replace or delete a part of the program but want to keep the old 3372*e4b17023SJohn Marinocode around for future reference, you often cannot simply comment it 3373*e4b17023SJohn Marinoout. Block comments do not nest, so the first comment inside the old 3374*e4b17023SJohn Marinocode will end the commenting-out. The probable result is a flood of 3375*e4b17023SJohn Marinosyntax errors. 3376*e4b17023SJohn Marino 3377*e4b17023SJohn MarinoOne way to avoid this problem is to use an always-false conditional 3378*e4b17023SJohn Marinoinstead. For instance, put @code{#if 0} before the deleted code and 3379*e4b17023SJohn Marino@code{#endif} after it. This works even if the code being turned 3380*e4b17023SJohn Marinooff contains conditionals, but they must be entire conditionals 3381*e4b17023SJohn Marino(balanced @samp{#if} and @samp{#endif}). 3382*e4b17023SJohn Marino 3383*e4b17023SJohn MarinoSome people use @code{#ifdef notdef} instead. This is risky, because 3384*e4b17023SJohn Marino@code{notdef} might be accidentally defined as a macro, and then the 3385*e4b17023SJohn Marinoconditional would succeed. @code{#if 0} can be counted on to fail. 3386*e4b17023SJohn Marino 3387*e4b17023SJohn MarinoDo not use @code{#if 0} for comments which are not C code. Use a real 3388*e4b17023SJohn Marinocomment, instead. The interior of @code{#if 0} must consist of complete 3389*e4b17023SJohn Marinotokens; in particular, single-quote characters must balance. Comments 3390*e4b17023SJohn Marinooften contain unbalanced single-quote characters (known in English as 3391*e4b17023SJohn Marinoapostrophes). These confuse @code{#if 0}. They don't confuse 3392*e4b17023SJohn Marino@samp{/*}. 3393*e4b17023SJohn Marino 3394*e4b17023SJohn Marino@node Diagnostics 3395*e4b17023SJohn Marino@chapter Diagnostics 3396*e4b17023SJohn Marino@cindex diagnostic 3397*e4b17023SJohn Marino@cindex reporting errors 3398*e4b17023SJohn Marino@cindex reporting warnings 3399*e4b17023SJohn Marino 3400*e4b17023SJohn Marino@findex #error 3401*e4b17023SJohn MarinoThe directive @samp{#error} causes the preprocessor to report a fatal 3402*e4b17023SJohn Marinoerror. The tokens forming the rest of the line following @samp{#error} 3403*e4b17023SJohn Marinoare used as the error message. 3404*e4b17023SJohn Marino 3405*e4b17023SJohn MarinoYou would use @samp{#error} inside of a conditional that detects a 3406*e4b17023SJohn Marinocombination of parameters which you know the program does not properly 3407*e4b17023SJohn Marinosupport. For example, if you know that the program will not run 3408*e4b17023SJohn Marinoproperly on a VAX, you might write 3409*e4b17023SJohn Marino 3410*e4b17023SJohn Marino@smallexample 3411*e4b17023SJohn Marino@group 3412*e4b17023SJohn Marino#ifdef __vax__ 3413*e4b17023SJohn Marino#error "Won't work on VAXen. See comments at get_last_object." 3414*e4b17023SJohn Marino#endif 3415*e4b17023SJohn Marino@end group 3416*e4b17023SJohn Marino@end smallexample 3417*e4b17023SJohn Marino 3418*e4b17023SJohn MarinoIf you have several configuration parameters that must be set up by 3419*e4b17023SJohn Marinothe installation in a consistent way, you can use conditionals to detect 3420*e4b17023SJohn Marinoan inconsistency and report it with @samp{#error}. For example, 3421*e4b17023SJohn Marino 3422*e4b17023SJohn Marino@smallexample 3423*e4b17023SJohn Marino#if !defined(UNALIGNED_INT_ASM_OP) && defined(DWARF2_DEBUGGING_INFO) 3424*e4b17023SJohn Marino#error "DWARF2_DEBUGGING_INFO requires UNALIGNED_INT_ASM_OP." 3425*e4b17023SJohn Marino#endif 3426*e4b17023SJohn Marino@end smallexample 3427*e4b17023SJohn Marino 3428*e4b17023SJohn Marino@findex #warning 3429*e4b17023SJohn MarinoThe directive @samp{#warning} is like @samp{#error}, but causes the 3430*e4b17023SJohn Marinopreprocessor to issue a warning and continue preprocessing. The tokens 3431*e4b17023SJohn Marinofollowing @samp{#warning} are used as the warning message. 3432*e4b17023SJohn Marino 3433*e4b17023SJohn MarinoYou might use @samp{#warning} in obsolete header files, with a message 3434*e4b17023SJohn Marinodirecting the user to the header file which should be used instead. 3435*e4b17023SJohn Marino 3436*e4b17023SJohn MarinoNeither @samp{#error} nor @samp{#warning} macro-expands its argument. 3437*e4b17023SJohn MarinoInternal whitespace sequences are each replaced with a single space. 3438*e4b17023SJohn MarinoThe line must consist of complete tokens. It is wisest to make the 3439*e4b17023SJohn Marinoargument of these directives be a single string constant; this avoids 3440*e4b17023SJohn Marinoproblems with apostrophes and the like. 3441*e4b17023SJohn Marino 3442*e4b17023SJohn Marino@node Line Control 3443*e4b17023SJohn Marino@chapter Line Control 3444*e4b17023SJohn Marino@cindex line control 3445*e4b17023SJohn Marino 3446*e4b17023SJohn MarinoThe C preprocessor informs the C compiler of the location in your source 3447*e4b17023SJohn Marinocode where each token came from. Presently, this is just the file name 3448*e4b17023SJohn Marinoand line number. All the tokens resulting from macro expansion are 3449*e4b17023SJohn Marinoreported as having appeared on the line of the source file where the 3450*e4b17023SJohn Marinooutermost macro was used. We intend to be more accurate in the future. 3451*e4b17023SJohn Marino 3452*e4b17023SJohn MarinoIf you write a program which generates source code, such as the 3453*e4b17023SJohn Marino@command{bison} parser generator, you may want to adjust the preprocessor's 3454*e4b17023SJohn Marinonotion of the current file name and line number by hand. Parts of the 3455*e4b17023SJohn Marinooutput from @command{bison} are generated from scratch, other parts come 3456*e4b17023SJohn Marinofrom a standard parser file. The rest are copied verbatim from 3457*e4b17023SJohn Marino@command{bison}'s input. You would like compiler error messages and 3458*e4b17023SJohn Marinosymbolic debuggers to be able to refer to @code{bison}'s input file. 3459*e4b17023SJohn Marino 3460*e4b17023SJohn Marino@findex #line 3461*e4b17023SJohn Marino@command{bison} or any such program can arrange this by writing 3462*e4b17023SJohn Marino@samp{#line} directives into the output file. @samp{#line} is a 3463*e4b17023SJohn Marinodirective that specifies the original line number and source file name 3464*e4b17023SJohn Marinofor subsequent input in the current preprocessor input file. 3465*e4b17023SJohn Marino@samp{#line} has three variants: 3466*e4b17023SJohn Marino 3467*e4b17023SJohn Marino@table @code 3468*e4b17023SJohn Marino@item #line @var{linenum} 3469*e4b17023SJohn Marino@var{linenum} is a non-negative decimal integer constant. It specifies 3470*e4b17023SJohn Marinothe line number which should be reported for the following line of 3471*e4b17023SJohn Marinoinput. Subsequent lines are counted from @var{linenum}. 3472*e4b17023SJohn Marino 3473*e4b17023SJohn Marino@item #line @var{linenum} @var{filename} 3474*e4b17023SJohn Marino@var{linenum} is the same as for the first form, and has the same 3475*e4b17023SJohn Marinoeffect. In addition, @var{filename} is a string constant. The 3476*e4b17023SJohn Marinofollowing line and all subsequent lines are reported to come from the 3477*e4b17023SJohn Marinofile it specifies, until something else happens to change that. 3478*e4b17023SJohn Marino@var{filename} is interpreted according to the normal rules for a string 3479*e4b17023SJohn Marinoconstant: backslash escapes are interpreted. This is different from 3480*e4b17023SJohn Marino@samp{#include}. 3481*e4b17023SJohn Marino 3482*e4b17023SJohn MarinoPrevious versions of CPP did not interpret escapes in @samp{#line}; 3483*e4b17023SJohn Marinowe have changed it because the standard requires they be interpreted, 3484*e4b17023SJohn Marinoand most other compilers do. 3485*e4b17023SJohn Marino 3486*e4b17023SJohn Marino@item #line @var{anything else} 3487*e4b17023SJohn Marino@var{anything else} is checked for macro calls, which are expanded. 3488*e4b17023SJohn MarinoThe result should match one of the above two forms. 3489*e4b17023SJohn Marino@end table 3490*e4b17023SJohn Marino 3491*e4b17023SJohn Marino@samp{#line} directives alter the results of the @code{__FILE__} and 3492*e4b17023SJohn Marino@code{__LINE__} predefined macros from that point on. @xref{Standard 3493*e4b17023SJohn MarinoPredefined Macros}. They do not have any effect on @samp{#include}'s 3494*e4b17023SJohn Marinoidea of the directory containing the current file. This is a change 3495*e4b17023SJohn Marinofrom GCC 2.95. Previously, a file reading 3496*e4b17023SJohn Marino 3497*e4b17023SJohn Marino@smallexample 3498*e4b17023SJohn Marino#line 1 "../src/gram.y" 3499*e4b17023SJohn Marino#include "gram.h" 3500*e4b17023SJohn Marino@end smallexample 3501*e4b17023SJohn Marino 3502*e4b17023SJohn Marinowould search for @file{gram.h} in @file{../src}, then the @option{-I} 3503*e4b17023SJohn Marinochain; the directory containing the physical source file would not be 3504*e4b17023SJohn Marinosearched. In GCC 3.0 and later, the @samp{#include} is not affected by 3505*e4b17023SJohn Marinothe presence of a @samp{#line} referring to a different directory. 3506*e4b17023SJohn Marino 3507*e4b17023SJohn MarinoWe made this change because the old behavior caused problems when 3508*e4b17023SJohn Marinogenerated source files were transported between machines. For instance, 3509*e4b17023SJohn Marinoit is common practice to ship generated parsers with a source release, 3510*e4b17023SJohn Marinoso that people building the distribution do not need to have yacc or 3511*e4b17023SJohn MarinoBison installed. These files frequently have @samp{#line} directives 3512*e4b17023SJohn Marinoreferring to the directory tree of the system where the distribution was 3513*e4b17023SJohn Marinocreated. If GCC tries to search for headers in those directories, the 3514*e4b17023SJohn Marinobuild is likely to fail. 3515*e4b17023SJohn Marino 3516*e4b17023SJohn MarinoThe new behavior can cause failures too, if the generated file is not 3517*e4b17023SJohn Marinoin the same directory as its source and it attempts to include a header 3518*e4b17023SJohn Marinowhich would be visible searching from the directory containing the 3519*e4b17023SJohn Marinosource file. However, this problem is easily solved with an additional 3520*e4b17023SJohn Marino@option{-I} switch on the command line. The failures caused by the old 3521*e4b17023SJohn Marinosemantics could sometimes be corrected only by editing the generated 3522*e4b17023SJohn Marinofiles, which is difficult and error-prone. 3523*e4b17023SJohn Marino 3524*e4b17023SJohn Marino@node Pragmas 3525*e4b17023SJohn Marino@chapter Pragmas 3526*e4b17023SJohn Marino 3527*e4b17023SJohn MarinoThe @samp{#pragma} directive is the method specified by the C standard 3528*e4b17023SJohn Marinofor providing additional information to the compiler, beyond what is 3529*e4b17023SJohn Marinoconveyed in the language itself. Three forms of this directive 3530*e4b17023SJohn Marino(commonly known as @dfn{pragmas}) are specified by the 1999 C standard. 3531*e4b17023SJohn MarinoA C compiler is free to attach any meaning it likes to other pragmas. 3532*e4b17023SJohn Marino 3533*e4b17023SJohn MarinoGCC has historically preferred to use extensions to the syntax of the 3534*e4b17023SJohn Marinolanguage, such as @code{__attribute__}, for this purpose. However, GCC 3535*e4b17023SJohn Marinodoes define a few pragmas of its own. These mostly have effects on the 3536*e4b17023SJohn Marinoentire translation unit or source file. 3537*e4b17023SJohn Marino 3538*e4b17023SJohn MarinoIn GCC version 3, all GNU-defined, supported pragmas have been given a 3539*e4b17023SJohn Marino@code{GCC} prefix. This is in line with the @code{STDC} prefix on all 3540*e4b17023SJohn Marinopragmas defined by C99. For backward compatibility, pragmas which were 3541*e4b17023SJohn Marinorecognized by previous versions are still recognized without the 3542*e4b17023SJohn Marino@code{GCC} prefix, but that usage is deprecated. Some older pragmas are 3543*e4b17023SJohn Marinodeprecated in their entirety. They are not recognized with the 3544*e4b17023SJohn Marino@code{GCC} prefix. @xref{Obsolete Features}. 3545*e4b17023SJohn Marino 3546*e4b17023SJohn Marino@cindex @code{_Pragma} 3547*e4b17023SJohn MarinoC99 introduces the @code{@w{_Pragma}} operator. This feature addresses a 3548*e4b17023SJohn Marinomajor problem with @samp{#pragma}: being a directive, it cannot be 3549*e4b17023SJohn Marinoproduced as the result of macro expansion. @code{@w{_Pragma}} is an 3550*e4b17023SJohn Marinooperator, much like @code{sizeof} or @code{defined}, and can be embedded 3551*e4b17023SJohn Marinoin a macro. 3552*e4b17023SJohn Marino 3553*e4b17023SJohn MarinoIts syntax is @code{@w{_Pragma (@var{string-literal})}}, where 3554*e4b17023SJohn Marino@var{string-literal} can be either a normal or wide-character string 3555*e4b17023SJohn Marinoliteral. It is destringized, by replacing all @samp{\\} with a single 3556*e4b17023SJohn Marino@samp{\} and all @samp{\"} with a @samp{"}. The result is then 3557*e4b17023SJohn Marinoprocessed as if it had appeared as the right hand side of a 3558*e4b17023SJohn Marino@samp{#pragma} directive. For example, 3559*e4b17023SJohn Marino 3560*e4b17023SJohn Marino@smallexample 3561*e4b17023SJohn Marino_Pragma ("GCC dependency \"parse.y\"") 3562*e4b17023SJohn Marino@end smallexample 3563*e4b17023SJohn Marino 3564*e4b17023SJohn Marino@noindent 3565*e4b17023SJohn Marinohas the same effect as @code{#pragma GCC dependency "parse.y"}. The 3566*e4b17023SJohn Marinosame effect could be achieved using macros, for example 3567*e4b17023SJohn Marino 3568*e4b17023SJohn Marino@smallexample 3569*e4b17023SJohn Marino#define DO_PRAGMA(x) _Pragma (#x) 3570*e4b17023SJohn MarinoDO_PRAGMA (GCC dependency "parse.y") 3571*e4b17023SJohn Marino@end smallexample 3572*e4b17023SJohn Marino 3573*e4b17023SJohn MarinoThe standard is unclear on where a @code{_Pragma} operator can appear. 3574*e4b17023SJohn MarinoThe preprocessor does not accept it within a preprocessing conditional 3575*e4b17023SJohn Marinodirective like @samp{#if}. To be safe, you are probably best keeping it 3576*e4b17023SJohn Marinoout of directives other than @samp{#define}, and putting it on a line of 3577*e4b17023SJohn Marinoits own. 3578*e4b17023SJohn Marino 3579*e4b17023SJohn MarinoThis manual documents the pragmas which are meaningful to the 3580*e4b17023SJohn Marinopreprocessor itself. Other pragmas are meaningful to the C or C++ 3581*e4b17023SJohn Marinocompilers. They are documented in the GCC manual. 3582*e4b17023SJohn Marino 3583*e4b17023SJohn MarinoGCC plugins may provide their own pragmas. 3584*e4b17023SJohn Marino 3585*e4b17023SJohn Marino@ftable @code 3586*e4b17023SJohn Marino@item #pragma GCC dependency 3587*e4b17023SJohn Marino@code{#pragma GCC dependency} allows you to check the relative dates of 3588*e4b17023SJohn Marinothe current file and another file. If the other file is more recent than 3589*e4b17023SJohn Marinothe current file, a warning is issued. This is useful if the current 3590*e4b17023SJohn Marinofile is derived from the other file, and should be regenerated. The 3591*e4b17023SJohn Marinoother file is searched for using the normal include search path. 3592*e4b17023SJohn MarinoOptional trailing text can be used to give more information in the 3593*e4b17023SJohn Marinowarning message. 3594*e4b17023SJohn Marino 3595*e4b17023SJohn Marino@smallexample 3596*e4b17023SJohn Marino#pragma GCC dependency "parse.y" 3597*e4b17023SJohn Marino#pragma GCC dependency "/usr/include/time.h" rerun fixincludes 3598*e4b17023SJohn Marino@end smallexample 3599*e4b17023SJohn Marino 3600*e4b17023SJohn Marino@item #pragma GCC poison 3601*e4b17023SJohn MarinoSometimes, there is an identifier that you want to remove completely 3602*e4b17023SJohn Marinofrom your program, and make sure that it never creeps back in. To 3603*e4b17023SJohn Marinoenforce this, you can @dfn{poison} the identifier with this pragma. 3604*e4b17023SJohn Marino@code{#pragma GCC poison} is followed by a list of identifiers to 3605*e4b17023SJohn Marinopoison. If any of those identifiers appears anywhere in the source 3606*e4b17023SJohn Marinoafter the directive, it is a hard error. For example, 3607*e4b17023SJohn Marino 3608*e4b17023SJohn Marino@smallexample 3609*e4b17023SJohn Marino#pragma GCC poison printf sprintf fprintf 3610*e4b17023SJohn Marinosprintf(some_string, "hello"); 3611*e4b17023SJohn Marino@end smallexample 3612*e4b17023SJohn Marino 3613*e4b17023SJohn Marino@noindent 3614*e4b17023SJohn Marinowill produce an error. 3615*e4b17023SJohn Marino 3616*e4b17023SJohn MarinoIf a poisoned identifier appears as part of the expansion of a macro 3617*e4b17023SJohn Marinowhich was defined before the identifier was poisoned, it will @emph{not} 3618*e4b17023SJohn Marinocause an error. This lets you poison an identifier without worrying 3619*e4b17023SJohn Marinoabout system headers defining macros that use it. 3620*e4b17023SJohn Marino 3621*e4b17023SJohn MarinoFor example, 3622*e4b17023SJohn Marino 3623*e4b17023SJohn Marino@smallexample 3624*e4b17023SJohn Marino#define strrchr rindex 3625*e4b17023SJohn Marino#pragma GCC poison rindex 3626*e4b17023SJohn Marinostrrchr(some_string, 'h'); 3627*e4b17023SJohn Marino@end smallexample 3628*e4b17023SJohn Marino 3629*e4b17023SJohn Marino@noindent 3630*e4b17023SJohn Marinowill not produce an error. 3631*e4b17023SJohn Marino 3632*e4b17023SJohn Marino@item #pragma GCC system_header 3633*e4b17023SJohn MarinoThis pragma takes no arguments. It causes the rest of the code in the 3634*e4b17023SJohn Marinocurrent file to be treated as if it came from a system header. 3635*e4b17023SJohn Marino@xref{System Headers}. 3636*e4b17023SJohn Marino 3637*e4b17023SJohn Marino@end ftable 3638*e4b17023SJohn Marino 3639*e4b17023SJohn Marino@node Other Directives 3640*e4b17023SJohn Marino@chapter Other Directives 3641*e4b17023SJohn Marino 3642*e4b17023SJohn Marino@findex #ident 3643*e4b17023SJohn Marino@findex #sccs 3644*e4b17023SJohn MarinoThe @samp{#ident} directive takes one argument, a string constant. On 3645*e4b17023SJohn Marinosome systems, that string constant is copied into a special segment of 3646*e4b17023SJohn Marinothe object file. On other systems, the directive is ignored. The 3647*e4b17023SJohn Marino@samp{#sccs} directive is a synonym for @samp{#ident}. 3648*e4b17023SJohn Marino 3649*e4b17023SJohn MarinoThese directives are not part of the C standard, but they are not 3650*e4b17023SJohn Marinoofficial GNU extensions either. What historical information we have 3651*e4b17023SJohn Marinobeen able to find, suggests they originated with System V@. 3652*e4b17023SJohn Marino 3653*e4b17023SJohn Marino@cindex null directive 3654*e4b17023SJohn MarinoThe @dfn{null directive} consists of a @samp{#} followed by a newline, 3655*e4b17023SJohn Marinowith only whitespace (including comments) in between. A null directive 3656*e4b17023SJohn Marinois understood as a preprocessing directive but has no effect on the 3657*e4b17023SJohn Marinopreprocessor output. The primary significance of the existence of the 3658*e4b17023SJohn Marinonull directive is that an input line consisting of just a @samp{#} will 3659*e4b17023SJohn Marinoproduce no output, rather than a line of output containing just a 3660*e4b17023SJohn Marino@samp{#}. Supposedly some old C programs contain such lines. 3661*e4b17023SJohn Marino 3662*e4b17023SJohn Marino@node Preprocessor Output 3663*e4b17023SJohn Marino@chapter Preprocessor Output 3664*e4b17023SJohn Marino 3665*e4b17023SJohn MarinoWhen the C preprocessor is used with the C, C++, or Objective-C 3666*e4b17023SJohn Marinocompilers, it is integrated into the compiler and communicates a stream 3667*e4b17023SJohn Marinoof binary tokens directly to the compiler's parser. However, it can 3668*e4b17023SJohn Marinoalso be used in the more conventional standalone mode, where it produces 3669*e4b17023SJohn Marinotextual output. 3670*e4b17023SJohn Marino@c FIXME: Document the library interface. 3671*e4b17023SJohn Marino 3672*e4b17023SJohn Marino@cindex output format 3673*e4b17023SJohn MarinoThe output from the C preprocessor looks much like the input, except 3674*e4b17023SJohn Marinothat all preprocessing directive lines have been replaced with blank 3675*e4b17023SJohn Marinolines and all comments with spaces. Long runs of blank lines are 3676*e4b17023SJohn Marinodiscarded. 3677*e4b17023SJohn Marino 3678*e4b17023SJohn MarinoThe ISO standard specifies that it is implementation defined whether a 3679*e4b17023SJohn Marinopreprocessor preserves whitespace between tokens, or replaces it with 3680*e4b17023SJohn Marinoe.g.@: a single space. In GNU CPP, whitespace between tokens is collapsed 3681*e4b17023SJohn Marinoto become a single space, with the exception that the first token on a 3682*e4b17023SJohn Marinonon-directive line is preceded with sufficient spaces that it appears in 3683*e4b17023SJohn Marinothe same column in the preprocessed output that it appeared in the 3684*e4b17023SJohn Marinooriginal source file. This is so the output is easy to read. 3685*e4b17023SJohn Marino@xref{Differences from previous versions}. CPP does not insert any 3686*e4b17023SJohn Marinowhitespace where there was none in the original source, except where 3687*e4b17023SJohn Marinonecessary to prevent an accidental token paste. 3688*e4b17023SJohn Marino 3689*e4b17023SJohn Marino@cindex linemarkers 3690*e4b17023SJohn MarinoSource file name and line number information is conveyed by lines 3691*e4b17023SJohn Marinoof the form 3692*e4b17023SJohn Marino 3693*e4b17023SJohn Marino@smallexample 3694*e4b17023SJohn Marino# @var{linenum} @var{filename} @var{flags} 3695*e4b17023SJohn Marino@end smallexample 3696*e4b17023SJohn Marino 3697*e4b17023SJohn Marino@noindent 3698*e4b17023SJohn MarinoThese are called @dfn{linemarkers}. They are inserted as needed into 3699*e4b17023SJohn Marinothe output (but never within a string or character constant). They mean 3700*e4b17023SJohn Marinothat the following line originated in file @var{filename} at line 3701*e4b17023SJohn Marino@var{linenum}. @var{filename} will never contain any non-printing 3702*e4b17023SJohn Marinocharacters; they are replaced with octal escape sequences. 3703*e4b17023SJohn Marino 3704*e4b17023SJohn MarinoAfter the file name comes zero or more flags, which are @samp{1}, 3705*e4b17023SJohn Marino@samp{2}, @samp{3}, or @samp{4}. If there are multiple flags, spaces 3706*e4b17023SJohn Marinoseparate them. Here is what the flags mean: 3707*e4b17023SJohn Marino 3708*e4b17023SJohn Marino@table @samp 3709*e4b17023SJohn Marino@item 1 3710*e4b17023SJohn MarinoThis indicates the start of a new file. 3711*e4b17023SJohn Marino@item 2 3712*e4b17023SJohn MarinoThis indicates returning to a file (after having included another file). 3713*e4b17023SJohn Marino@item 3 3714*e4b17023SJohn MarinoThis indicates that the following text comes from a system header file, 3715*e4b17023SJohn Marinoso certain warnings should be suppressed. 3716*e4b17023SJohn Marino@item 4 3717*e4b17023SJohn MarinoThis indicates that the following text should be treated as being 3718*e4b17023SJohn Marinowrapped in an implicit @code{extern "C"} block. 3719*e4b17023SJohn Marino@c maybe cross reference NO_IMPLICIT_EXTERN_C 3720*e4b17023SJohn Marino@end table 3721*e4b17023SJohn Marino 3722*e4b17023SJohn MarinoAs an extension, the preprocessor accepts linemarkers in non-assembler 3723*e4b17023SJohn Marinoinput files. They are treated like the corresponding @samp{#line} 3724*e4b17023SJohn Marinodirective, (@pxref{Line Control}), except that trailing flags are 3725*e4b17023SJohn Marinopermitted, and are interpreted with the meanings described above. If 3726*e4b17023SJohn Marinomultiple flags are given, they must be in ascending order. 3727*e4b17023SJohn Marino 3728*e4b17023SJohn MarinoSome directives may be duplicated in the output of the preprocessor. 3729*e4b17023SJohn MarinoThese are @samp{#ident} (always), @samp{#pragma} (only if the 3730*e4b17023SJohn Marinopreprocessor does not handle the pragma itself), and @samp{#define} and 3731*e4b17023SJohn Marino@samp{#undef} (with certain debugging options). If this happens, the 3732*e4b17023SJohn Marino@samp{#} of the directive will always be in the first column, and there 3733*e4b17023SJohn Marinowill be no space between the @samp{#} and the directive name. If macro 3734*e4b17023SJohn Marinoexpansion happens to generate tokens which might be mistaken for a 3735*e4b17023SJohn Marinoduplicated directive, a space will be inserted between the @samp{#} and 3736*e4b17023SJohn Marinothe directive name. 3737*e4b17023SJohn Marino 3738*e4b17023SJohn Marino@node Traditional Mode 3739*e4b17023SJohn Marino@chapter Traditional Mode 3740*e4b17023SJohn Marino 3741*e4b17023SJohn MarinoTraditional (pre-standard) C preprocessing is rather different from 3742*e4b17023SJohn Marinothe preprocessing specified by the standard. When GCC is given the 3743*e4b17023SJohn Marino@option{-traditional-cpp} option, it attempts to emulate a traditional 3744*e4b17023SJohn Marinopreprocessor. 3745*e4b17023SJohn Marino 3746*e4b17023SJohn MarinoGCC versions 3.2 and later only support traditional mode semantics in 3747*e4b17023SJohn Marinothe preprocessor, and not in the compiler front ends. This chapter 3748*e4b17023SJohn Marinooutlines the traditional preprocessor semantics we implemented. 3749*e4b17023SJohn Marino 3750*e4b17023SJohn MarinoThe implementation does not correspond precisely to the behavior of 3751*e4b17023SJohn Marinoearlier versions of GCC, nor to any true traditional preprocessor. 3752*e4b17023SJohn MarinoAfter all, inconsistencies among traditional implementations were a 3753*e4b17023SJohn Marinomajor motivation for C standardization. However, we intend that it 3754*e4b17023SJohn Marinoshould be compatible with true traditional preprocessors in all ways 3755*e4b17023SJohn Marinothat actually matter. 3756*e4b17023SJohn Marino 3757*e4b17023SJohn Marino@menu 3758*e4b17023SJohn Marino* Traditional lexical analysis:: 3759*e4b17023SJohn Marino* Traditional macros:: 3760*e4b17023SJohn Marino* Traditional miscellany:: 3761*e4b17023SJohn Marino* Traditional warnings:: 3762*e4b17023SJohn Marino@end menu 3763*e4b17023SJohn Marino 3764*e4b17023SJohn Marino@node Traditional lexical analysis 3765*e4b17023SJohn Marino@section Traditional lexical analysis 3766*e4b17023SJohn Marino 3767*e4b17023SJohn MarinoThe traditional preprocessor does not decompose its input into tokens 3768*e4b17023SJohn Marinothe same way a standards-conforming preprocessor does. The input is 3769*e4b17023SJohn Marinosimply treated as a stream of text with minimal internal form. 3770*e4b17023SJohn Marino 3771*e4b17023SJohn MarinoThis implementation does not treat trigraphs (@pxref{trigraphs}) 3772*e4b17023SJohn Marinospecially since they were an invention of the standards committee. It 3773*e4b17023SJohn Marinohandles arbitrarily-positioned escaped newlines properly and splices 3774*e4b17023SJohn Marinothe lines as you would expect; many traditional preprocessors did not 3775*e4b17023SJohn Marinodo this. 3776*e4b17023SJohn Marino 3777*e4b17023SJohn MarinoThe form of horizontal whitespace in the input file is preserved in 3778*e4b17023SJohn Marinothe output. In particular, hard tabs remain hard tabs. This can be 3779*e4b17023SJohn Marinouseful if, for example, you are preprocessing a Makefile. 3780*e4b17023SJohn Marino 3781*e4b17023SJohn MarinoTraditional CPP only recognizes C-style block comments, and treats the 3782*e4b17023SJohn Marino@samp{/*} sequence as introducing a comment only if it lies outside 3783*e4b17023SJohn Marinoquoted text. Quoted text is introduced by the usual single and double 3784*e4b17023SJohn Marinoquotes, and also by an initial @samp{<} in a @code{#include} 3785*e4b17023SJohn Marinodirective. 3786*e4b17023SJohn Marino 3787*e4b17023SJohn MarinoTraditionally, comments are completely removed and are not replaced 3788*e4b17023SJohn Marinowith a space. Since a traditional compiler does its own tokenization 3789*e4b17023SJohn Marinoof the output of the preprocessor, this means that comments can 3790*e4b17023SJohn Marinoeffectively be used as token paste operators. However, comments 3791*e4b17023SJohn Marinobehave like separators for text handled by the preprocessor itself, 3792*e4b17023SJohn Marinosince it doesn't re-lex its input. For example, in 3793*e4b17023SJohn Marino 3794*e4b17023SJohn Marino@smallexample 3795*e4b17023SJohn Marino#if foo/**/bar 3796*e4b17023SJohn Marino@end smallexample 3797*e4b17023SJohn Marino 3798*e4b17023SJohn Marino@noindent 3799*e4b17023SJohn Marino@samp{foo} and @samp{bar} are distinct identifiers and expanded 3800*e4b17023SJohn Marinoseparately if they happen to be macros. In other words, this 3801*e4b17023SJohn Marinodirective is equivalent to 3802*e4b17023SJohn Marino 3803*e4b17023SJohn Marino@smallexample 3804*e4b17023SJohn Marino#if foo bar 3805*e4b17023SJohn Marino@end smallexample 3806*e4b17023SJohn Marino 3807*e4b17023SJohn Marino@noindent 3808*e4b17023SJohn Marinorather than 3809*e4b17023SJohn Marino 3810*e4b17023SJohn Marino@smallexample 3811*e4b17023SJohn Marino#if foobar 3812*e4b17023SJohn Marino@end smallexample 3813*e4b17023SJohn Marino 3814*e4b17023SJohn MarinoGenerally speaking, in traditional mode an opening quote need not have 3815*e4b17023SJohn Marinoa matching closing quote. In particular, a macro may be defined with 3816*e4b17023SJohn Marinoreplacement text that contains an unmatched quote. Of course, if you 3817*e4b17023SJohn Marinoattempt to compile preprocessed output containing an unmatched quote 3818*e4b17023SJohn Marinoyou will get a syntax error. 3819*e4b17023SJohn Marino 3820*e4b17023SJohn MarinoHowever, all preprocessing directives other than @code{#define} 3821*e4b17023SJohn Marinorequire matching quotes. For example: 3822*e4b17023SJohn Marino 3823*e4b17023SJohn Marino@smallexample 3824*e4b17023SJohn Marino#define m This macro's fine and has an unmatched quote 3825*e4b17023SJohn Marino"/* This is not a comment. */ 3826*e4b17023SJohn Marino/* @r{This is a comment. The following #include directive 3827*e4b17023SJohn Marino is ill-formed.} */ 3828*e4b17023SJohn Marino#include <stdio.h 3829*e4b17023SJohn Marino@end smallexample 3830*e4b17023SJohn Marino 3831*e4b17023SJohn MarinoJust as for the ISO preprocessor, what would be a closing quote can be 3832*e4b17023SJohn Marinoescaped with a backslash to prevent the quoted text from closing. 3833*e4b17023SJohn Marino 3834*e4b17023SJohn Marino@node Traditional macros 3835*e4b17023SJohn Marino@section Traditional macros 3836*e4b17023SJohn Marino 3837*e4b17023SJohn MarinoThe major difference between traditional and ISO macros is that the 3838*e4b17023SJohn Marinoformer expand to text rather than to a token sequence. CPP removes 3839*e4b17023SJohn Marinoall leading and trailing horizontal whitespace from a macro's 3840*e4b17023SJohn Marinoreplacement text before storing it, but preserves the form of internal 3841*e4b17023SJohn Marinowhitespace. 3842*e4b17023SJohn Marino 3843*e4b17023SJohn MarinoOne consequence is that it is legitimate for the replacement text to 3844*e4b17023SJohn Marinocontain an unmatched quote (@pxref{Traditional lexical analysis}). An 3845*e4b17023SJohn Marinounclosed string or character constant continues into the text 3846*e4b17023SJohn Marinofollowing the macro call. Similarly, the text at the end of a macro's 3847*e4b17023SJohn Marinoexpansion can run together with the text after the macro invocation to 3848*e4b17023SJohn Marinoproduce a single token. 3849*e4b17023SJohn Marino 3850*e4b17023SJohn MarinoNormally comments are removed from the replacement text after the 3851*e4b17023SJohn Marinomacro is expanded, but if the @option{-CC} option is passed on the 3852*e4b17023SJohn Marinocommand line comments are preserved. (In fact, the current 3853*e4b17023SJohn Marinoimplementation removes comments even before saving the macro 3854*e4b17023SJohn Marinoreplacement text, but it careful to do it in such a way that the 3855*e4b17023SJohn Marinoobserved effect is identical even in the function-like macro case.) 3856*e4b17023SJohn Marino 3857*e4b17023SJohn MarinoThe ISO stringification operator @samp{#} and token paste operator 3858*e4b17023SJohn Marino@samp{##} have no special meaning. As explained later, an effect 3859*e4b17023SJohn Marinosimilar to these operators can be obtained in a different way. Macro 3860*e4b17023SJohn Marinonames that are embedded in quotes, either from the main file or after 3861*e4b17023SJohn Marinomacro replacement, do not expand. 3862*e4b17023SJohn Marino 3863*e4b17023SJohn MarinoCPP replaces an unquoted object-like macro name with its replacement 3864*e4b17023SJohn Marinotext, and then rescans it for further macros to replace. Unlike 3865*e4b17023SJohn Marinostandard macro expansion, traditional macro expansion has no provision 3866*e4b17023SJohn Marinoto prevent recursion. If an object-like macro appears unquoted in its 3867*e4b17023SJohn Marinoreplacement text, it will be replaced again during the rescan pass, 3868*e4b17023SJohn Marinoand so on @emph{ad infinitum}. GCC detects when it is expanding 3869*e4b17023SJohn Marinorecursive macros, emits an error message, and continues after the 3870*e4b17023SJohn Marinooffending macro invocation. 3871*e4b17023SJohn Marino 3872*e4b17023SJohn Marino@smallexample 3873*e4b17023SJohn Marino#define PLUS + 3874*e4b17023SJohn Marino#define INC(x) PLUS+x 3875*e4b17023SJohn MarinoINC(foo); 3876*e4b17023SJohn Marino @expansion{} ++foo; 3877*e4b17023SJohn Marino@end smallexample 3878*e4b17023SJohn Marino 3879*e4b17023SJohn MarinoFunction-like macros are similar in form but quite different in 3880*e4b17023SJohn Marinobehavior to their ISO counterparts. Their arguments are contained 3881*e4b17023SJohn Marinowithin parentheses, are comma-separated, and can cross physical lines. 3882*e4b17023SJohn MarinoCommas within nested parentheses are not treated as argument 3883*e4b17023SJohn Marinoseparators. Similarly, a quote in an argument cannot be left 3884*e4b17023SJohn Marinounclosed; a following comma or parenthesis that comes before the 3885*e4b17023SJohn Marinoclosing quote is treated like any other character. There is no 3886*e4b17023SJohn Marinofacility for handling variadic macros. 3887*e4b17023SJohn Marino 3888*e4b17023SJohn MarinoThis implementation removes all comments from macro arguments, unless 3889*e4b17023SJohn Marinothe @option{-C} option is given. The form of all other horizontal 3890*e4b17023SJohn Marinowhitespace in arguments is preserved, including leading and trailing 3891*e4b17023SJohn Marinowhitespace. In particular 3892*e4b17023SJohn Marino 3893*e4b17023SJohn Marino@smallexample 3894*e4b17023SJohn Marinof( ) 3895*e4b17023SJohn Marino@end smallexample 3896*e4b17023SJohn Marino 3897*e4b17023SJohn Marino@noindent 3898*e4b17023SJohn Marinois treated as an invocation of the macro @samp{f} with a single 3899*e4b17023SJohn Marinoargument consisting of a single space. If you want to invoke a 3900*e4b17023SJohn Marinofunction-like macro that takes no arguments, you must not leave any 3901*e4b17023SJohn Marinowhitespace between the parentheses. 3902*e4b17023SJohn Marino 3903*e4b17023SJohn MarinoIf a macro argument crosses a new line, the new line is replaced with 3904*e4b17023SJohn Marinoa space when forming the argument. If the previous line contained an 3905*e4b17023SJohn Marinounterminated quote, the following line inherits the quoted state. 3906*e4b17023SJohn Marino 3907*e4b17023SJohn MarinoTraditional preprocessors replace parameters in the replacement text 3908*e4b17023SJohn Marinowith their arguments regardless of whether the parameters are within 3909*e4b17023SJohn Marinoquotes or not. This provides a way to stringize arguments. For 3910*e4b17023SJohn Marinoexample 3911*e4b17023SJohn Marino 3912*e4b17023SJohn Marino@smallexample 3913*e4b17023SJohn Marino#define str(x) "x" 3914*e4b17023SJohn Marinostr(/* @r{A comment} */some text ) 3915*e4b17023SJohn Marino @expansion{} "some text " 3916*e4b17023SJohn Marino@end smallexample 3917*e4b17023SJohn Marino 3918*e4b17023SJohn Marino@noindent 3919*e4b17023SJohn MarinoNote that the comment is removed, but that the trailing space is 3920*e4b17023SJohn Marinopreserved. Here is an example of using a comment to effect token 3921*e4b17023SJohn Marinopasting. 3922*e4b17023SJohn Marino 3923*e4b17023SJohn Marino@smallexample 3924*e4b17023SJohn Marino#define suffix(x) foo_/**/x 3925*e4b17023SJohn Marinosuffix(bar) 3926*e4b17023SJohn Marino @expansion{} foo_bar 3927*e4b17023SJohn Marino@end smallexample 3928*e4b17023SJohn Marino 3929*e4b17023SJohn Marino@node Traditional miscellany 3930*e4b17023SJohn Marino@section Traditional miscellany 3931*e4b17023SJohn Marino 3932*e4b17023SJohn MarinoHere are some things to be aware of when using the traditional 3933*e4b17023SJohn Marinopreprocessor. 3934*e4b17023SJohn Marino 3935*e4b17023SJohn Marino@itemize @bullet 3936*e4b17023SJohn Marino@item 3937*e4b17023SJohn MarinoPreprocessing directives are recognized only when their leading 3938*e4b17023SJohn Marino@samp{#} appears in the first column. There can be no whitespace 3939*e4b17023SJohn Marinobetween the beginning of the line and the @samp{#}, but whitespace can 3940*e4b17023SJohn Marinofollow the @samp{#}. 3941*e4b17023SJohn Marino 3942*e4b17023SJohn Marino@item 3943*e4b17023SJohn MarinoA true traditional C preprocessor does not recognize @samp{#error} or 3944*e4b17023SJohn Marino@samp{#pragma}, and may not recognize @samp{#elif}. CPP supports all 3945*e4b17023SJohn Marinothe directives in traditional mode that it supports in ISO mode, 3946*e4b17023SJohn Marinoincluding extensions, with the exception that the effects of 3947*e4b17023SJohn Marino@samp{#pragma GCC poison} are undefined. 3948*e4b17023SJohn Marino 3949*e4b17023SJohn Marino@item 3950*e4b17023SJohn Marino__STDC__ is not defined. 3951*e4b17023SJohn Marino 3952*e4b17023SJohn Marino@item 3953*e4b17023SJohn MarinoIf you use digraphs the behavior is undefined. 3954*e4b17023SJohn Marino 3955*e4b17023SJohn Marino@item 3956*e4b17023SJohn MarinoIf a line that looks like a directive appears within macro arguments, 3957*e4b17023SJohn Marinothe behavior is undefined. 3958*e4b17023SJohn Marino 3959*e4b17023SJohn Marino@end itemize 3960*e4b17023SJohn Marino 3961*e4b17023SJohn Marino@node Traditional warnings 3962*e4b17023SJohn Marino@section Traditional warnings 3963*e4b17023SJohn MarinoYou can request warnings about features that did not exist, or worked 3964*e4b17023SJohn Marinodifferently, in traditional C with the @option{-Wtraditional} option. 3965*e4b17023SJohn MarinoGCC does not warn about features of ISO C which you must use when you 3966*e4b17023SJohn Marinoare using a conforming compiler, such as the @samp{#} and @samp{##} 3967*e4b17023SJohn Marinooperators. 3968*e4b17023SJohn Marino 3969*e4b17023SJohn MarinoPresently @option{-Wtraditional} warns about: 3970*e4b17023SJohn Marino 3971*e4b17023SJohn Marino@itemize @bullet 3972*e4b17023SJohn Marino@item 3973*e4b17023SJohn MarinoMacro parameters that appear within string literals in the macro body. 3974*e4b17023SJohn MarinoIn traditional C macro replacement takes place within string literals, 3975*e4b17023SJohn Marinobut does not in ISO C@. 3976*e4b17023SJohn Marino 3977*e4b17023SJohn Marino@item 3978*e4b17023SJohn MarinoIn traditional C, some preprocessor directives did not exist. 3979*e4b17023SJohn MarinoTraditional preprocessors would only consider a line to be a directive 3980*e4b17023SJohn Marinoif the @samp{#} appeared in column 1 on the line. Therefore 3981*e4b17023SJohn Marino@option{-Wtraditional} warns about directives that traditional C 3982*e4b17023SJohn Marinounderstands but would ignore because the @samp{#} does not appear as the 3983*e4b17023SJohn Marinofirst character on the line. It also suggests you hide directives like 3984*e4b17023SJohn Marino@samp{#pragma} not understood by traditional C by indenting them. Some 3985*e4b17023SJohn Marinotraditional implementations would not recognize @samp{#elif}, so it 3986*e4b17023SJohn Marinosuggests avoiding it altogether. 3987*e4b17023SJohn Marino 3988*e4b17023SJohn Marino@item 3989*e4b17023SJohn MarinoA function-like macro that appears without an argument list. In some 3990*e4b17023SJohn Marinotraditional preprocessors this was an error. In ISO C it merely means 3991*e4b17023SJohn Marinothat the macro is not expanded. 3992*e4b17023SJohn Marino 3993*e4b17023SJohn Marino@item 3994*e4b17023SJohn MarinoThe unary plus operator. This did not exist in traditional C@. 3995*e4b17023SJohn Marino 3996*e4b17023SJohn Marino@item 3997*e4b17023SJohn MarinoThe @samp{U} and @samp{LL} integer constant suffixes, which were not 3998*e4b17023SJohn Marinoavailable in traditional C@. (Traditional C does support the @samp{L} 3999*e4b17023SJohn Marinosuffix for simple long integer constants.) You are not warned about 4000*e4b17023SJohn Marinouses of these suffixes in macros defined in system headers. For 4001*e4b17023SJohn Marinoinstance, @code{UINT_MAX} may well be defined as @code{4294967295U}, but 4002*e4b17023SJohn Marinoyou will not be warned if you use @code{UINT_MAX}. 4003*e4b17023SJohn Marino 4004*e4b17023SJohn MarinoYou can usually avoid the warning, and the related warning about 4005*e4b17023SJohn Marinoconstants which are so large that they are unsigned, by writing the 4006*e4b17023SJohn Marinointeger constant in question in hexadecimal, with no U suffix. Take 4007*e4b17023SJohn Marinocare, though, because this gives the wrong result in exotic cases. 4008*e4b17023SJohn Marino@end itemize 4009*e4b17023SJohn Marino 4010*e4b17023SJohn Marino@node Implementation Details 4011*e4b17023SJohn Marino@chapter Implementation Details 4012*e4b17023SJohn Marino 4013*e4b17023SJohn MarinoHere we document details of how the preprocessor's implementation 4014*e4b17023SJohn Marinoaffects its user-visible behavior. You should try to avoid undue 4015*e4b17023SJohn Marinoreliance on behavior described here, as it is possible that it will 4016*e4b17023SJohn Marinochange subtly in future implementations. 4017*e4b17023SJohn Marino 4018*e4b17023SJohn MarinoAlso documented here are obsolete features and changes from previous 4019*e4b17023SJohn Marinoversions of CPP@. 4020*e4b17023SJohn Marino 4021*e4b17023SJohn Marino@menu 4022*e4b17023SJohn Marino* Implementation-defined behavior:: 4023*e4b17023SJohn Marino* Implementation limits:: 4024*e4b17023SJohn Marino* Obsolete Features:: 4025*e4b17023SJohn Marino* Differences from previous versions:: 4026*e4b17023SJohn Marino@end menu 4027*e4b17023SJohn Marino 4028*e4b17023SJohn Marino@node Implementation-defined behavior 4029*e4b17023SJohn Marino@section Implementation-defined behavior 4030*e4b17023SJohn Marino@cindex implementation-defined behavior 4031*e4b17023SJohn Marino 4032*e4b17023SJohn MarinoThis is how CPP behaves in all the cases which the C standard 4033*e4b17023SJohn Marinodescribes as @dfn{implementation-defined}. This term means that the 4034*e4b17023SJohn Marinoimplementation is free to do what it likes, but must document its choice 4035*e4b17023SJohn Marinoand stick to it. 4036*e4b17023SJohn Marino@c FIXME: Check the C++ standard for more implementation-defined stuff. 4037*e4b17023SJohn Marino 4038*e4b17023SJohn Marino@itemize @bullet 4039*e4b17023SJohn Marino@need 1000 4040*e4b17023SJohn Marino@item The mapping of physical source file multi-byte characters to the 4041*e4b17023SJohn Marinoexecution character set. 4042*e4b17023SJohn Marino 4043*e4b17023SJohn MarinoThe input character set can be specified using the 4044*e4b17023SJohn Marino@option{-finput-charset} option, while the execution character set may 4045*e4b17023SJohn Marinobe controlled using the @option{-fexec-charset} and 4046*e4b17023SJohn Marino@option{-fwide-exec-charset} options. 4047*e4b17023SJohn Marino 4048*e4b17023SJohn Marino@item Identifier characters. 4049*e4b17023SJohn Marino@anchor{Identifier characters} 4050*e4b17023SJohn Marino 4051*e4b17023SJohn MarinoThe C and C++ standards allow identifiers to be composed of @samp{_} 4052*e4b17023SJohn Marinoand the alphanumeric characters. C++ and C99 also allow universal 4053*e4b17023SJohn Marinocharacter names, and C99 further permits implementation-defined 4054*e4b17023SJohn Marinocharacters. GCC currently only permits universal character names if 4055*e4b17023SJohn Marino@option{-fextended-identifiers} is used, because the implementation of 4056*e4b17023SJohn Marinouniversal character names in identifiers is experimental. 4057*e4b17023SJohn Marino 4058*e4b17023SJohn MarinoGCC allows the @samp{$} character in identifiers as an extension for 4059*e4b17023SJohn Marinomost targets. This is true regardless of the @option{std=} switch, 4060*e4b17023SJohn Marinosince this extension cannot conflict with standards-conforming 4061*e4b17023SJohn Marinoprograms. When preprocessing assembler, however, dollars are not 4062*e4b17023SJohn Marinoidentifier characters by default. 4063*e4b17023SJohn Marino 4064*e4b17023SJohn MarinoCurrently the targets that by default do not permit @samp{$} are AVR, 4065*e4b17023SJohn MarinoIP2K, MMIX, MIPS Irix 3, ARM aout, and PowerPC targets for the AIX 4066*e4b17023SJohn Marinooperating system. 4067*e4b17023SJohn Marino 4068*e4b17023SJohn MarinoYou can override the default with @option{-fdollars-in-identifiers} or 4069*e4b17023SJohn Marino@option{fno-dollars-in-identifiers}. @xref{fdollars-in-identifiers}. 4070*e4b17023SJohn Marino 4071*e4b17023SJohn Marino@item Non-empty sequences of whitespace characters. 4072*e4b17023SJohn Marino 4073*e4b17023SJohn MarinoIn textual output, each whitespace sequence is collapsed to a single 4074*e4b17023SJohn Marinospace. For aesthetic reasons, the first token on each non-directive 4075*e4b17023SJohn Marinoline of output is preceded with sufficient spaces that it appears in the 4076*e4b17023SJohn Marinosame column as it did in the original source file. 4077*e4b17023SJohn Marino 4078*e4b17023SJohn Marino@item The numeric value of character constants in preprocessor expressions. 4079*e4b17023SJohn Marino 4080*e4b17023SJohn MarinoThe preprocessor and compiler interpret character constants in the 4081*e4b17023SJohn Marinosame way; i.e.@: escape sequences such as @samp{\a} are given the 4082*e4b17023SJohn Marinovalues they would have on the target machine. 4083*e4b17023SJohn Marino 4084*e4b17023SJohn MarinoThe compiler evaluates a multi-character character constant a character 4085*e4b17023SJohn Marinoat a time, shifting the previous value left by the number of bits per 4086*e4b17023SJohn Marinotarget character, and then or-ing in the bit-pattern of the new 4087*e4b17023SJohn Marinocharacter truncated to the width of a target character. The final 4088*e4b17023SJohn Marinobit-pattern is given type @code{int}, and is therefore signed, 4089*e4b17023SJohn Marinoregardless of whether single characters are signed or not (a slight 4090*e4b17023SJohn Marinochange from versions 3.1 and earlier of GCC)@. If there are more 4091*e4b17023SJohn Marinocharacters in the constant than would fit in the target @code{int} the 4092*e4b17023SJohn Marinocompiler issues a warning, and the excess leading characters are 4093*e4b17023SJohn Marinoignored. 4094*e4b17023SJohn Marino 4095*e4b17023SJohn MarinoFor example, @code{'ab'} for a target with an 8-bit @code{char} would be 4096*e4b17023SJohn Marinointerpreted as @w{@samp{(int) ((unsigned char) 'a' * 256 + (unsigned char) 4097*e4b17023SJohn Marino'b')}}, and @code{'\234a'} as @w{@samp{(int) ((unsigned char) '\234' * 4098*e4b17023SJohn Marino256 + (unsigned char) 'a')}}. 4099*e4b17023SJohn Marino 4100*e4b17023SJohn Marino@item Source file inclusion. 4101*e4b17023SJohn Marino 4102*e4b17023SJohn MarinoFor a discussion on how the preprocessor locates header files, 4103*e4b17023SJohn Marino@ref{Include Operation}. 4104*e4b17023SJohn Marino 4105*e4b17023SJohn Marino@item Interpretation of the filename resulting from a macro-expanded 4106*e4b17023SJohn Marino@samp{#include} directive. 4107*e4b17023SJohn Marino 4108*e4b17023SJohn Marino@xref{Computed Includes}. 4109*e4b17023SJohn Marino 4110*e4b17023SJohn Marino@item Treatment of a @samp{#pragma} directive that after macro-expansion 4111*e4b17023SJohn Marinoresults in a standard pragma. 4112*e4b17023SJohn Marino 4113*e4b17023SJohn MarinoNo macro expansion occurs on any @samp{#pragma} directive line, so the 4114*e4b17023SJohn Marinoquestion does not arise. 4115*e4b17023SJohn Marino 4116*e4b17023SJohn MarinoNote that GCC does not yet implement any of the standard 4117*e4b17023SJohn Marinopragmas. 4118*e4b17023SJohn Marino 4119*e4b17023SJohn Marino@end itemize 4120*e4b17023SJohn Marino 4121*e4b17023SJohn Marino@node Implementation limits 4122*e4b17023SJohn Marino@section Implementation limits 4123*e4b17023SJohn Marino@cindex implementation limits 4124*e4b17023SJohn Marino 4125*e4b17023SJohn MarinoCPP has a small number of internal limits. This section lists the 4126*e4b17023SJohn Marinolimits which the C standard requires to be no lower than some minimum, 4127*e4b17023SJohn Marinoand all the others known. It is intended that there should be as few limits 4128*e4b17023SJohn Marinoas possible. If you encounter an undocumented or inconvenient limit, 4129*e4b17023SJohn Marinoplease report that as a bug. @xref{Bugs, , Reporting Bugs, gcc, Using 4130*e4b17023SJohn Marinothe GNU Compiler Collection (GCC)}. 4131*e4b17023SJohn Marino 4132*e4b17023SJohn MarinoWhere we say something is limited @dfn{only by available memory}, that 4133*e4b17023SJohn Marinomeans that internal data structures impose no intrinsic limit, and space 4134*e4b17023SJohn Marinois allocated with @code{malloc} or equivalent. The actual limit will 4135*e4b17023SJohn Marinotherefore depend on many things, such as the size of other things 4136*e4b17023SJohn Marinoallocated by the compiler at the same time, the amount of memory 4137*e4b17023SJohn Marinoconsumed by other processes on the same computer, etc. 4138*e4b17023SJohn Marino 4139*e4b17023SJohn Marino@itemize @bullet 4140*e4b17023SJohn Marino 4141*e4b17023SJohn Marino@item Nesting levels of @samp{#include} files. 4142*e4b17023SJohn Marino 4143*e4b17023SJohn MarinoWe impose an arbitrary limit of 200 levels, to avoid runaway recursion. 4144*e4b17023SJohn MarinoThe standard requires at least 15 levels. 4145*e4b17023SJohn Marino 4146*e4b17023SJohn Marino@item Nesting levels of conditional inclusion. 4147*e4b17023SJohn Marino 4148*e4b17023SJohn MarinoThe C standard mandates this be at least 63. CPP is limited only by 4149*e4b17023SJohn Marinoavailable memory. 4150*e4b17023SJohn Marino 4151*e4b17023SJohn Marino@item Levels of parenthesized expressions within a full expression. 4152*e4b17023SJohn Marino 4153*e4b17023SJohn MarinoThe C standard requires this to be at least 63. In preprocessor 4154*e4b17023SJohn Marinoconditional expressions, it is limited only by available memory. 4155*e4b17023SJohn Marino 4156*e4b17023SJohn Marino@item Significant initial characters in an identifier or macro name. 4157*e4b17023SJohn Marino 4158*e4b17023SJohn MarinoThe preprocessor treats all characters as significant. The C standard 4159*e4b17023SJohn Marinorequires only that the first 63 be significant. 4160*e4b17023SJohn Marino 4161*e4b17023SJohn Marino@item Number of macros simultaneously defined in a single translation unit. 4162*e4b17023SJohn Marino 4163*e4b17023SJohn MarinoThe standard requires at least 4095 be possible. CPP is limited only 4164*e4b17023SJohn Marinoby available memory. 4165*e4b17023SJohn Marino 4166*e4b17023SJohn Marino@item Number of parameters in a macro definition and arguments in a macro call. 4167*e4b17023SJohn Marino 4168*e4b17023SJohn MarinoWe allow @code{USHRT_MAX}, which is no smaller than 65,535. The minimum 4169*e4b17023SJohn Marinorequired by the standard is 127. 4170*e4b17023SJohn Marino 4171*e4b17023SJohn Marino@item Number of characters on a logical source line. 4172*e4b17023SJohn Marino 4173*e4b17023SJohn MarinoThe C standard requires a minimum of 4096 be permitted. CPP places 4174*e4b17023SJohn Marinono limits on this, but you may get incorrect column numbers reported in 4175*e4b17023SJohn Marinodiagnostics for lines longer than 65,535 characters. 4176*e4b17023SJohn Marino 4177*e4b17023SJohn Marino@item Maximum size of a source file. 4178*e4b17023SJohn Marino 4179*e4b17023SJohn MarinoThe standard does not specify any lower limit on the maximum size of a 4180*e4b17023SJohn Marinosource file. GNU cpp maps files into memory, so it is limited by the 4181*e4b17023SJohn Marinoavailable address space. This is generally at least two gigabytes. 4182*e4b17023SJohn MarinoDepending on the operating system, the size of physical memory may or 4183*e4b17023SJohn Marinomay not be a limitation. 4184*e4b17023SJohn Marino 4185*e4b17023SJohn Marino@end itemize 4186*e4b17023SJohn Marino 4187*e4b17023SJohn Marino@node Obsolete Features 4188*e4b17023SJohn Marino@section Obsolete Features 4189*e4b17023SJohn Marino 4190*e4b17023SJohn MarinoCPP has some features which are present mainly for compatibility with 4191*e4b17023SJohn Marinoolder programs. We discourage their use in new code. In some cases, 4192*e4b17023SJohn Marinowe plan to remove the feature in a future version of GCC@. 4193*e4b17023SJohn Marino 4194*e4b17023SJohn Marino@subsection Assertions 4195*e4b17023SJohn Marino@cindex assertions 4196*e4b17023SJohn Marino 4197*e4b17023SJohn Marino@dfn{Assertions} are a deprecated alternative to macros in writing 4198*e4b17023SJohn Marinoconditionals to test what sort of computer or system the compiled 4199*e4b17023SJohn Marinoprogram will run on. Assertions are usually predefined, but you can 4200*e4b17023SJohn Marinodefine them with preprocessing directives or command-line options. 4201*e4b17023SJohn Marino 4202*e4b17023SJohn MarinoAssertions were intended to provide a more systematic way to describe 4203*e4b17023SJohn Marinothe compiler's target system and we added them for compatibility with 4204*e4b17023SJohn Marinoexisting compilers. In practice they are just as unpredictable as the 4205*e4b17023SJohn Marinosystem-specific predefined macros. In addition, they are not part of 4206*e4b17023SJohn Marinoany standard, and only a few compilers support them. 4207*e4b17023SJohn MarinoTherefore, the use of assertions is @strong{less} portable than the use 4208*e4b17023SJohn Marinoof system-specific predefined macros. We recommend you do not use them at 4209*e4b17023SJohn Marinoall. 4210*e4b17023SJohn Marino 4211*e4b17023SJohn Marino@cindex predicates 4212*e4b17023SJohn MarinoAn assertion looks like this: 4213*e4b17023SJohn Marino 4214*e4b17023SJohn Marino@smallexample 4215*e4b17023SJohn Marino#@var{predicate} (@var{answer}) 4216*e4b17023SJohn Marino@end smallexample 4217*e4b17023SJohn Marino 4218*e4b17023SJohn Marino@noindent 4219*e4b17023SJohn Marino@var{predicate} must be a single identifier. @var{answer} can be any 4220*e4b17023SJohn Marinosequence of tokens; all characters are significant except for leading 4221*e4b17023SJohn Marinoand trailing whitespace, and differences in internal whitespace 4222*e4b17023SJohn Marinosequences are ignored. (This is similar to the rules governing macro 4223*e4b17023SJohn Marinoredefinition.) Thus, @code{(x + y)} is different from @code{(x+y)} but 4224*e4b17023SJohn Marinoequivalent to @code{@w{( x + y )}}. Parentheses do not nest inside an 4225*e4b17023SJohn Marinoanswer. 4226*e4b17023SJohn Marino 4227*e4b17023SJohn Marino@cindex testing predicates 4228*e4b17023SJohn MarinoTo test an assertion, you write it in an @samp{#if}. For example, this 4229*e4b17023SJohn Marinoconditional succeeds if either @code{vax} or @code{ns16000} has been 4230*e4b17023SJohn Marinoasserted as an answer for @code{machine}. 4231*e4b17023SJohn Marino 4232*e4b17023SJohn Marino@smallexample 4233*e4b17023SJohn Marino#if #machine (vax) || #machine (ns16000) 4234*e4b17023SJohn Marino@end smallexample 4235*e4b17023SJohn Marino 4236*e4b17023SJohn Marino@noindent 4237*e4b17023SJohn MarinoYou can test whether @emph{any} answer is asserted for a predicate by 4238*e4b17023SJohn Marinoomitting the answer in the conditional: 4239*e4b17023SJohn Marino 4240*e4b17023SJohn Marino@smallexample 4241*e4b17023SJohn Marino#if #machine 4242*e4b17023SJohn Marino@end smallexample 4243*e4b17023SJohn Marino 4244*e4b17023SJohn Marino@findex #assert 4245*e4b17023SJohn MarinoAssertions are made with the @samp{#assert} directive. Its sole 4246*e4b17023SJohn Marinoargument is the assertion to make, without the leading @samp{#} that 4247*e4b17023SJohn Marinoidentifies assertions in conditionals. 4248*e4b17023SJohn Marino 4249*e4b17023SJohn Marino@smallexample 4250*e4b17023SJohn Marino#assert @var{predicate} (@var{answer}) 4251*e4b17023SJohn Marino@end smallexample 4252*e4b17023SJohn Marino 4253*e4b17023SJohn Marino@noindent 4254*e4b17023SJohn MarinoYou may make several assertions with the same predicate and different 4255*e4b17023SJohn Marinoanswers. Subsequent assertions do not override previous ones for the 4256*e4b17023SJohn Marinosame predicate. All the answers for any given predicate are 4257*e4b17023SJohn Marinosimultaneously true. 4258*e4b17023SJohn Marino 4259*e4b17023SJohn Marino@cindex assertions, canceling 4260*e4b17023SJohn Marino@findex #unassert 4261*e4b17023SJohn MarinoAssertions can be canceled with the @samp{#unassert} directive. It 4262*e4b17023SJohn Marinohas the same syntax as @samp{#assert}. In that form it cancels only the 4263*e4b17023SJohn Marinoanswer which was specified on the @samp{#unassert} line; other answers 4264*e4b17023SJohn Marinofor that predicate remain true. You can cancel an entire predicate by 4265*e4b17023SJohn Marinoleaving out the answer: 4266*e4b17023SJohn Marino 4267*e4b17023SJohn Marino@smallexample 4268*e4b17023SJohn Marino#unassert @var{predicate} 4269*e4b17023SJohn Marino@end smallexample 4270*e4b17023SJohn Marino 4271*e4b17023SJohn Marino@noindent 4272*e4b17023SJohn MarinoIn either form, if no such assertion has been made, @samp{#unassert} has 4273*e4b17023SJohn Marinono effect. 4274*e4b17023SJohn Marino 4275*e4b17023SJohn MarinoYou can also make or cancel assertions using command line options. 4276*e4b17023SJohn Marino@xref{Invocation}. 4277*e4b17023SJohn Marino 4278*e4b17023SJohn Marino@node Differences from previous versions 4279*e4b17023SJohn Marino@section Differences from previous versions 4280*e4b17023SJohn Marino@cindex differences from previous versions 4281*e4b17023SJohn Marino 4282*e4b17023SJohn MarinoThis section details behavior which has changed from previous versions 4283*e4b17023SJohn Marinoof CPP@. We do not plan to change it again in the near future, but 4284*e4b17023SJohn Marinowe do not promise not to, either. 4285*e4b17023SJohn Marino 4286*e4b17023SJohn MarinoThe ``previous versions'' discussed here are 2.95 and before. The 4287*e4b17023SJohn Marinobehavior of GCC 3.0 is mostly the same as the behavior of the widely 4288*e4b17023SJohn Marinoused 2.96 and 2.97 development snapshots. Where there are differences, 4289*e4b17023SJohn Marinothey generally represent bugs in the snapshots. 4290*e4b17023SJohn Marino 4291*e4b17023SJohn Marino@itemize @bullet 4292*e4b17023SJohn Marino 4293*e4b17023SJohn Marino@item -I- deprecated 4294*e4b17023SJohn Marino 4295*e4b17023SJohn MarinoThis option has been deprecated in 4.0. @option{-iquote} is meant to 4296*e4b17023SJohn Marinoreplace the need for this option. 4297*e4b17023SJohn Marino 4298*e4b17023SJohn Marino@item Order of evaluation of @samp{#} and @samp{##} operators 4299*e4b17023SJohn Marino 4300*e4b17023SJohn MarinoThe standard does not specify the order of evaluation of a chain of 4301*e4b17023SJohn Marino@samp{##} operators, nor whether @samp{#} is evaluated before, after, or 4302*e4b17023SJohn Marinoat the same time as @samp{##}. You should therefore not write any code 4303*e4b17023SJohn Marinowhich depends on any specific ordering. It is possible to guarantee an 4304*e4b17023SJohn Marinoordering, if you need one, by suitable use of nested macros. 4305*e4b17023SJohn Marino 4306*e4b17023SJohn MarinoAn example of where this might matter is pasting the arguments @samp{1}, 4307*e4b17023SJohn Marino@samp{e} and @samp{-2}. This would be fine for left-to-right pasting, 4308*e4b17023SJohn Marinobut right-to-left pasting would produce an invalid token @samp{e-2}. 4309*e4b17023SJohn Marino 4310*e4b17023SJohn MarinoGCC 3.0 evaluates @samp{#} and @samp{##} at the same time and strictly 4311*e4b17023SJohn Marinoleft to right. Older versions evaluated all @samp{#} operators first, 4312*e4b17023SJohn Marinothen all @samp{##} operators, in an unreliable order. 4313*e4b17023SJohn Marino 4314*e4b17023SJohn Marino@item The form of whitespace between tokens in preprocessor output 4315*e4b17023SJohn Marino 4316*e4b17023SJohn Marino@xref{Preprocessor Output}, for the current textual format. This is 4317*e4b17023SJohn Marinoalso the format used by stringification. Normally, the preprocessor 4318*e4b17023SJohn Marinocommunicates tokens directly to the compiler's parser, and whitespace 4319*e4b17023SJohn Marinodoes not come up at all. 4320*e4b17023SJohn Marino 4321*e4b17023SJohn MarinoOlder versions of GCC preserved all whitespace provided by the user and 4322*e4b17023SJohn Marinoinserted lots more whitespace of their own, because they could not 4323*e4b17023SJohn Marinoaccurately predict when extra spaces were needed to prevent accidental 4324*e4b17023SJohn Marinotoken pasting. 4325*e4b17023SJohn Marino 4326*e4b17023SJohn Marino@item Optional argument when invoking rest argument macros 4327*e4b17023SJohn Marino 4328*e4b17023SJohn MarinoAs an extension, GCC permits you to omit the variable arguments entirely 4329*e4b17023SJohn Marinowhen you use a variable argument macro. This is forbidden by the 1999 C 4330*e4b17023SJohn Marinostandard, and will provoke a pedantic warning with GCC 3.0. Previous 4331*e4b17023SJohn Marinoversions accepted it silently. 4332*e4b17023SJohn Marino 4333*e4b17023SJohn Marino@item @samp{##} swallowing preceding text in rest argument macros 4334*e4b17023SJohn Marino 4335*e4b17023SJohn MarinoFormerly, in a macro expansion, if @samp{##} appeared before a variable 4336*e4b17023SJohn Marinoarguments parameter, and the set of tokens specified for that argument 4337*e4b17023SJohn Marinoin the macro invocation was empty, previous versions of CPP would 4338*e4b17023SJohn Marinoback up and remove the preceding sequence of non-whitespace characters 4339*e4b17023SJohn Marino(@strong{not} the preceding token). This extension is in direct 4340*e4b17023SJohn Marinoconflict with the 1999 C standard and has been drastically pared back. 4341*e4b17023SJohn Marino 4342*e4b17023SJohn MarinoIn the current version of the preprocessor, if @samp{##} appears between 4343*e4b17023SJohn Marinoa comma and a variable arguments parameter, and the variable argument is 4344*e4b17023SJohn Marinoomitted entirely, the comma will be removed from the expansion. If the 4345*e4b17023SJohn Marinovariable argument is empty, or the token before @samp{##} is not a 4346*e4b17023SJohn Marinocomma, then @samp{##} behaves as a normal token paste. 4347*e4b17023SJohn Marino 4348*e4b17023SJohn Marino@item @samp{#line} and @samp{#include} 4349*e4b17023SJohn Marino 4350*e4b17023SJohn MarinoThe @samp{#line} directive used to change GCC's notion of the 4351*e4b17023SJohn Marino``directory containing the current file'', used by @samp{#include} with 4352*e4b17023SJohn Marinoa double-quoted header file name. In 3.0 and later, it does not. 4353*e4b17023SJohn Marino@xref{Line Control}, for further explanation. 4354*e4b17023SJohn Marino 4355*e4b17023SJohn Marino@item Syntax of @samp{#line} 4356*e4b17023SJohn Marino 4357*e4b17023SJohn MarinoIn GCC 2.95 and previous, the string constant argument to @samp{#line} 4358*e4b17023SJohn Marinowas treated the same way as the argument to @samp{#include}: backslash 4359*e4b17023SJohn Marinoescapes were not honored, and the string ended at the second @samp{"}. 4360*e4b17023SJohn MarinoThis is not compliant with the C standard. In GCC 3.0, an attempt was 4361*e4b17023SJohn Marinomade to correct the behavior, so that the string was treated as a real 4362*e4b17023SJohn Marinostring constant, but it turned out to be buggy. In 3.1, the bugs have 4363*e4b17023SJohn Marinobeen fixed. (We are not fixing the bugs in 3.0 because they affect 4364*e4b17023SJohn Marinorelatively few people and the fix is quite invasive.) 4365*e4b17023SJohn Marino 4366*e4b17023SJohn Marino@end itemize 4367*e4b17023SJohn Marino 4368*e4b17023SJohn Marino@node Invocation 4369*e4b17023SJohn Marino@chapter Invocation 4370*e4b17023SJohn Marino@cindex invocation 4371*e4b17023SJohn Marino@cindex command line 4372*e4b17023SJohn Marino 4373*e4b17023SJohn MarinoMost often when you use the C preprocessor you will not have to invoke it 4374*e4b17023SJohn Marinoexplicitly: the C compiler will do so automatically. However, the 4375*e4b17023SJohn Marinopreprocessor is sometimes useful on its own. All the options listed 4376*e4b17023SJohn Marinohere are also acceptable to the C compiler and have the same meaning, 4377*e4b17023SJohn Marinoexcept that the C compiler has different rules for specifying the output 4378*e4b17023SJohn Marinofile. 4379*e4b17023SJohn Marino 4380*e4b17023SJohn Marino@emph{Note:} Whether you use the preprocessor by way of @command{gcc} 4381*e4b17023SJohn Marinoor @command{cpp}, the @dfn{compiler driver} is run first. This 4382*e4b17023SJohn Marinoprogram's purpose is to translate your command into invocations of the 4383*e4b17023SJohn Marinoprograms that do the actual work. Their command line interfaces are 4384*e4b17023SJohn Marinosimilar but not identical to the documented interface, and may change 4385*e4b17023SJohn Marinowithout notice. 4386*e4b17023SJohn Marino 4387*e4b17023SJohn Marino@ignore 4388*e4b17023SJohn Marino@c man begin SYNOPSIS 4389*e4b17023SJohn Marinocpp [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}] 4390*e4b17023SJohn Marino [@option{-I}@var{dir}@dots{}] [@option{-iquote}@var{dir}@dots{}] 4391*e4b17023SJohn Marino [@option{-W}@var{warn}@dots{}] 4392*e4b17023SJohn Marino [@option{-M}|@option{-MM}] [@option{-MG}] [@option{-MF} @var{filename}] 4393*e4b17023SJohn Marino [@option{-MP}] [@option{-MQ} @var{target}@dots{}] 4394*e4b17023SJohn Marino [@option{-MT} @var{target}@dots{}] 4395*e4b17023SJohn Marino [@option{-P}] [@option{-fno-working-directory}] 4396*e4b17023SJohn Marino [@option{-x} @var{language}] [@option{-std=}@var{standard}] 4397*e4b17023SJohn Marino @var{infile} @var{outfile} 4398*e4b17023SJohn Marino 4399*e4b17023SJohn MarinoOnly the most useful options are listed here; see below for the remainder. 4400*e4b17023SJohn Marino@c man end 4401*e4b17023SJohn Marino@c man begin SEEALSO 4402*e4b17023SJohn Marinogpl(7), gfdl(7), fsf-funding(7), 4403*e4b17023SJohn Marinogcc(1), as(1), ld(1), and the Info entries for @file{cpp}, @file{gcc}, and 4404*e4b17023SJohn Marino@file{binutils}. 4405*e4b17023SJohn Marino@c man end 4406*e4b17023SJohn Marino@end ignore 4407*e4b17023SJohn Marino 4408*e4b17023SJohn Marino@c man begin OPTIONS 4409*e4b17023SJohn MarinoThe C preprocessor expects two file names as arguments, @var{infile} and 4410*e4b17023SJohn Marino@var{outfile}. The preprocessor reads @var{infile} together with any 4411*e4b17023SJohn Marinoother files it specifies with @samp{#include}. All the output generated 4412*e4b17023SJohn Marinoby the combined input files is written in @var{outfile}. 4413*e4b17023SJohn Marino 4414*e4b17023SJohn MarinoEither @var{infile} or @var{outfile} may be @option{-}, which as 4415*e4b17023SJohn Marino@var{infile} means to read from standard input and as @var{outfile} 4416*e4b17023SJohn Marinomeans to write to standard output. Also, if either file is omitted, it 4417*e4b17023SJohn Marinomeans the same as if @option{-} had been specified for that file. 4418*e4b17023SJohn Marino 4419*e4b17023SJohn MarinoUnless otherwise noted, or the option ends in @samp{=}, all options 4420*e4b17023SJohn Marinowhich take an argument may have that argument appear either immediately 4421*e4b17023SJohn Marinoafter the option, or with a space between option and argument: 4422*e4b17023SJohn Marino@option{-Ifoo} and @option{-I foo} have the same effect. 4423*e4b17023SJohn Marino 4424*e4b17023SJohn Marino@cindex grouping options 4425*e4b17023SJohn Marino@cindex options, grouping 4426*e4b17023SJohn MarinoMany options have multi-letter names; therefore multiple single-letter 4427*e4b17023SJohn Marinooptions may @emph{not} be grouped: @option{-dM} is very different from 4428*e4b17023SJohn Marino@w{@samp{-d -M}}. 4429*e4b17023SJohn Marino 4430*e4b17023SJohn Marino@cindex options 4431*e4b17023SJohn Marino@include cppopts.texi 4432*e4b17023SJohn Marino@c man end 4433*e4b17023SJohn Marino 4434*e4b17023SJohn Marino@node Environment Variables 4435*e4b17023SJohn Marino@chapter Environment Variables 4436*e4b17023SJohn Marino@cindex environment variables 4437*e4b17023SJohn Marino@c man begin ENVIRONMENT 4438*e4b17023SJohn Marino 4439*e4b17023SJohn MarinoThis section describes the environment variables that affect how CPP 4440*e4b17023SJohn Marinooperates. You can use them to specify directories or prefixes to use 4441*e4b17023SJohn Marinowhen searching for include files, or to control dependency output. 4442*e4b17023SJohn Marino 4443*e4b17023SJohn MarinoNote that you can also specify places to search using options such as 4444*e4b17023SJohn Marino@option{-I}, and control dependency output with options like 4445*e4b17023SJohn Marino@option{-M} (@pxref{Invocation}). These take precedence over 4446*e4b17023SJohn Marinoenvironment variables, which in turn take precedence over the 4447*e4b17023SJohn Marinoconfiguration of GCC@. 4448*e4b17023SJohn Marino 4449*e4b17023SJohn Marino@include cppenv.texi 4450*e4b17023SJohn Marino@c man end 4451*e4b17023SJohn Marino 4452*e4b17023SJohn Marino@page 4453*e4b17023SJohn Marino@include fdl.texi 4454*e4b17023SJohn Marino 4455*e4b17023SJohn Marino@page 4456*e4b17023SJohn Marino@node Index of Directives 4457*e4b17023SJohn Marino@unnumbered Index of Directives 4458*e4b17023SJohn Marino@printindex fn 4459*e4b17023SJohn Marino 4460*e4b17023SJohn Marino@node Option Index 4461*e4b17023SJohn Marino@unnumbered Option Index 4462*e4b17023SJohn Marino@noindent 4463*e4b17023SJohn MarinoCPP's command line options and environment variables are indexed here 4464*e4b17023SJohn Marinowithout any initial @samp{-} or @samp{--}. 4465*e4b17023SJohn Marino@printindex op 4466*e4b17023SJohn Marino 4467*e4b17023SJohn Marino@page 4468*e4b17023SJohn Marino@node Concept Index 4469*e4b17023SJohn Marino@unnumbered Concept Index 4470*e4b17023SJohn Marino@printindex cp 4471*e4b17023SJohn Marino 4472*e4b17023SJohn Marino@bye 4473