1*404b540aSrobertThis is doc/cpp.info, produced by makeinfo version 4.8 from 2*404b540aSrobert/scratch/mitchell/gcc-releases/gcc-4.2.1/gcc-4.2.1/gcc/doc/cpp.texi. 3*404b540aSrobert 4*404b540aSrobert Copyright (C) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 5*404b540aSrobert1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free Software 6*404b540aSrobertFoundation, Inc. 7*404b540aSrobert 8*404b540aSrobert Permission is granted to copy, distribute and/or modify this document 9*404b540aSrobertunder the terms of the GNU Free Documentation License, Version 1.1 or 10*404b540aSrobertany later version published by the Free Software Foundation. A copy of 11*404b540aSrobertthe license is included in the section entitled "GNU Free Documentation 12*404b540aSrobertLicense". 13*404b540aSrobert 14*404b540aSrobert This manual contains no Invariant Sections. The Front-Cover Texts 15*404b540aSrobertare (a) (see below), and the Back-Cover Texts are (b) (see below). 16*404b540aSrobert 17*404b540aSrobert (a) The FSF's Front-Cover Text is: 18*404b540aSrobert 19*404b540aSrobert A GNU Manual 20*404b540aSrobert 21*404b540aSrobert (b) The FSF's Back-Cover Text is: 22*404b540aSrobert 23*404b540aSrobert You have freedom to copy and modify this GNU Manual, like GNU 24*404b540aSrobertsoftware. Copies published by the Free Software Foundation raise 25*404b540aSrobertfunds for GNU development. 26*404b540aSrobert 27*404b540aSrobertINFO-DIR-SECTION Software development 28*404b540aSrobertSTART-INFO-DIR-ENTRY 29*404b540aSrobert* Cpp: (cpp). The GNU C preprocessor. 30*404b540aSrobertEND-INFO-DIR-ENTRY 31*404b540aSrobert 32*404b540aSrobert 33*404b540aSrobertFile: cpp.info, Node: Top, Next: Overview, Up: (dir) 34*404b540aSrobert 35*404b540aSrobertThe C Preprocessor 36*404b540aSrobert****************** 37*404b540aSrobert 38*404b540aSrobertThe C preprocessor implements the macro language used to transform C, 39*404b540aSrobertC++, and Objective-C programs before they are compiled. It can also be 40*404b540aSrobertuseful on its own. 41*404b540aSrobert 42*404b540aSrobert* Menu: 43*404b540aSrobert 44*404b540aSrobert* Overview:: 45*404b540aSrobert* Header Files:: 46*404b540aSrobert* Macros:: 47*404b540aSrobert* Conditionals:: 48*404b540aSrobert* Diagnostics:: 49*404b540aSrobert* Line Control:: 50*404b540aSrobert* Pragmas:: 51*404b540aSrobert* Other Directives:: 52*404b540aSrobert* Preprocessor Output:: 53*404b540aSrobert* Traditional Mode:: 54*404b540aSrobert* Implementation Details:: 55*404b540aSrobert* Invocation:: 56*404b540aSrobert* Environment Variables:: 57*404b540aSrobert* GNU Free Documentation License:: 58*404b540aSrobert* Index of Directives:: 59*404b540aSrobert* Option Index:: 60*404b540aSrobert* Concept Index:: 61*404b540aSrobert 62*404b540aSrobert --- The Detailed Node Listing --- 63*404b540aSrobert 64*404b540aSrobertOverview 65*404b540aSrobert 66*404b540aSrobert* Character sets:: 67*404b540aSrobert* Initial processing:: 68*404b540aSrobert* Tokenization:: 69*404b540aSrobert* The preprocessing language:: 70*404b540aSrobert 71*404b540aSrobertHeader Files 72*404b540aSrobert 73*404b540aSrobert* Include Syntax:: 74*404b540aSrobert* Include Operation:: 75*404b540aSrobert* Search Path:: 76*404b540aSrobert* Once-Only Headers:: 77*404b540aSrobert* Computed Includes:: 78*404b540aSrobert* Wrapper Headers:: 79*404b540aSrobert* System Headers:: 80*404b540aSrobert 81*404b540aSrobertMacros 82*404b540aSrobert 83*404b540aSrobert* Object-like Macros:: 84*404b540aSrobert* Function-like Macros:: 85*404b540aSrobert* Macro Arguments:: 86*404b540aSrobert* Stringification:: 87*404b540aSrobert* Concatenation:: 88*404b540aSrobert* Variadic Macros:: 89*404b540aSrobert* Predefined Macros:: 90*404b540aSrobert* Undefining and Redefining Macros:: 91*404b540aSrobert* Directives Within Macro Arguments:: 92*404b540aSrobert* Macro Pitfalls:: 93*404b540aSrobert 94*404b540aSrobertPredefined Macros 95*404b540aSrobert 96*404b540aSrobert* Standard Predefined Macros:: 97*404b540aSrobert* Common Predefined Macros:: 98*404b540aSrobert* System-specific Predefined Macros:: 99*404b540aSrobert* C++ Named Operators:: 100*404b540aSrobert 101*404b540aSrobertMacro Pitfalls 102*404b540aSrobert 103*404b540aSrobert* Misnesting:: 104*404b540aSrobert* Operator Precedence Problems:: 105*404b540aSrobert* Swallowing the Semicolon:: 106*404b540aSrobert* Duplication of Side Effects:: 107*404b540aSrobert* Self-Referential Macros:: 108*404b540aSrobert* Argument Prescan:: 109*404b540aSrobert* Newlines in Arguments:: 110*404b540aSrobert 111*404b540aSrobertConditionals 112*404b540aSrobert 113*404b540aSrobert* Conditional Uses:: 114*404b540aSrobert* Conditional Syntax:: 115*404b540aSrobert* Deleted Code:: 116*404b540aSrobert 117*404b540aSrobertConditional Syntax 118*404b540aSrobert 119*404b540aSrobert* Ifdef:: 120*404b540aSrobert* If:: 121*404b540aSrobert* Defined:: 122*404b540aSrobert* Else:: 123*404b540aSrobert* Elif:: 124*404b540aSrobert 125*404b540aSrobertImplementation Details 126*404b540aSrobert 127*404b540aSrobert* Implementation-defined behavior:: 128*404b540aSrobert* Implementation limits:: 129*404b540aSrobert* Obsolete Features:: 130*404b540aSrobert* Differences from previous versions:: 131*404b540aSrobert 132*404b540aSrobertObsolete Features 133*404b540aSrobert 134*404b540aSrobert* Assertions:: 135*404b540aSrobert* Obsolete once-only headers:: 136*404b540aSrobert 137*404b540aSrobert Copyright (C) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 138*404b540aSrobert1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free Software 139*404b540aSrobertFoundation, Inc. 140*404b540aSrobert 141*404b540aSrobert Permission is granted to copy, distribute and/or modify this document 142*404b540aSrobertunder the terms of the GNU Free Documentation License, Version 1.1 or 143*404b540aSrobertany later version published by the Free Software Foundation. A copy of 144*404b540aSrobertthe license is included in the section entitled "GNU Free Documentation 145*404b540aSrobertLicense". 146*404b540aSrobert 147*404b540aSrobert This manual contains no Invariant Sections. The Front-Cover Texts 148*404b540aSrobertare (a) (see below), and the Back-Cover Texts are (b) (see below). 149*404b540aSrobert 150*404b540aSrobert (a) The FSF's Front-Cover Text is: 151*404b540aSrobert 152*404b540aSrobert A GNU Manual 153*404b540aSrobert 154*404b540aSrobert (b) The FSF's Back-Cover Text is: 155*404b540aSrobert 156*404b540aSrobert You have freedom to copy and modify this GNU Manual, like GNU 157*404b540aSrobertsoftware. Copies published by the Free Software Foundation raise 158*404b540aSrobertfunds for GNU development. 159*404b540aSrobert 160*404b540aSrobert 161*404b540aSrobertFile: cpp.info, Node: Overview, Next: Header Files, Prev: Top, Up: Top 162*404b540aSrobert 163*404b540aSrobert1 Overview 164*404b540aSrobert********** 165*404b540aSrobert 166*404b540aSrobertThe C preprocessor, often known as "cpp", is a "macro processor" that 167*404b540aSrobertis used automatically by the C compiler to transform your program 168*404b540aSrobertbefore compilation. It is called a macro processor because it allows 169*404b540aSrobertyou to define "macros", which are brief abbreviations for longer 170*404b540aSrobertconstructs. 171*404b540aSrobert 172*404b540aSrobert The C preprocessor is intended to be used only with C, C++, and 173*404b540aSrobertObjective-C source code. In the past, it has been abused as a general 174*404b540aSroberttext processor. It will choke on input which does not obey C's lexical 175*404b540aSrobertrules. For example, apostrophes will be interpreted as the beginning of 176*404b540aSrobertcharacter constants, and cause errors. Also, you cannot rely on it 177*404b540aSrobertpreserving characteristics of the input which are not significant to 178*404b540aSrobertC-family languages. If a Makefile is preprocessed, all the hard tabs 179*404b540aSrobertwill be removed, and the Makefile will not work. 180*404b540aSrobert 181*404b540aSrobert Having said that, you can often get away with using cpp on things 182*404b540aSrobertwhich are not C. Other Algol-ish programming languages are often safe 183*404b540aSrobert(Pascal, Ada, etc.) So is assembly, with caution. `-traditional-cpp' 184*404b540aSrobertmode preserves more white space, and is otherwise more permissive. Many 185*404b540aSrobertof the problems can be avoided by writing C or C++ style comments 186*404b540aSrobertinstead of native language comments, and keeping macros simple. 187*404b540aSrobert 188*404b540aSrobert Wherever possible, you should use a preprocessor geared to the 189*404b540aSrobertlanguage you are writing in. Modern versions of the GNU assembler have 190*404b540aSrobertmacro facilities. Most high level programming languages have their own 191*404b540aSrobertconditional compilation and inclusion mechanism. If all else fails, 192*404b540aSroberttry a true general text processor, such as GNU M4. 193*404b540aSrobert 194*404b540aSrobert C preprocessors vary in some details. This manual discusses the GNU 195*404b540aSrobertC preprocessor, which provides a small superset of the features of ISO 196*404b540aSrobertStandard C. In its default mode, the GNU C preprocessor does not do a 197*404b540aSrobertfew things required by the standard. These are features which are 198*404b540aSrobertrarely, if ever, used, and may cause surprising changes to the meaning 199*404b540aSrobertof a program which does not expect them. To get strict ISO Standard C, 200*404b540aSrobertyou should use the `-std=c89' or `-std=c99' options, depending on which 201*404b540aSrobertversion of the standard you want. To get all the mandatory 202*404b540aSrobertdiagnostics, you must also use `-pedantic'. *Note Invocation::. 203*404b540aSrobert 204*404b540aSrobert This manual describes the behavior of the ISO preprocessor. To 205*404b540aSrobertminimize gratuitous differences, where the ISO preprocessor's behavior 206*404b540aSrobertdoes not conflict with traditional semantics, the traditional 207*404b540aSrobertpreprocessor should behave the same way. The various differences that 208*404b540aSrobertdo exist are detailed in the section *Note Traditional Mode::. 209*404b540aSrobert 210*404b540aSrobert For clarity, unless noted otherwise, references to `CPP' in this 211*404b540aSrobertmanual refer to GNU CPP. 212*404b540aSrobert 213*404b540aSrobert* Menu: 214*404b540aSrobert 215*404b540aSrobert* Character sets:: 216*404b540aSrobert* Initial processing:: 217*404b540aSrobert* Tokenization:: 218*404b540aSrobert* The preprocessing language:: 219*404b540aSrobert 220*404b540aSrobert 221*404b540aSrobertFile: cpp.info, Node: Character sets, Next: Initial processing, Up: Overview 222*404b540aSrobert 223*404b540aSrobert1.1 Character sets 224*404b540aSrobert================== 225*404b540aSrobert 226*404b540aSrobertSource code character set processing in C and related languages is 227*404b540aSrobertrather complicated. The C standard discusses two character sets, but 228*404b540aSrobertthere are really at least four. 229*404b540aSrobert 230*404b540aSrobert The files input to CPP might be in any character set at all. CPP's 231*404b540aSrobertvery first action, before it even looks for line boundaries, is to 232*404b540aSrobertconvert the file into the character set it uses for internal 233*404b540aSrobertprocessing. That set is what the C standard calls the "source" 234*404b540aSrobertcharacter set. It must be isomorphic with ISO 10646, also known as 235*404b540aSrobertUnicode. CPP uses the UTF-8 encoding of Unicode. 236*404b540aSrobert 237*404b540aSrobert The character sets of the input files are specified using the 238*404b540aSrobert`-finput-charset=' option. 239*404b540aSrobert 240*404b540aSrobert All preprocessing work (the subject of the rest of this manual) is 241*404b540aSrobertcarried out in the source character set. If you request textual output 242*404b540aSrobertfrom the preprocessor with the `-E' option, it will be in UTF-8. 243*404b540aSrobert 244*404b540aSrobert After preprocessing is complete, string and character constants are 245*404b540aSrobertconverted again, into the "execution" character set. This character 246*404b540aSrobertset is under control of the user; the default is UTF-8, matching the 247*404b540aSrobertsource character set. Wide string and character constants have their 248*404b540aSrobertown character set, which is not called out specifically in the 249*404b540aSrobertstandard. Again, it is under control of the user. The default is 250*404b540aSrobertUTF-16 or UTF-32, whichever fits in the target's `wchar_t' type, in the 251*404b540aSroberttarget machine's byte order.(1) Octal and hexadecimal escape sequences 252*404b540aSrobertdo not undergo conversion; '\x12' has the value 0x12 regardless of the 253*404b540aSrobertcurrently selected execution character set. All other escapes are 254*404b540aSrobertreplaced by the character in the source character set that they 255*404b540aSrobertrepresent, then converted to the execution character set, just like 256*404b540aSrobertunescaped characters. 257*404b540aSrobert 258*404b540aSrobert Unless the experimental `-fextended-identifiers' option is used, GCC 259*404b540aSrobertdoes not permit the use of characters outside the ASCII range, nor `\u' 260*404b540aSrobertand `\U' escapes, in identifiers. Even with that option, characters 261*404b540aSrobertoutside the ASCII range can only be specified with the `\u' and `\U' 262*404b540aSrobertescapes, not used directly in identifiers. 263*404b540aSrobert 264*404b540aSrobert ---------- Footnotes ---------- 265*404b540aSrobert 266*404b540aSrobert (1) UTF-16 does not meet the requirements of the C standard for a 267*404b540aSrobertwide character set, but the choice of 16-bit `wchar_t' is enshrined in 268*404b540aSrobertsome system ABIs so we cannot fix this. 269*404b540aSrobert 270*404b540aSrobert 271*404b540aSrobertFile: cpp.info, Node: Initial processing, Next: Tokenization, Prev: Character sets, Up: Overview 272*404b540aSrobert 273*404b540aSrobert1.2 Initial processing 274*404b540aSrobert====================== 275*404b540aSrobert 276*404b540aSrobertThe preprocessor performs a series of textual transformations on its 277*404b540aSrobertinput. These happen before all other processing. Conceptually, they 278*404b540aSroberthappen in a rigid order, and the entire file is run through each 279*404b540aSroberttransformation before the next one begins. CPP actually does them all 280*404b540aSrobertat once, for performance reasons. These transformations correspond 281*404b540aSrobertroughly to the first three "phases of translation" described in the C 282*404b540aSrobertstandard. 283*404b540aSrobert 284*404b540aSrobert 1. The input file is read into memory and broken into lines. 285*404b540aSrobert 286*404b540aSrobert Different systems use different conventions to indicate the end of 287*404b540aSrobert a line. GCC accepts the ASCII control sequences `LF', `CR LF' and 288*404b540aSrobert `CR' as end-of-line markers. These are the canonical sequences 289*404b540aSrobert used by Unix, DOS and VMS, and the classic Mac OS (before OSX) 290*404b540aSrobert respectively. You may therefore safely copy source code written 291*404b540aSrobert on any of those systems to a different one and use it without 292*404b540aSrobert conversion. (GCC may lose track of the current line number if a 293*404b540aSrobert file doesn't consistently use one convention, as sometimes happens 294*404b540aSrobert when it is edited on computers with different conventions that 295*404b540aSrobert share a network file system.) 296*404b540aSrobert 297*404b540aSrobert If the last line of any input file lacks an end-of-line marker, 298*404b540aSrobert the end of the file is considered to implicitly supply one. The C 299*404b540aSrobert standard says that this condition provokes undefined behavior, so 300*404b540aSrobert GCC will emit a warning message. 301*404b540aSrobert 302*404b540aSrobert 2. If trigraphs are enabled, they are replaced by their corresponding 303*404b540aSrobert single characters. By default GCC ignores trigraphs, but if you 304*404b540aSrobert request a strictly conforming mode with the `-std' option, or you 305*404b540aSrobert specify the `-trigraphs' option, then it converts them. 306*404b540aSrobert 307*404b540aSrobert These are nine three-character sequences, all starting with `??', 308*404b540aSrobert that are defined by ISO C to stand for single characters. They 309*404b540aSrobert permit obsolete systems that lack some of C's punctuation to use 310*404b540aSrobert C. For example, `??/' stands for `\', so '??/n' is a character 311*404b540aSrobert constant for a newline. 312*404b540aSrobert 313*404b540aSrobert Trigraphs are not popular and many compilers implement them 314*404b540aSrobert incorrectly. Portable code should not rely on trigraphs being 315*404b540aSrobert either converted or ignored. With `-Wtrigraphs' GCC will warn you 316*404b540aSrobert when a trigraph may change the meaning of your program if it were 317*404b540aSrobert converted. *Note Wtrigraphs::. 318*404b540aSrobert 319*404b540aSrobert In a string constant, you can prevent a sequence of question marks 320*404b540aSrobert from being confused with a trigraph by inserting a backslash 321*404b540aSrobert between the question marks, or by separating the string literal at 322*404b540aSrobert the trigraph and making use of string literal concatenation. 323*404b540aSrobert "(??\?)" is the string `(???)', not `(?]'. Traditional C 324*404b540aSrobert compilers do not recognize these idioms. 325*404b540aSrobert 326*404b540aSrobert The nine trigraphs and their replacements are 327*404b540aSrobert 328*404b540aSrobert Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??- 329*404b540aSrobert Replacement: [ ] { } # \ ^ | ~ 330*404b540aSrobert 331*404b540aSrobert 3. Continued lines are merged into one long line. 332*404b540aSrobert 333*404b540aSrobert A continued line is a line which ends with a backslash, `\'. The 334*404b540aSrobert backslash is removed and the following line is joined with the 335*404b540aSrobert current one. No space is inserted, so you may split a line 336*404b540aSrobert anywhere, even in the middle of a word. (It is generally more 337*404b540aSrobert readable to split lines only at white space.) 338*404b540aSrobert 339*404b540aSrobert The trailing backslash on a continued line is commonly referred to 340*404b540aSrobert as a "backslash-newline". 341*404b540aSrobert 342*404b540aSrobert If there is white space between a backslash and the end of a line, 343*404b540aSrobert that is still a continued line. However, as this is usually the 344*404b540aSrobert result of an editing mistake, and many compilers will not accept 345*404b540aSrobert it as a continued line, GCC will warn you about it. 346*404b540aSrobert 347*404b540aSrobert 4. All comments are replaced with single spaces. 348*404b540aSrobert 349*404b540aSrobert There are two kinds of comments. "Block comments" begin with `/*' 350*404b540aSrobert and continue until the next `*/'. Block comments do not nest: 351*404b540aSrobert 352*404b540aSrobert /* this is /* one comment */ text outside comment 353*404b540aSrobert 354*404b540aSrobert "Line comments" begin with `//' and continue to the end of the 355*404b540aSrobert current line. Line comments do not nest either, but it does not 356*404b540aSrobert matter, because they would end in the same place anyway. 357*404b540aSrobert 358*404b540aSrobert // this is // one comment 359*404b540aSrobert text outside comment 360*404b540aSrobert 361*404b540aSrobert It is safe to put line comments inside block comments, or vice versa. 362*404b540aSrobert 363*404b540aSrobert /* block comment 364*404b540aSrobert // contains line comment 365*404b540aSrobert yet more comment 366*404b540aSrobert */ outside comment 367*404b540aSrobert 368*404b540aSrobert // line comment /* contains block comment */ 369*404b540aSrobert 370*404b540aSrobert But beware of commenting out one end of a block comment with a line 371*404b540aSrobertcomment. 372*404b540aSrobert 373*404b540aSrobert // l.c. /* block comment begins 374*404b540aSrobert oops! this isn't a comment anymore */ 375*404b540aSrobert 376*404b540aSrobert Comments are not recognized within string literals. "/* blah */" is 377*404b540aSrobertthe string constant `/* blah */', not an empty string. 378*404b540aSrobert 379*404b540aSrobert Line comments are not in the 1989 edition of the C standard, but they 380*404b540aSrobertare recognized by GCC as an extension. In C++ and in the 1999 edition 381*404b540aSrobertof the C standard, they are an official part of the language. 382*404b540aSrobert 383*404b540aSrobert Since these transformations happen before all other processing, you 384*404b540aSrobertcan split a line mechanically with backslash-newline anywhere. You can 385*404b540aSrobertcomment out the end of a line. You can continue a line comment onto the 386*404b540aSrobertnext line with backslash-newline. You can even split `/*', `*/', and 387*404b540aSrobert`//' onto multiple lines with backslash-newline. For example: 388*404b540aSrobert 389*404b540aSrobert /\ 390*404b540aSrobert * 391*404b540aSrobert */ # /* 392*404b540aSrobert */ defi\ 393*404b540aSrobert ne FO\ 394*404b540aSrobert O 10\ 395*404b540aSrobert 20 396*404b540aSrobert 397*404b540aSrobertis equivalent to `#define FOO 1020'. All these tricks are extremely 398*404b540aSrobertconfusing and should not be used in code intended to be readable. 399*404b540aSrobert 400*404b540aSrobert There is no way to prevent a backslash at the end of a line from 401*404b540aSrobertbeing interpreted as a backslash-newline. This cannot affect any 402*404b540aSrobertcorrect program, however. 403*404b540aSrobert 404*404b540aSrobert 405*404b540aSrobertFile: cpp.info, Node: Tokenization, Next: The preprocessing language, Prev: Initial processing, Up: Overview 406*404b540aSrobert 407*404b540aSrobert1.3 Tokenization 408*404b540aSrobert================ 409*404b540aSrobert 410*404b540aSrobertAfter the textual transformations are finished, the input file is 411*404b540aSrobertconverted into a sequence of "preprocessing tokens". These mostly 412*404b540aSrobertcorrespond to the syntactic tokens used by the C compiler, but there are 413*404b540aSroberta few differences. White space separates tokens; it is not itself a 414*404b540aSroberttoken of any kind. Tokens do not have to be separated by white space, 415*404b540aSrobertbut it is often necessary to avoid ambiguities. 416*404b540aSrobert 417*404b540aSrobert When faced with a sequence of characters that has more than one 418*404b540aSrobertpossible tokenization, the preprocessor is greedy. It always makes 419*404b540aSroberteach token, starting from the left, as big as possible before moving on 420*404b540aSrobertto the next token. For instance, `a+++++b' is interpreted as 421*404b540aSrobert`a ++ ++ + b', not as `a ++ + ++ b', even though the latter 422*404b540aSroberttokenization could be part of a valid C program and the former could 423*404b540aSrobertnot. 424*404b540aSrobert 425*404b540aSrobert Once the input file is broken into tokens, the token boundaries never 426*404b540aSrobertchange, except when the `##' preprocessing operator is used to paste 427*404b540aSroberttokens together. *Note Concatenation::. For example, 428*404b540aSrobert 429*404b540aSrobert #define foo() bar 430*404b540aSrobert foo()baz 431*404b540aSrobert ==> bar baz 432*404b540aSrobert _not_ 433*404b540aSrobert ==> barbaz 434*404b540aSrobert 435*404b540aSrobert The compiler does not re-tokenize the preprocessor's output. Each 436*404b540aSrobertpreprocessing token becomes one compiler token. 437*404b540aSrobert 438*404b540aSrobert Preprocessing tokens fall into five broad classes: identifiers, 439*404b540aSrobertpreprocessing numbers, string literals, punctuators, and other. An 440*404b540aSrobert"identifier" is the same as an identifier in C: any sequence of 441*404b540aSrobertletters, digits, or underscores, which begins with a letter or 442*404b540aSrobertunderscore. Keywords of C have no significance to the preprocessor; 443*404b540aSrobertthey are ordinary identifiers. You can define a macro whose name is a 444*404b540aSrobertkeyword, for instance. The only identifier which can be considered a 445*404b540aSrobertpreprocessing keyword is `defined'. *Note Defined::. 446*404b540aSrobert 447*404b540aSrobert This is mostly true of other languages which use the C preprocessor. 448*404b540aSrobertHowever, a few of the keywords of C++ are significant even in the 449*404b540aSrobertpreprocessor. *Note C++ Named Operators::. 450*404b540aSrobert 451*404b540aSrobert In the 1999 C standard, identifiers may contain letters which are not 452*404b540aSrobertpart of the "basic source character set", at the implementation's 453*404b540aSrobertdiscretion (such as accented Latin letters, Greek letters, or Chinese 454*404b540aSrobertideograms). This may be done with an extended character set, or the 455*404b540aSrobert`\u' and `\U' escape sequences. The implementation of this feature in 456*404b540aSrobertGCC is experimental; such characters are only accepted in the `\u' and 457*404b540aSrobert`\U' forms and only if `-fextended-identifiers' is used. 458*404b540aSrobert 459*404b540aSrobert As an extension, GCC treats `$' as a letter. This is for 460*404b540aSrobertcompatibility with some systems, such as VMS, where `$' is commonly 461*404b540aSrobertused in system-defined function and object names. `$' is not a letter 462*404b540aSrobertin strictly conforming mode, or if you specify the `-$' option. *Note 463*404b540aSrobertInvocation::. 464*404b540aSrobert 465*404b540aSrobert A "preprocessing number" has a rather bizarre definition. The 466*404b540aSrobertcategory includes all the normal integer and floating point constants 467*404b540aSrobertone expects of C, but also a number of other things one might not 468*404b540aSrobertinitially recognize as a number. Formally, preprocessing numbers begin 469*404b540aSrobertwith an optional period, a required decimal digit, and then continue 470*404b540aSrobertwith any sequence of letters, digits, underscores, periods, and 471*404b540aSrobertexponents. Exponents are the two-character sequences `e+', `e-', `E+', 472*404b540aSrobert`E-', `p+', `p-', `P+', and `P-'. (The exponents that begin with `p' 473*404b540aSrobertor `P' are new to C99. They are used for hexadecimal floating-point 474*404b540aSrobertconstants.) 475*404b540aSrobert 476*404b540aSrobert The purpose of this unusual definition is to isolate the preprocessor 477*404b540aSrobertfrom the full complexity of numeric constants. It does not have to 478*404b540aSrobertdistinguish between lexically valid and invalid floating-point numbers, 479*404b540aSrobertwhich is complicated. The definition also permits you to split an 480*404b540aSrobertidentifier at any position and get exactly two tokens, which can then be 481*404b540aSrobertpasted back together with the `##' operator. 482*404b540aSrobert 483*404b540aSrobert It's possible for preprocessing numbers to cause programs to be 484*404b540aSrobertmisinterpreted. For example, `0xE+12' is a preprocessing number which 485*404b540aSrobertdoes not translate to any valid numeric constant, therefore a syntax 486*404b540aSroberterror. It does not mean `0xE + 12', which is what you might have 487*404b540aSrobertintended. 488*404b540aSrobert 489*404b540aSrobert "String literals" are string constants, character constants, and 490*404b540aSrobertheader file names (the argument of `#include').(1) String constants 491*404b540aSrobertand character constants are straightforward: "..." or '...'. In either 492*404b540aSrobertcase embedded quotes should be escaped with a backslash: '\'' is the 493*404b540aSrobertcharacter constant for `''. There is no limit on the length of a 494*404b540aSrobertcharacter constant, but the value of a character constant that contains 495*404b540aSrobertmore than one character is implementation-defined. *Note 496*404b540aSrobertImplementation Details::. 497*404b540aSrobert 498*404b540aSrobert Header file names either look like string constants, "...", or are 499*404b540aSrobertwritten with angle brackets instead, <...>. In either case, backslash 500*404b540aSrobertis an ordinary character. There is no way to escape the closing quote 501*404b540aSrobertor angle bracket. The preprocessor looks for the header file in 502*404b540aSrobertdifferent places depending on which form you use. *Note Include 503*404b540aSrobertOperation::. 504*404b540aSrobert 505*404b540aSrobert No string literal may extend past the end of a line. Older versions 506*404b540aSrobertof GCC accepted multi-line string constants. You may use continued 507*404b540aSrobertlines instead, or string constant concatenation. *Note Differences 508*404b540aSrobertfrom previous versions::. 509*404b540aSrobert 510*404b540aSrobert "Punctuators" are all the usual bits of punctuation which are 511*404b540aSrobertmeaningful to C and C++. All but three of the punctuation characters in 512*404b540aSrobertASCII are C punctuators. The exceptions are `@', `$', and ``'. In 513*404b540aSrobertaddition, all the two- and three-character operators are punctuators. 514*404b540aSrobertThere are also six "digraphs", which the C++ standard calls 515*404b540aSrobert"alternative tokens", which are merely alternate ways to spell other 516*404b540aSrobertpunctuators. This is a second attempt to work around missing 517*404b540aSrobertpunctuation in obsolete systems. It has no negative side effects, 518*404b540aSrobertunlike trigraphs, but does not cover as much ground. The digraphs and 519*404b540aSroberttheir corresponding normal punctuators are: 520*404b540aSrobert 521*404b540aSrobert Digraph: <% %> <: :> %: %:%: 522*404b540aSrobert Punctuator: { } [ ] # ## 523*404b540aSrobert 524*404b540aSrobert Any other single character is considered "other". It is passed on to 525*404b540aSrobertthe preprocessor's output unmolested. The C compiler will almost 526*404b540aSrobertcertainly reject source code containing "other" tokens. In ASCII, the 527*404b540aSrobertonly other characters are `@', `$', ``', and control characters other 528*404b540aSrobertthan NUL (all bits zero). (Note that `$' is normally considered a 529*404b540aSrobertletter.) All characters with the high bit set (numeric range 530*404b540aSrobert0x7F-0xFF) are also "other" in the present implementation. This will 531*404b540aSrobertchange when proper support for international character sets is added to 532*404b540aSrobertGCC. 533*404b540aSrobert 534*404b540aSrobert NUL is a special case because of the high probability that its 535*404b540aSrobertappearance is accidental, and because it may be invisible to the user 536*404b540aSrobert(many terminals do not display NUL at all). Within comments, NULs are 537*404b540aSrobertsilently ignored, just as any other character would be. In running 538*404b540aSroberttext, NUL is considered white space. For example, these two directives 539*404b540aSroberthave the same meaning. 540*404b540aSrobert 541*404b540aSrobert #define X^@1 542*404b540aSrobert #define X 1 543*404b540aSrobert 544*404b540aSrobert(where `^@' is ASCII NUL). Within string or character constants, NULs 545*404b540aSrobertare preserved. In the latter two cases the preprocessor emits a 546*404b540aSrobertwarning message. 547*404b540aSrobert 548*404b540aSrobert ---------- Footnotes ---------- 549*404b540aSrobert 550*404b540aSrobert (1) The C standard uses the term "string literal" to refer only to 551*404b540aSrobertwhat we are calling "string constants". 552*404b540aSrobert 553*404b540aSrobert 554*404b540aSrobertFile: cpp.info, Node: The preprocessing language, Prev: Tokenization, Up: Overview 555*404b540aSrobert 556*404b540aSrobert1.4 The preprocessing language 557*404b540aSrobert============================== 558*404b540aSrobert 559*404b540aSrobertAfter tokenization, the stream of tokens may simply be passed straight 560*404b540aSrobertto the compiler's parser. However, if it contains any operations in the 561*404b540aSrobert"preprocessing language", it will be transformed first. This stage 562*404b540aSrobertcorresponds roughly to the standard's "translation phase 4" and is what 563*404b540aSrobertmost people think of as the preprocessor's job. 564*404b540aSrobert 565*404b540aSrobert The preprocessing language consists of "directives" to be executed 566*404b540aSrobertand "macros" to be expanded. Its primary capabilities are: 567*404b540aSrobert 568*404b540aSrobert * Inclusion of header files. These are files of declarations that 569*404b540aSrobert can be substituted into your program. 570*404b540aSrobert 571*404b540aSrobert * Macro expansion. You can define "macros", which are abbreviations 572*404b540aSrobert for arbitrary fragments of C code. The preprocessor will replace 573*404b540aSrobert the macros with their definitions throughout the program. Some 574*404b540aSrobert macros are automatically defined for you. 575*404b540aSrobert 576*404b540aSrobert * Conditional compilation. You can include or exclude parts of the 577*404b540aSrobert program according to various conditions. 578*404b540aSrobert 579*404b540aSrobert * Line control. If you use a program to combine or rearrange source 580*404b540aSrobert files into an intermediate file which is then compiled, you can 581*404b540aSrobert use line control to inform the compiler where each source line 582*404b540aSrobert originally came from. 583*404b540aSrobert 584*404b540aSrobert * Diagnostics. You can detect problems at compile time and issue 585*404b540aSrobert errors or warnings. 586*404b540aSrobert 587*404b540aSrobert There are a few more, less useful, features. 588*404b540aSrobert 589*404b540aSrobert Except for expansion of predefined macros, all these operations are 590*404b540aSroberttriggered with "preprocessing directives". Preprocessing directives 591*404b540aSrobertare lines in your program that start with `#'. Whitespace is allowed 592*404b540aSrobertbefore and after the `#'. The `#' is followed by an identifier, the 593*404b540aSrobert"directive name". It specifies the operation to perform. Directives 594*404b540aSrobertare commonly referred to as `#NAME' where NAME is the directive name. 595*404b540aSrobertFor example, `#define' is the directive that defines a macro. 596*404b540aSrobert 597*404b540aSrobert The `#' which begins a directive cannot come from a macro expansion. 598*404b540aSrobertAlso, the directive name is not macro expanded. Thus, if `foo' is 599*404b540aSrobertdefined as a macro expanding to `define', that does not make `#foo' a 600*404b540aSrobertvalid preprocessing directive. 601*404b540aSrobert 602*404b540aSrobert The set of valid directive names is fixed. Programs cannot define 603*404b540aSrobertnew preprocessing directives. 604*404b540aSrobert 605*404b540aSrobert Some directives require arguments; these make up the rest of the 606*404b540aSrobertdirective line and must be separated from the directive name by 607*404b540aSrobertwhitespace. For example, `#define' must be followed by a macro name 608*404b540aSrobertand the intended expansion of the macro. 609*404b540aSrobert 610*404b540aSrobert A preprocessing directive cannot cover more than one line. The line 611*404b540aSrobertmay, however, be continued with backslash-newline, or by a block comment 612*404b540aSrobertwhich extends past the end of the line. In either case, when the 613*404b540aSrobertdirective is processed, the continuations have already been merged with 614*404b540aSrobertthe first line to make one long line. 615*404b540aSrobert 616*404b540aSrobert 617*404b540aSrobertFile: cpp.info, Node: Header Files, Next: Macros, Prev: Overview, Up: Top 618*404b540aSrobert 619*404b540aSrobert2 Header Files 620*404b540aSrobert************** 621*404b540aSrobert 622*404b540aSrobertA header file is a file containing C declarations and macro definitions 623*404b540aSrobert(*note Macros::) to be shared between several source files. You request 624*404b540aSrobertthe use of a header file in your program by "including" it, with the C 625*404b540aSrobertpreprocessing directive `#include'. 626*404b540aSrobert 627*404b540aSrobert Header files serve two purposes. 628*404b540aSrobert 629*404b540aSrobert * System header files declare the interfaces to parts of the 630*404b540aSrobert operating system. You include them in your program to supply the 631*404b540aSrobert definitions and declarations you need to invoke system calls and 632*404b540aSrobert libraries. 633*404b540aSrobert 634*404b540aSrobert * Your own header files contain declarations for interfaces between 635*404b540aSrobert the source files of your program. Each time you have a group of 636*404b540aSrobert related declarations and macro definitions all or most of which 637*404b540aSrobert are needed in several different source files, it is a good idea to 638*404b540aSrobert create a header file for them. 639*404b540aSrobert 640*404b540aSrobert Including a header file produces the same results as copying the 641*404b540aSrobertheader file into each source file that needs it. Such copying would be 642*404b540aSroberttime-consuming and error-prone. With a header file, the related 643*404b540aSrobertdeclarations appear in only one place. If they need to be changed, they 644*404b540aSrobertcan be changed in one place, and programs that include the header file 645*404b540aSrobertwill automatically use the new version when next recompiled. The header 646*404b540aSrobertfile eliminates the labor of finding and changing all the copies as well 647*404b540aSrobertas the risk that a failure to find one copy will result in 648*404b540aSrobertinconsistencies within a program. 649*404b540aSrobert 650*404b540aSrobert In C, the usual convention is to give header files names that end 651*404b540aSrobertwith `.h'. It is most portable to use only letters, digits, dashes, and 652*404b540aSrobertunderscores in header file names, and at most one dot. 653*404b540aSrobert 654*404b540aSrobert* Menu: 655*404b540aSrobert 656*404b540aSrobert* Include Syntax:: 657*404b540aSrobert* Include Operation:: 658*404b540aSrobert* Search Path:: 659*404b540aSrobert* Once-Only Headers:: 660*404b540aSrobert* Computed Includes:: 661*404b540aSrobert* Wrapper Headers:: 662*404b540aSrobert* System Headers:: 663*404b540aSrobert 664*404b540aSrobert 665*404b540aSrobertFile: cpp.info, Node: Include Syntax, Next: Include Operation, Up: Header Files 666*404b540aSrobert 667*404b540aSrobert2.1 Include Syntax 668*404b540aSrobert================== 669*404b540aSrobert 670*404b540aSrobertBoth user and system header files are included using the preprocessing 671*404b540aSrobertdirective `#include'. It has two variants: 672*404b540aSrobert 673*404b540aSrobert`#include <FILE>' 674*404b540aSrobert This variant is used for system header files. It searches for a 675*404b540aSrobert file named FILE in a standard list of system directories. You can 676*404b540aSrobert prepend directories to this list with the `-I' option (*note 677*404b540aSrobert Invocation::). 678*404b540aSrobert 679*404b540aSrobert`#include "FILE"' 680*404b540aSrobert This variant is used for header files of your own program. It 681*404b540aSrobert searches for a file named FILE first in the directory containing 682*404b540aSrobert the current file, then in the quote directories and then the same 683*404b540aSrobert directories used for `<FILE>'. You can prepend directories to the 684*404b540aSrobert list of quote directories with the `-iquote' option. 685*404b540aSrobert 686*404b540aSrobert The argument of `#include', whether delimited with quote marks or 687*404b540aSrobertangle brackets, behaves like a string constant in that comments are not 688*404b540aSrobertrecognized, and macro names are not expanded. Thus, `#include <x/*y>' 689*404b540aSrobertspecifies inclusion of a system header file named `x/*y'. 690*404b540aSrobert 691*404b540aSrobert However, if backslashes occur within FILE, they are considered 692*404b540aSrobertordinary text characters, not escape characters. None of the character 693*404b540aSrobertescape sequences appropriate to string constants in C are processed. 694*404b540aSrobertThus, `#include "x\n\\y"' specifies a filename containing three 695*404b540aSrobertbackslashes. (Some systems interpret `\' as a pathname separator. All 696*404b540aSrobertof these also interpret `/' the same way. It is most portable to use 697*404b540aSrobertonly `/'.) 698*404b540aSrobert 699*404b540aSrobert It is an error if there is anything (other than comments) on the line 700*404b540aSrobertafter the file name. 701*404b540aSrobert 702*404b540aSrobert 703*404b540aSrobertFile: cpp.info, Node: Include Operation, Next: Search Path, Prev: Include Syntax, Up: Header Files 704*404b540aSrobert 705*404b540aSrobert2.2 Include Operation 706*404b540aSrobert===================== 707*404b540aSrobert 708*404b540aSrobertThe `#include' directive works by directing the C preprocessor to scan 709*404b540aSrobertthe specified file as input before continuing with the rest of the 710*404b540aSrobertcurrent file. The output from the preprocessor contains the output 711*404b540aSrobertalready generated, followed by the output resulting from the included 712*404b540aSrobertfile, followed by the output that comes from the text after the 713*404b540aSrobert`#include' directive. For example, if you have a header file 714*404b540aSrobert`header.h' as follows, 715*404b540aSrobert 716*404b540aSrobert char *test (void); 717*404b540aSrobert 718*404b540aSrobertand a main program called `program.c' that uses the header file, like 719*404b540aSrobertthis, 720*404b540aSrobert 721*404b540aSrobert int x; 722*404b540aSrobert #include "header.h" 723*404b540aSrobert 724*404b540aSrobert int 725*404b540aSrobert main (void) 726*404b540aSrobert { 727*404b540aSrobert puts (test ()); 728*404b540aSrobert } 729*404b540aSrobert 730*404b540aSrobertthe compiler will see the same token stream as it would if `program.c' 731*404b540aSrobertread 732*404b540aSrobert 733*404b540aSrobert int x; 734*404b540aSrobert char *test (void); 735*404b540aSrobert 736*404b540aSrobert int 737*404b540aSrobert main (void) 738*404b540aSrobert { 739*404b540aSrobert puts (test ()); 740*404b540aSrobert } 741*404b540aSrobert 742*404b540aSrobert Included files are not limited to declarations and macro definitions; 743*404b540aSrobertthose are merely the typical uses. Any fragment of a C program can be 744*404b540aSrobertincluded from another file. The include file could even contain the 745*404b540aSrobertbeginning of a statement that is concluded in the containing file, or 746*404b540aSrobertthe end of a statement that was started in the including file. However, 747*404b540aSrobertan included file must consist of complete tokens. Comments and string 748*404b540aSrobertliterals which have not been closed by the end of an included file are 749*404b540aSrobertinvalid. For error recovery, they are considered to end at the end of 750*404b540aSrobertthe file. 751*404b540aSrobert 752*404b540aSrobert To avoid confusion, it is best if header files contain only complete 753*404b540aSrobertsyntactic units--function declarations or definitions, type 754*404b540aSrobertdeclarations, etc. 755*404b540aSrobert 756*404b540aSrobert The line following the `#include' directive is always treated as a 757*404b540aSrobertseparate line by the C preprocessor, even if the included file lacks a 758*404b540aSrobertfinal newline. 759*404b540aSrobert 760*404b540aSrobert 761*404b540aSrobertFile: cpp.info, Node: Search Path, Next: Once-Only Headers, Prev: Include Operation, Up: Header Files 762*404b540aSrobert 763*404b540aSrobert2.3 Search Path 764*404b540aSrobert=============== 765*404b540aSrobert 766*404b540aSrobertGCC looks in several different places for headers. On a normal Unix 767*404b540aSrobertsystem, if you do not instruct it otherwise, it will look for headers 768*404b540aSrobertrequested with `#include <FILE>' in: 769*404b540aSrobert 770*404b540aSrobert /usr/local/include 771*404b540aSrobert LIBDIR/gcc/TARGET/VERSION/include 772*404b540aSrobert /usr/TARGET/include 773*404b540aSrobert /usr/include 774*404b540aSrobert 775*404b540aSrobert For C++ programs, it will also look in `/usr/include/g++-v3', first. 776*404b540aSrobertIn the above, TARGET is the canonical name of the system GCC was 777*404b540aSrobertconfigured to compile code for; often but not always the same as the 778*404b540aSrobertcanonical name of the system it runs on. VERSION is the version of GCC 779*404b540aSrobertin use. 780*404b540aSrobert 781*404b540aSrobert You can add to this list with the `-IDIR' command line option. All 782*404b540aSrobertthe directories named by `-I' are searched, in left-to-right order, 783*404b540aSrobert_before_ the default directories. The only exception is when `dir' is 784*404b540aSrobertalready searched by default. In this case, the option is ignored and 785*404b540aSrobertthe search order for system directories remains unchanged. 786*404b540aSrobert 787*404b540aSrobert Duplicate directories are removed from the quote and bracket search 788*404b540aSrobertchains before the two chains are merged to make the final search chain. 789*404b540aSrobertThus, it is possible for a directory to occur twice in the final search 790*404b540aSrobertchain if it was specified in both the quote and bracket chains. 791*404b540aSrobert 792*404b540aSrobert You can prevent GCC from searching any of the default directories 793*404b540aSrobertwith the `-nostdinc' option. This is useful when you are compiling an 794*404b540aSrobertoperating system kernel or some other program that does not use the 795*404b540aSrobertstandard C library facilities, or the standard C library itself. `-I' 796*404b540aSrobertoptions are not ignored as described above when `-nostdinc' is in 797*404b540aSroberteffect. 798*404b540aSrobert 799*404b540aSrobert GCC looks for headers requested with `#include "FILE"' first in the 800*404b540aSrobertdirectory containing the current file, then in the directories as 801*404b540aSrobertspecified by `-iquote' options, then in the same places it would have 802*404b540aSrobertlooked for a header requested with angle brackets. For example, if 803*404b540aSrobert`/usr/include/sys/stat.h' contains `#include "types.h"', GCC looks for 804*404b540aSrobert`types.h' first in `/usr/include/sys', then in its usual search path. 805*404b540aSrobert 806*404b540aSrobert `#line' (*note Line Control::) does not change GCC's idea of the 807*404b540aSrobertdirectory containing the current file. 808*404b540aSrobert 809*404b540aSrobert You may put `-I-' at any point in your list of `-I' options. This 810*404b540aSroberthas two effects. First, directories appearing before the `-I-' in the 811*404b540aSrobertlist are searched only for headers requested with quote marks. 812*404b540aSrobertDirectories after `-I-' are searched for all headers. Second, the 813*404b540aSrobertdirectory containing the current file is not searched for anything, 814*404b540aSrobertunless it happens to be one of the directories named by an `-I' switch. 815*404b540aSrobert`-I-' is deprecated, `-iquote' should be used instead. 816*404b540aSrobert 817*404b540aSrobert `-I. -I-' is not the same as no `-I' options at all, and does not 818*404b540aSrobertcause the same behavior for `<>' includes that `""' includes get with 819*404b540aSrobertno special options. `-I.' searches the compiler's current working 820*404b540aSrobertdirectory for header files. That may or may not be the same as the 821*404b540aSrobertdirectory containing the current file. 822*404b540aSrobert 823*404b540aSrobert If you need to look for headers in a directory named `-', write 824*404b540aSrobert`-I./-'. 825*404b540aSrobert 826*404b540aSrobert There are several more ways to adjust the header search path. They 827*404b540aSrobertare generally less useful. *Note Invocation::. 828*404b540aSrobert 829*404b540aSrobert 830*404b540aSrobertFile: cpp.info, Node: Once-Only Headers, Next: Computed Includes, Prev: Search Path, Up: Header Files 831*404b540aSrobert 832*404b540aSrobert2.4 Once-Only Headers 833*404b540aSrobert===================== 834*404b540aSrobert 835*404b540aSrobertIf a header file happens to be included twice, the compiler will process 836*404b540aSrobertits contents twice. This is very likely to cause an error, e.g. when 837*404b540aSrobertthe compiler sees the same structure definition twice. Even if it does 838*404b540aSrobertnot, it will certainly waste time. 839*404b540aSrobert 840*404b540aSrobert The standard way to prevent this is to enclose the entire real 841*404b540aSrobertcontents of the file in a conditional, like this: 842*404b540aSrobert 843*404b540aSrobert /* File foo. */ 844*404b540aSrobert #ifndef FILE_FOO_SEEN 845*404b540aSrobert #define FILE_FOO_SEEN 846*404b540aSrobert 847*404b540aSrobert THE ENTIRE FILE 848*404b540aSrobert 849*404b540aSrobert #endif /* !FILE_FOO_SEEN */ 850*404b540aSrobert 851*404b540aSrobert This construct is commonly known as a "wrapper #ifndef". When the 852*404b540aSrobertheader is included again, the conditional will be false, because 853*404b540aSrobert`FILE_FOO_SEEN' is defined. The preprocessor will skip over the entire 854*404b540aSrobertcontents of the file, and the compiler will not see it twice. 855*404b540aSrobert 856*404b540aSrobert CPP optimizes even further. It remembers when a header file has a 857*404b540aSrobertwrapper `#ifndef'. If a subsequent `#include' specifies that header, 858*404b540aSrobertand the macro in the `#ifndef' is still defined, it does not bother to 859*404b540aSrobertrescan the file at all. 860*404b540aSrobert 861*404b540aSrobert You can put comments outside the wrapper. They will not interfere 862*404b540aSrobertwith this optimization. 863*404b540aSrobert 864*404b540aSrobert The macro `FILE_FOO_SEEN' is called the "controlling macro" or 865*404b540aSrobert"guard macro". In a user header file, the macro name should not begin 866*404b540aSrobertwith `_'. In a system header file, it should begin with `__' to avoid 867*404b540aSrobertconflicts with user programs. In any kind of header file, the macro 868*404b540aSrobertname should contain the name of the file and some additional text, to 869*404b540aSrobertavoid conflicts with other header files. 870*404b540aSrobert 871*404b540aSrobert 872*404b540aSrobertFile: cpp.info, Node: Computed Includes, Next: Wrapper Headers, Prev: Once-Only Headers, Up: Header Files 873*404b540aSrobert 874*404b540aSrobert2.5 Computed Includes 875*404b540aSrobert===================== 876*404b540aSrobert 877*404b540aSrobertSometimes it is necessary to select one of several different header 878*404b540aSrobertfiles to be included into your program. They might specify 879*404b540aSrobertconfiguration parameters to be used on different sorts of operating 880*404b540aSrobertsystems, for instance. You could do this with a series of conditionals, 881*404b540aSrobert 882*404b540aSrobert #if SYSTEM_1 883*404b540aSrobert # include "system_1.h" 884*404b540aSrobert #elif SYSTEM_2 885*404b540aSrobert # include "system_2.h" 886*404b540aSrobert #elif SYSTEM_3 887*404b540aSrobert ... 888*404b540aSrobert #endif 889*404b540aSrobert 890*404b540aSrobert That rapidly becomes tedious. Instead, the preprocessor offers the 891*404b540aSrobertability to use a macro for the header name. This is called a "computed 892*404b540aSrobertinclude". Instead of writing a header name as the direct argument of 893*404b540aSrobert`#include', you simply put a macro name there instead: 894*404b540aSrobert 895*404b540aSrobert #define SYSTEM_H "system_1.h" 896*404b540aSrobert ... 897*404b540aSrobert #include SYSTEM_H 898*404b540aSrobert 899*404b540aSrobert`SYSTEM_H' will be expanded, and the preprocessor will look for 900*404b540aSrobert`system_1.h' as if the `#include' had been written that way originally. 901*404b540aSrobert`SYSTEM_H' could be defined by your Makefile with a `-D' option. 902*404b540aSrobert 903*404b540aSrobert You must be careful when you define the macro. `#define' saves 904*404b540aSroberttokens, not text. The preprocessor has no way of knowing that the macro 905*404b540aSrobertwill be used as the argument of `#include', so it generates ordinary 906*404b540aSroberttokens, not a header name. This is unlikely to cause problems if you 907*404b540aSrobertuse double-quote includes, which are close enough to string constants. 908*404b540aSrobertIf you use angle brackets, however, you may have trouble. 909*404b540aSrobert 910*404b540aSrobert The syntax of a computed include is actually a bit more general than 911*404b540aSrobertthe above. If the first non-whitespace character after `#include' is 912*404b540aSrobertnot `"' or `<', then the entire line is macro-expanded like running 913*404b540aSroberttext would be. 914*404b540aSrobert 915*404b540aSrobert If the line expands to a single string constant, the contents of that 916*404b540aSrobertstring constant are the file to be included. CPP does not re-examine 917*404b540aSrobertthe string for embedded quotes, but neither does it process backslash 918*404b540aSrobertescapes in the string. Therefore 919*404b540aSrobert 920*404b540aSrobert #define HEADER "a\"b" 921*404b540aSrobert #include HEADER 922*404b540aSrobert 923*404b540aSrobertlooks for a file named `a\"b'. CPP searches for the file according to 924*404b540aSrobertthe rules for double-quoted includes. 925*404b540aSrobert 926*404b540aSrobert If the line expands to a token stream beginning with a `<' token and 927*404b540aSrobertincluding a `>' token, then the tokens between the `<' and the first 928*404b540aSrobert`>' are combined to form the filename to be included. Any whitespace 929*404b540aSrobertbetween tokens is reduced to a single space; then any space after the 930*404b540aSrobertinitial `<' is retained, but a trailing space before the closing `>' is 931*404b540aSrobertignored. CPP searches for the file according to the rules for 932*404b540aSrobertangle-bracket includes. 933*404b540aSrobert 934*404b540aSrobert In either case, if there are any tokens on the line after the file 935*404b540aSrobertname, an error occurs and the directive is not processed. It is also 936*404b540aSrobertan error if the result of expansion does not match either of the two 937*404b540aSrobertexpected forms. 938*404b540aSrobert 939*404b540aSrobert These rules are implementation-defined behavior according to the C 940*404b540aSrobertstandard. To minimize the risk of different compilers interpreting your 941*404b540aSrobertcomputed includes differently, we recommend you use only a single 942*404b540aSrobertobject-like macro which expands to a string constant. This will also 943*404b540aSrobertminimize confusion for people reading your program. 944*404b540aSrobert 945*404b540aSrobert 946*404b540aSrobertFile: cpp.info, Node: Wrapper Headers, Next: System Headers, Prev: Computed Includes, Up: Header Files 947*404b540aSrobert 948*404b540aSrobert2.6 Wrapper Headers 949*404b540aSrobert=================== 950*404b540aSrobert 951*404b540aSrobertSometimes it is necessary to adjust the contents of a system-provided 952*404b540aSrobertheader file without editing it directly. GCC's `fixincludes' operation 953*404b540aSrobertdoes this, for example. One way to do that would be to create a new 954*404b540aSrobertheader file with the same name and insert it in the search path before 955*404b540aSrobertthe original header. That works fine as long as you're willing to 956*404b540aSrobertreplace the old header entirely. But what if you want to refer to the 957*404b540aSrobertold header from the new one? 958*404b540aSrobert 959*404b540aSrobert You cannot simply include the old header with `#include'. That will 960*404b540aSrobertstart from the beginning, and find your new header again. If your 961*404b540aSrobertheader is not protected from multiple inclusion (*note Once-Only 962*404b540aSrobertHeaders::), it will recurse infinitely and cause a fatal error. 963*404b540aSrobert 964*404b540aSrobert You could include the old header with an absolute pathname: 965*404b540aSrobert #include "/usr/include/old-header.h" 966*404b540aSrobert This works, but is not clean; should the system headers ever move, 967*404b540aSrobertyou would have to edit the new headers to match. 968*404b540aSrobert 969*404b540aSrobert There is no way to solve this problem within the C standard, but you 970*404b540aSrobertcan use the GNU extension `#include_next'. It means, "Include the 971*404b540aSrobert_next_ file with this name". This directive works like `#include' 972*404b540aSrobertexcept in searching for the specified file: it starts searching the 973*404b540aSrobertlist of header file directories _after_ the directory in which the 974*404b540aSrobertcurrent file was found. 975*404b540aSrobert 976*404b540aSrobert Suppose you specify `-I /usr/local/include', and the list of 977*404b540aSrobertdirectories to search also includes `/usr/include'; and suppose both 978*404b540aSrobertdirectories contain `signal.h'. Ordinary `#include <signal.h>' finds 979*404b540aSrobertthe file under `/usr/local/include'. If that file contains 980*404b540aSrobert`#include_next <signal.h>', it starts searching after that directory, 981*404b540aSrobertand finds the file in `/usr/include'. 982*404b540aSrobert 983*404b540aSrobert `#include_next' does not distinguish between `<FILE>' and `"FILE"' 984*404b540aSrobertinclusion, nor does it check that the file you specify has the same 985*404b540aSrobertname as the current file. It simply looks for the file named, starting 986*404b540aSrobertwith the directory in the search path after the one where the current 987*404b540aSrobertfile was found. 988*404b540aSrobert 989*404b540aSrobert The use of `#include_next' can lead to great confusion. We 990*404b540aSrobertrecommend it be used only when there is no other alternative. In 991*404b540aSrobertparticular, it should not be used in the headers belonging to a specific 992*404b540aSrobertprogram; it should be used only to make global corrections along the 993*404b540aSrobertlines of `fixincludes'. 994*404b540aSrobert 995*404b540aSrobert 996*404b540aSrobertFile: cpp.info, Node: System Headers, Prev: Wrapper Headers, Up: Header Files 997*404b540aSrobert 998*404b540aSrobert2.7 System Headers 999*404b540aSrobert================== 1000*404b540aSrobert 1001*404b540aSrobertThe header files declaring interfaces to the operating system and 1002*404b540aSrobertruntime libraries often cannot be written in strictly conforming C. 1003*404b540aSrobertTherefore, GCC gives code found in "system headers" special treatment. 1004*404b540aSrobertAll warnings, other than those generated by `#warning' (*note 1005*404b540aSrobertDiagnostics::), are suppressed while GCC is processing a system header. 1006*404b540aSrobertMacros defined in a system header are immune to a few warnings 1007*404b540aSrobertwherever they are expanded. This immunity is granted on an ad-hoc 1008*404b540aSrobertbasis, when we find that a warning generates lots of false positives 1009*404b540aSrobertbecause of code in macros defined in system headers. 1010*404b540aSrobert 1011*404b540aSrobert Normally, only the headers found in specific directories are 1012*404b540aSrobertconsidered system headers. These directories are determined when GCC 1013*404b540aSrobertis compiled. There are, however, two ways to make normal headers into 1014*404b540aSrobertsystem headers. 1015*404b540aSrobert 1016*404b540aSrobert The `-isystem' command line option adds its argument to the list of 1017*404b540aSrobertdirectories to search for headers, just like `-I'. Any headers found 1018*404b540aSrobertin that directory will be considered system headers. 1019*404b540aSrobert 1020*404b540aSrobert All directories named by `-isystem' are searched _after_ all 1021*404b540aSrobertdirectories named by `-I', no matter what their order was on the 1022*404b540aSrobertcommand line. If the same directory is named by both `-I' and 1023*404b540aSrobert`-isystem', the `-I' option is ignored. GCC provides an informative 1024*404b540aSrobertmessage when this occurs if `-v' is used. 1025*404b540aSrobert 1026*404b540aSrobert There is also a directive, `#pragma GCC system_header', which tells 1027*404b540aSrobertGCC to consider the rest of the current include file a system header, 1028*404b540aSrobertno matter where it was found. Code that comes before the `#pragma' in 1029*404b540aSrobertthe file will not be affected. `#pragma GCC system_header' has no 1030*404b540aSroberteffect in the primary source file. 1031*404b540aSrobert 1032*404b540aSrobert On very old systems, some of the pre-defined system header 1033*404b540aSrobertdirectories get even more special treatment. GNU C++ considers code in 1034*404b540aSrobertheaders found in those directories to be surrounded by an `extern "C"' 1035*404b540aSrobertblock. There is no way to request this behavior with a `#pragma', or 1036*404b540aSrobertfrom the command line. 1037*404b540aSrobert 1038*404b540aSrobert 1039*404b540aSrobertFile: cpp.info, Node: Macros, Next: Conditionals, Prev: Header Files, Up: Top 1040*404b540aSrobert 1041*404b540aSrobert3 Macros 1042*404b540aSrobert******** 1043*404b540aSrobert 1044*404b540aSrobertA "macro" is a fragment of code which has been given a name. Whenever 1045*404b540aSrobertthe name is used, it is replaced by the contents of the macro. There 1046*404b540aSrobertare two kinds of macros. They differ mostly in what they look like 1047*404b540aSrobertwhen they are used. "Object-like" macros resemble data objects when 1048*404b540aSrobertused, "function-like" macros resemble function calls. 1049*404b540aSrobert 1050*404b540aSrobert You may define any valid identifier as a macro, even if it is a C 1051*404b540aSrobertkeyword. The preprocessor does not know anything about keywords. This 1052*404b540aSrobertcan be useful if you wish to hide a keyword such as `const' from an 1053*404b540aSrobertolder compiler that does not understand it. However, the preprocessor 1054*404b540aSrobertoperator `defined' (*note Defined::) can never be defined as a macro, 1055*404b540aSrobertand C++'s named operators (*note C++ Named Operators::) cannot be 1056*404b540aSrobertmacros when you are compiling C++. 1057*404b540aSrobert 1058*404b540aSrobert* Menu: 1059*404b540aSrobert 1060*404b540aSrobert* Object-like Macros:: 1061*404b540aSrobert* Function-like Macros:: 1062*404b540aSrobert* Macro Arguments:: 1063*404b540aSrobert* Stringification:: 1064*404b540aSrobert* Concatenation:: 1065*404b540aSrobert* Variadic Macros:: 1066*404b540aSrobert* Predefined Macros:: 1067*404b540aSrobert* Undefining and Redefining Macros:: 1068*404b540aSrobert* Directives Within Macro Arguments:: 1069*404b540aSrobert* Macro Pitfalls:: 1070*404b540aSrobert 1071*404b540aSrobert 1072*404b540aSrobertFile: cpp.info, Node: Object-like Macros, Next: Function-like Macros, Up: Macros 1073*404b540aSrobert 1074*404b540aSrobert3.1 Object-like Macros 1075*404b540aSrobert====================== 1076*404b540aSrobert 1077*404b540aSrobertAn "object-like macro" is a simple identifier which will be replaced by 1078*404b540aSroberta code fragment. It is called object-like because it looks like a data 1079*404b540aSrobertobject in code that uses it. They are most commonly used to give 1080*404b540aSrobertsymbolic names to numeric constants. 1081*404b540aSrobert 1082*404b540aSrobert You create macros with the `#define' directive. `#define' is 1083*404b540aSrobertfollowed by the name of the macro and then the token sequence it should 1084*404b540aSrobertbe an abbreviation for, which is variously referred to as the macro's 1085*404b540aSrobert"body", "expansion" or "replacement list". For example, 1086*404b540aSrobert 1087*404b540aSrobert #define BUFFER_SIZE 1024 1088*404b540aSrobert 1089*404b540aSrobertdefines a macro named `BUFFER_SIZE' as an abbreviation for the token 1090*404b540aSrobert`1024'. If somewhere after this `#define' directive there comes a C 1091*404b540aSrobertstatement of the form 1092*404b540aSrobert 1093*404b540aSrobert foo = (char *) malloc (BUFFER_SIZE); 1094*404b540aSrobert 1095*404b540aSrobertthen the C preprocessor will recognize and "expand" the macro 1096*404b540aSrobert`BUFFER_SIZE'. The C compiler will see the same tokens as it would if 1097*404b540aSrobertyou had written 1098*404b540aSrobert 1099*404b540aSrobert foo = (char *) malloc (1024); 1100*404b540aSrobert 1101*404b540aSrobert By convention, macro names are written in uppercase. Programs are 1102*404b540aSroberteasier to read when it is possible to tell at a glance which names are 1103*404b540aSrobertmacros. 1104*404b540aSrobert 1105*404b540aSrobert The macro's body ends at the end of the `#define' line. You may 1106*404b540aSrobertcontinue the definition onto multiple lines, if necessary, using 1107*404b540aSrobertbackslash-newline. When the macro is expanded, however, it will all 1108*404b540aSrobertcome out on one line. For example, 1109*404b540aSrobert 1110*404b540aSrobert #define NUMBERS 1, \ 1111*404b540aSrobert 2, \ 1112*404b540aSrobert 3 1113*404b540aSrobert int x[] = { NUMBERS }; 1114*404b540aSrobert ==> int x[] = { 1, 2, 3 }; 1115*404b540aSrobert 1116*404b540aSrobertThe most common visible consequence of this is surprising line numbers 1117*404b540aSrobertin error messages. 1118*404b540aSrobert 1119*404b540aSrobert There is no restriction on what can go in a macro body provided it 1120*404b540aSrobertdecomposes into valid preprocessing tokens. Parentheses need not 1121*404b540aSrobertbalance, and the body need not resemble valid C code. (If it does not, 1122*404b540aSrobertyou may get error messages from the C compiler when you use the macro.) 1123*404b540aSrobert 1124*404b540aSrobert The C preprocessor scans your program sequentially. Macro 1125*404b540aSrobertdefinitions take effect at the place you write them. Therefore, the 1126*404b540aSrobertfollowing input to the C preprocessor 1127*404b540aSrobert 1128*404b540aSrobert foo = X; 1129*404b540aSrobert #define X 4 1130*404b540aSrobert bar = X; 1131*404b540aSrobert 1132*404b540aSrobertproduces 1133*404b540aSrobert 1134*404b540aSrobert foo = X; 1135*404b540aSrobert bar = 4; 1136*404b540aSrobert 1137*404b540aSrobert When the preprocessor expands a macro name, the macro's expansion 1138*404b540aSrobertreplaces the macro invocation, then the expansion is examined for more 1139*404b540aSrobertmacros to expand. For example, 1140*404b540aSrobert 1141*404b540aSrobert #define TABLESIZE BUFSIZE 1142*404b540aSrobert #define BUFSIZE 1024 1143*404b540aSrobert TABLESIZE 1144*404b540aSrobert ==> BUFSIZE 1145*404b540aSrobert ==> 1024 1146*404b540aSrobert 1147*404b540aSrobert`TABLESIZE' is expanded first to produce `BUFSIZE', then that macro is 1148*404b540aSrobertexpanded to produce the final result, `1024'. 1149*404b540aSrobert 1150*404b540aSrobert Notice that `BUFSIZE' was not defined when `TABLESIZE' was defined. 1151*404b540aSrobertThe `#define' for `TABLESIZE' uses exactly the expansion you 1152*404b540aSrobertspecify--in this case, `BUFSIZE'--and does not check to see whether it 1153*404b540aSroberttoo contains macro names. Only when you _use_ `TABLESIZE' is the 1154*404b540aSrobertresult of its expansion scanned for more macro names. 1155*404b540aSrobert 1156*404b540aSrobert This makes a difference if you change the definition of `BUFSIZE' at 1157*404b540aSrobertsome point in the source file. `TABLESIZE', defined as shown, will 1158*404b540aSrobertalways expand using the definition of `BUFSIZE' that is currently in 1159*404b540aSroberteffect: 1160*404b540aSrobert 1161*404b540aSrobert #define BUFSIZE 1020 1162*404b540aSrobert #define TABLESIZE BUFSIZE 1163*404b540aSrobert #undef BUFSIZE 1164*404b540aSrobert #define BUFSIZE 37 1165*404b540aSrobert 1166*404b540aSrobertNow `TABLESIZE' expands (in two stages) to `37'. 1167*404b540aSrobert 1168*404b540aSrobert If the expansion of a macro contains its own name, either directly or 1169*404b540aSrobertvia intermediate macros, it is not expanded again when the expansion is 1170*404b540aSrobertexamined for more macros. This prevents infinite recursion. *Note 1171*404b540aSrobertSelf-Referential Macros::, for the precise details. 1172*404b540aSrobert 1173*404b540aSrobert 1174*404b540aSrobertFile: cpp.info, Node: Function-like Macros, Next: Macro Arguments, Prev: Object-like Macros, Up: Macros 1175*404b540aSrobert 1176*404b540aSrobert3.2 Function-like Macros 1177*404b540aSrobert======================== 1178*404b540aSrobert 1179*404b540aSrobertYou can also define macros whose use looks like a function call. These 1180*404b540aSrobertare called "function-like macros". To define a function-like macro, 1181*404b540aSrobertyou use the same `#define' directive, but you put a pair of parentheses 1182*404b540aSrobertimmediately after the macro name. For example, 1183*404b540aSrobert 1184*404b540aSrobert #define lang_init() c_init() 1185*404b540aSrobert lang_init() 1186*404b540aSrobert ==> c_init() 1187*404b540aSrobert 1188*404b540aSrobert A function-like macro is only expanded if its name appears with a 1189*404b540aSrobertpair of parentheses after it. If you write just the name, it is left 1190*404b540aSrobertalone. This can be useful when you have a function and a macro of the 1191*404b540aSrobertsame name, and you wish to use the function sometimes. 1192*404b540aSrobert 1193*404b540aSrobert extern void foo(void); 1194*404b540aSrobert #define foo() /* optimized inline version */ 1195*404b540aSrobert ... 1196*404b540aSrobert foo(); 1197*404b540aSrobert funcptr = foo; 1198*404b540aSrobert 1199*404b540aSrobert Here the call to `foo()' will use the macro, but the function 1200*404b540aSrobertpointer will get the address of the real function. If the macro were to 1201*404b540aSrobertbe expanded, it would cause a syntax error. 1202*404b540aSrobert 1203*404b540aSrobert If you put spaces between the macro name and the parentheses in the 1204*404b540aSrobertmacro definition, that does not define a function-like macro, it defines 1205*404b540aSrobertan object-like macro whose expansion happens to begin with a pair of 1206*404b540aSrobertparentheses. 1207*404b540aSrobert 1208*404b540aSrobert #define lang_init () c_init() 1209*404b540aSrobert lang_init() 1210*404b540aSrobert ==> () c_init()() 1211*404b540aSrobert 1212*404b540aSrobert The first two pairs of parentheses in this expansion come from the 1213*404b540aSrobertmacro. The third is the pair that was originally after the macro 1214*404b540aSrobertinvocation. Since `lang_init' is an object-like macro, it does not 1215*404b540aSrobertconsume those parentheses. 1216*404b540aSrobert 1217*404b540aSrobert 1218*404b540aSrobertFile: cpp.info, Node: Macro Arguments, Next: Stringification, Prev: Function-like Macros, Up: Macros 1219*404b540aSrobert 1220*404b540aSrobert3.3 Macro Arguments 1221*404b540aSrobert=================== 1222*404b540aSrobert 1223*404b540aSrobertFunction-like macros can take "arguments", just like true functions. 1224*404b540aSrobertTo define a macro that uses arguments, you insert "parameters" between 1225*404b540aSrobertthe pair of parentheses in the macro definition that make the macro 1226*404b540aSrobertfunction-like. The parameters must be valid C identifiers, separated 1227*404b540aSrobertby commas and optionally whitespace. 1228*404b540aSrobert 1229*404b540aSrobert To invoke a macro that takes arguments, you write the name of the 1230*404b540aSrobertmacro followed by a list of "actual arguments" in parentheses, separated 1231*404b540aSrobertby commas. The invocation of the macro need not be restricted to a 1232*404b540aSrobertsingle logical line--it can cross as many lines in the source file as 1233*404b540aSrobertyou wish. The number of arguments you give must match the number of 1234*404b540aSrobertparameters in the macro definition. When the macro is expanded, each 1235*404b540aSrobertuse of a parameter in its body is replaced by the tokens of the 1236*404b540aSrobertcorresponding argument. (You need not use all of the parameters in the 1237*404b540aSrobertmacro body.) 1238*404b540aSrobert 1239*404b540aSrobert As an example, here is a macro that computes the minimum of two 1240*404b540aSrobertnumeric values, as it is defined in many C programs, and some uses. 1241*404b540aSrobert 1242*404b540aSrobert #define min(X, Y) ((X) < (Y) ? (X) : (Y)) 1243*404b540aSrobert x = min(a, b); ==> x = ((a) < (b) ? (a) : (b)); 1244*404b540aSrobert y = min(1, 2); ==> y = ((1) < (2) ? (1) : (2)); 1245*404b540aSrobert z = min(a + 28, *p); ==> z = ((a + 28) < (*p) ? (a + 28) : (*p)); 1246*404b540aSrobert 1247*404b540aSrobert(In this small example you can already see several of the dangers of 1248*404b540aSrobertmacro arguments. *Note Macro Pitfalls::, for detailed explanations.) 1249*404b540aSrobert 1250*404b540aSrobert Leading and trailing whitespace in each argument is dropped, and all 1251*404b540aSrobertwhitespace between the tokens of an argument is reduced to a single 1252*404b540aSrobertspace. Parentheses within each argument must balance; a comma within 1253*404b540aSrobertsuch parentheses does not end the argument. However, there is no 1254*404b540aSrobertrequirement for square brackets or braces to balance, and they do not 1255*404b540aSrobertprevent a comma from separating arguments. Thus, 1256*404b540aSrobert 1257*404b540aSrobert macro (array[x = y, x + 1]) 1258*404b540aSrobert 1259*404b540aSrobertpasses two arguments to `macro': `array[x = y' and `x + 1]'. If you 1260*404b540aSrobertwant to supply `array[x = y, x + 1]' as an argument, you can write it 1261*404b540aSrobertas `array[(x = y, x + 1)]', which is equivalent C code. 1262*404b540aSrobert 1263*404b540aSrobert All arguments to a macro are completely macro-expanded before they 1264*404b540aSrobertare substituted into the macro body. After substitution, the complete 1265*404b540aSroberttext is scanned again for macros to expand, including the arguments. 1266*404b540aSrobertThis rule may seem strange, but it is carefully designed so you need 1267*404b540aSrobertnot worry about whether any function call is actually a macro 1268*404b540aSrobertinvocation. You can run into trouble if you try to be too clever, 1269*404b540aSrobertthough. *Note Argument Prescan::, for detailed discussion. 1270*404b540aSrobert 1271*404b540aSrobert For example, `min (min (a, b), c)' is first expanded to 1272*404b540aSrobert 1273*404b540aSrobert min (((a) < (b) ? (a) : (b)), (c)) 1274*404b540aSrobert 1275*404b540aSrobertand then to 1276*404b540aSrobert 1277*404b540aSrobert ((((a) < (b) ? (a) : (b))) < (c) 1278*404b540aSrobert ? (((a) < (b) ? (a) : (b))) 1279*404b540aSrobert : (c)) 1280*404b540aSrobert 1281*404b540aSrobert(Line breaks shown here for clarity would not actually be generated.) 1282*404b540aSrobert 1283*404b540aSrobert You can leave macro arguments empty; this is not an error to the 1284*404b540aSrobertpreprocessor (but many macros will then expand to invalid code). You 1285*404b540aSrobertcannot leave out arguments entirely; if a macro takes two arguments, 1286*404b540aSrobertthere must be exactly one comma at the top level of its argument list. 1287*404b540aSrobertHere are some silly examples using `min': 1288*404b540aSrobert 1289*404b540aSrobert min(, b) ==> (( ) < (b) ? ( ) : (b)) 1290*404b540aSrobert min(a, ) ==> ((a ) < ( ) ? (a ) : ( )) 1291*404b540aSrobert min(,) ==> (( ) < ( ) ? ( ) : ( )) 1292*404b540aSrobert min((,),) ==> (((,)) < ( ) ? ((,)) : ( )) 1293*404b540aSrobert 1294*404b540aSrobert min() error--> macro "min" requires 2 arguments, but only 1 given 1295*404b540aSrobert min(,,) error--> macro "min" passed 3 arguments, but takes just 2 1296*404b540aSrobert 1297*404b540aSrobert Whitespace is not a preprocessing token, so if a macro `foo' takes 1298*404b540aSrobertone argument, `foo ()' and `foo ( )' both supply it an empty argument. 1299*404b540aSrobertPrevious GNU preprocessor implementations and documentation were 1300*404b540aSrobertincorrect on this point, insisting that a function-like macro that 1301*404b540aSroberttakes a single argument be passed a space if an empty argument was 1302*404b540aSrobertrequired. 1303*404b540aSrobert 1304*404b540aSrobert Macro parameters appearing inside string literals are not replaced by 1305*404b540aSroberttheir corresponding actual arguments. 1306*404b540aSrobert 1307*404b540aSrobert #define foo(x) x, "x" 1308*404b540aSrobert foo(bar) ==> bar, "x" 1309*404b540aSrobert 1310*404b540aSrobert 1311*404b540aSrobertFile: cpp.info, Node: Stringification, Next: Concatenation, Prev: Macro Arguments, Up: Macros 1312*404b540aSrobert 1313*404b540aSrobert3.4 Stringification 1314*404b540aSrobert=================== 1315*404b540aSrobert 1316*404b540aSrobertSometimes you may want to convert a macro argument into a string 1317*404b540aSrobertconstant. Parameters are not replaced inside string constants, but you 1318*404b540aSrobertcan use the `#' preprocessing operator instead. When a macro parameter 1319*404b540aSrobertis used with a leading `#', the preprocessor replaces it with the 1320*404b540aSrobertliteral text of the actual argument, converted to a string constant. 1321*404b540aSrobertUnlike normal parameter replacement, the argument is not macro-expanded 1322*404b540aSrobertfirst. This is called "stringification". 1323*404b540aSrobert 1324*404b540aSrobert There is no way to combine an argument with surrounding text and 1325*404b540aSrobertstringify it all together. Instead, you can write a series of adjacent 1326*404b540aSrobertstring constants and stringified arguments. The preprocessor will 1327*404b540aSrobertreplace the stringified arguments with string constants. The C 1328*404b540aSrobertcompiler will then combine all the adjacent string constants into one 1329*404b540aSrobertlong string. 1330*404b540aSrobert 1331*404b540aSrobert Here is an example of a macro definition that uses stringification: 1332*404b540aSrobert 1333*404b540aSrobert #define WARN_IF(EXP) \ 1334*404b540aSrobert do { if (EXP) \ 1335*404b540aSrobert fprintf (stderr, "Warning: " #EXP "\n"); } \ 1336*404b540aSrobert while (0) 1337*404b540aSrobert WARN_IF (x == 0); 1338*404b540aSrobert ==> do { if (x == 0) 1339*404b540aSrobert fprintf (stderr, "Warning: " "x == 0" "\n"); } while (0); 1340*404b540aSrobert 1341*404b540aSrobertThe argument for `EXP' is substituted once, as-is, into the `if' 1342*404b540aSrobertstatement, and once, stringified, into the argument to `fprintf'. If 1343*404b540aSrobert`x' were a macro, it would be expanded in the `if' statement, but not 1344*404b540aSrobertin the string. 1345*404b540aSrobert 1346*404b540aSrobert The `do' and `while (0)' are a kludge to make it possible to write 1347*404b540aSrobert`WARN_IF (ARG);', which the resemblance of `WARN_IF' to a function 1348*404b540aSrobertwould make C programmers want to do; see *Note Swallowing the 1349*404b540aSrobertSemicolon::. 1350*404b540aSrobert 1351*404b540aSrobert Stringification in C involves more than putting double-quote 1352*404b540aSrobertcharacters around the fragment. The preprocessor backslash-escapes the 1353*404b540aSrobertquotes surrounding embedded string constants, and all backslashes 1354*404b540aSrobertwithin string and character constants, in order to get a valid C string 1355*404b540aSrobertconstant with the proper contents. Thus, stringifying `p = "foo\n";' 1356*404b540aSrobertresults in "p = \"foo\\n\";". However, backslashes that are not inside 1357*404b540aSrobertstring or character constants are not duplicated: `\n' by itself 1358*404b540aSrobertstringifies to "\n". 1359*404b540aSrobert 1360*404b540aSrobert All leading and trailing whitespace in text being stringified is 1361*404b540aSrobertignored. Any sequence of whitespace in the middle of the text is 1362*404b540aSrobertconverted to a single space in the stringified result. Comments are 1363*404b540aSrobertreplaced by whitespace long before stringification happens, so they 1364*404b540aSrobertnever appear in stringified text. 1365*404b540aSrobert 1366*404b540aSrobert There is no way to convert a macro argument into a character 1367*404b540aSrobertconstant. 1368*404b540aSrobert 1369*404b540aSrobert If you want to stringify the result of expansion of a macro argument, 1370*404b540aSrobertyou have to use two levels of macros. 1371*404b540aSrobert 1372*404b540aSrobert #define xstr(s) str(s) 1373*404b540aSrobert #define str(s) #s 1374*404b540aSrobert #define foo 4 1375*404b540aSrobert str (foo) 1376*404b540aSrobert ==> "foo" 1377*404b540aSrobert xstr (foo) 1378*404b540aSrobert ==> xstr (4) 1379*404b540aSrobert ==> str (4) 1380*404b540aSrobert ==> "4" 1381*404b540aSrobert 1382*404b540aSrobert `s' is stringified when it is used in `str', so it is not 1383*404b540aSrobertmacro-expanded first. But `s' is an ordinary argument to `xstr', so it 1384*404b540aSrobertis completely macro-expanded before `xstr' itself is expanded (*note 1385*404b540aSrobertArgument Prescan::). Therefore, by the time `str' gets to its 1386*404b540aSrobertargument, it has already been macro-expanded. 1387*404b540aSrobert 1388*404b540aSrobert 1389*404b540aSrobertFile: cpp.info, Node: Concatenation, Next: Variadic Macros, Prev: Stringification, Up: Macros 1390*404b540aSrobert 1391*404b540aSrobert3.5 Concatenation 1392*404b540aSrobert================= 1393*404b540aSrobert 1394*404b540aSrobertIt is often useful to merge two tokens into one while expanding macros. 1395*404b540aSrobertThis is called "token pasting" or "token concatenation". The `##' 1396*404b540aSrobertpreprocessing operator performs token pasting. When a macro is 1397*404b540aSrobertexpanded, the two tokens on either side of each `##' operator are 1398*404b540aSrobertcombined into a single token, which then replaces the `##' and the two 1399*404b540aSrobertoriginal tokens in the macro expansion. Usually both will be 1400*404b540aSrobertidentifiers, or one will be an identifier and the other a preprocessing 1401*404b540aSrobertnumber. When pasted, they make a longer identifier. This isn't the 1402*404b540aSrobertonly valid case. It is also possible to concatenate two numbers (or a 1403*404b540aSrobertnumber and a name, such as `1.5' and `e3') into a number. Also, 1404*404b540aSrobertmulti-character operators such as `+=' can be formed by token pasting. 1405*404b540aSrobert 1406*404b540aSrobert However, two tokens that don't together form a valid token cannot be 1407*404b540aSrobertpasted together. For example, you cannot concatenate `x' with `+' in 1408*404b540aSroberteither order. If you try, the preprocessor issues a warning and emits 1409*404b540aSrobertthe two tokens. Whether it puts white space between the tokens is 1410*404b540aSrobertundefined. It is common to find unnecessary uses of `##' in complex 1411*404b540aSrobertmacros. If you get this warning, it is likely that you can simply 1412*404b540aSrobertremove the `##'. 1413*404b540aSrobert 1414*404b540aSrobert Both the tokens combined by `##' could come from the macro body, but 1415*404b540aSrobertyou could just as well write them as one token in the first place. 1416*404b540aSrobertToken pasting is most useful when one or both of the tokens comes from a 1417*404b540aSrobertmacro argument. If either of the tokens next to an `##' is a parameter 1418*404b540aSrobertname, it is replaced by its actual argument before `##' executes. As 1419*404b540aSrobertwith stringification, the actual argument is not macro-expanded first. 1420*404b540aSrobertIf the argument is empty, that `##' has no effect. 1421*404b540aSrobert 1422*404b540aSrobert Keep in mind that the C preprocessor converts comments to whitespace 1423*404b540aSrobertbefore macros are even considered. Therefore, you cannot create a 1424*404b540aSrobertcomment by concatenating `/' and `*'. You can put as much whitespace 1425*404b540aSrobertbetween `##' and its operands as you like, including comments, and you 1426*404b540aSrobertcan put comments in arguments that will be concatenated. However, it 1427*404b540aSrobertis an error if `##' appears at either end of a macro body. 1428*404b540aSrobert 1429*404b540aSrobert Consider a C program that interprets named commands. There probably 1430*404b540aSrobertneeds to be a table of commands, perhaps an array of structures declared 1431*404b540aSrobertas follows: 1432*404b540aSrobert 1433*404b540aSrobert struct command 1434*404b540aSrobert { 1435*404b540aSrobert char *name; 1436*404b540aSrobert void (*function) (void); 1437*404b540aSrobert }; 1438*404b540aSrobert 1439*404b540aSrobert struct command commands[] = 1440*404b540aSrobert { 1441*404b540aSrobert { "quit", quit_command }, 1442*404b540aSrobert { "help", help_command }, 1443*404b540aSrobert ... 1444*404b540aSrobert }; 1445*404b540aSrobert 1446*404b540aSrobert It would be cleaner not to have to give each command name twice, 1447*404b540aSrobertonce in the string constant and once in the function name. A macro 1448*404b540aSrobertwhich takes the name of a command as an argument can make this 1449*404b540aSrobertunnecessary. The string constant can be created with stringification, 1450*404b540aSrobertand the function name by concatenating the argument with `_command'. 1451*404b540aSrobertHere is how it is done: 1452*404b540aSrobert 1453*404b540aSrobert #define COMMAND(NAME) { #NAME, NAME ## _command } 1454*404b540aSrobert 1455*404b540aSrobert struct command commands[] = 1456*404b540aSrobert { 1457*404b540aSrobert COMMAND (quit), 1458*404b540aSrobert COMMAND (help), 1459*404b540aSrobert ... 1460*404b540aSrobert }; 1461*404b540aSrobert 1462*404b540aSrobert 1463*404b540aSrobertFile: cpp.info, Node: Variadic Macros, Next: Predefined Macros, Prev: Concatenation, Up: Macros 1464*404b540aSrobert 1465*404b540aSrobert3.6 Variadic Macros 1466*404b540aSrobert=================== 1467*404b540aSrobert 1468*404b540aSrobertA macro can be declared to accept a variable number of arguments much as 1469*404b540aSroberta function can. The syntax for defining the macro is similar to that of 1470*404b540aSroberta function. Here is an example: 1471*404b540aSrobert 1472*404b540aSrobert #define eprintf(...) fprintf (stderr, __VA_ARGS__) 1473*404b540aSrobert 1474*404b540aSrobert This kind of macro is called "variadic". When the macro is invoked, 1475*404b540aSrobertall the tokens in its argument list after the last named argument (this 1476*404b540aSrobertmacro has none), including any commas, become the "variable argument". 1477*404b540aSrobertThis sequence of tokens replaces the identifier `__VA_ARGS__' in the 1478*404b540aSrobertmacro body wherever it appears. Thus, we have this expansion: 1479*404b540aSrobert 1480*404b540aSrobert eprintf ("%s:%d: ", input_file, lineno) 1481*404b540aSrobert ==> fprintf (stderr, "%s:%d: ", input_file, lineno) 1482*404b540aSrobert 1483*404b540aSrobert The variable argument is completely macro-expanded before it is 1484*404b540aSrobertinserted into the macro expansion, just like an ordinary argument. You 1485*404b540aSrobertmay use the `#' and `##' operators to stringify the variable argument 1486*404b540aSrobertor to paste its leading or trailing token with another token. (But see 1487*404b540aSrobertbelow for an important special case for `##'.) 1488*404b540aSrobert 1489*404b540aSrobert If your macro is complicated, you may want a more descriptive name 1490*404b540aSrobertfor the variable argument than `__VA_ARGS__'. CPP permits this, as an 1491*404b540aSrobertextension. You may write an argument name immediately before the 1492*404b540aSrobert`...'; that name is used for the variable argument. The `eprintf' 1493*404b540aSrobertmacro above could be written 1494*404b540aSrobert 1495*404b540aSrobert #define eprintf(args...) fprintf (stderr, args) 1496*404b540aSrobert 1497*404b540aSrobertusing this extension. You cannot use `__VA_ARGS__' and this extension 1498*404b540aSrobertin the same macro. 1499*404b540aSrobert 1500*404b540aSrobert You can have named arguments as well as variable arguments in a 1501*404b540aSrobertvariadic macro. We could define `eprintf' like this, instead: 1502*404b540aSrobert 1503*404b540aSrobert #define eprintf(format, ...) fprintf (stderr, format, __VA_ARGS__) 1504*404b540aSrobert 1505*404b540aSrobertThis formulation looks more descriptive, but unfortunately it is less 1506*404b540aSrobertflexible: you must now supply at least one argument after the format 1507*404b540aSrobertstring. In standard C, you cannot omit the comma separating the named 1508*404b540aSrobertargument from the variable arguments. Furthermore, if you leave the 1509*404b540aSrobertvariable argument empty, you will get a syntax error, because there 1510*404b540aSrobertwill be an extra comma after the format string. 1511*404b540aSrobert 1512*404b540aSrobert eprintf("success!\n", ); 1513*404b540aSrobert ==> fprintf(stderr, "success!\n", ); 1514*404b540aSrobert 1515*404b540aSrobert GNU CPP has a pair of extensions which deal with this problem. 1516*404b540aSrobertFirst, you are allowed to leave the variable argument out entirely: 1517*404b540aSrobert 1518*404b540aSrobert eprintf ("success!\n") 1519*404b540aSrobert ==> fprintf(stderr, "success!\n", ); 1520*404b540aSrobert 1521*404b540aSrobertSecond, the `##' token paste operator has a special meaning when placed 1522*404b540aSrobertbetween a comma and a variable argument. If you write 1523*404b540aSrobert 1524*404b540aSrobert #define eprintf(format, ...) fprintf (stderr, format, ##__VA_ARGS__) 1525*404b540aSrobert 1526*404b540aSrobertand the variable argument is left out when the `eprintf' macro is used, 1527*404b540aSrobertthen the comma before the `##' will be deleted. This does _not_ happen 1528*404b540aSrobertif you pass an empty argument, nor does it happen if the token 1529*404b540aSrobertpreceding `##' is anything other than a comma. 1530*404b540aSrobert 1531*404b540aSrobert eprintf ("success!\n") 1532*404b540aSrobert ==> fprintf(stderr, "success!\n"); 1533*404b540aSrobert 1534*404b540aSrobertThe above explanation is ambiguous about the case where the only macro 1535*404b540aSrobertparameter is a variable arguments parameter, as it is meaningless to 1536*404b540aSroberttry to distinguish whether no argument at all is an empty argument or a 1537*404b540aSrobertmissing argument. In this case the C99 standard is clear that the 1538*404b540aSrobertcomma must remain, however the existing GCC extension used to swallow 1539*404b540aSrobertthe comma. So CPP retains the comma when conforming to a specific C 1540*404b540aSrobertstandard, and drops it otherwise. 1541*404b540aSrobert 1542*404b540aSrobert C99 mandates that the only place the identifier `__VA_ARGS__' can 1543*404b540aSrobertappear is in the replacement list of a variadic macro. It may not be 1544*404b540aSrobertused as a macro name, macro argument name, or within a different type 1545*404b540aSrobertof macro. It may also be forbidden in open text; the standard is 1546*404b540aSrobertambiguous. We recommend you avoid using it except for its defined 1547*404b540aSrobertpurpose. 1548*404b540aSrobert 1549*404b540aSrobert Variadic macros are a new feature in C99. GNU CPP has supported them 1550*404b540aSrobertfor a long time, but only with a named variable argument (`args...', 1551*404b540aSrobertnot `...' and `__VA_ARGS__'). If you are concerned with portability to 1552*404b540aSrobertprevious versions of GCC, you should use only named variable arguments. 1553*404b540aSrobertOn the other hand, if you are concerned with portability to other 1554*404b540aSrobertconforming implementations of C99, you should use only `__VA_ARGS__'. 1555*404b540aSrobert 1556*404b540aSrobert Previous versions of CPP implemented the comma-deletion extension 1557*404b540aSrobertmuch more generally. We have restricted it in this release to minimize 1558*404b540aSrobertthe differences from C99. To get the same effect with both this and 1559*404b540aSrobertprevious versions of GCC, the token preceding the special `##' must be 1560*404b540aSroberta comma, and there must be white space between that comma and whatever 1561*404b540aSrobertcomes immediately before it: 1562*404b540aSrobert 1563*404b540aSrobert #define eprintf(format, args...) fprintf (stderr, format , ##args) 1564*404b540aSrobert 1565*404b540aSrobert*Note Differences from previous versions::, for the gory details. 1566*404b540aSrobert 1567*404b540aSrobert 1568*404b540aSrobertFile: cpp.info, Node: Predefined Macros, Next: Undefining and Redefining Macros, Prev: Variadic Macros, Up: Macros 1569*404b540aSrobert 1570*404b540aSrobert3.7 Predefined Macros 1571*404b540aSrobert===================== 1572*404b540aSrobert 1573*404b540aSrobertSeveral object-like macros are predefined; you use them without 1574*404b540aSrobertsupplying their definitions. They fall into three classes: standard, 1575*404b540aSrobertcommon, and system-specific. 1576*404b540aSrobert 1577*404b540aSrobert In C++, there is a fourth category, the named operators. They act 1578*404b540aSrobertlike predefined macros, but you cannot undefine them. 1579*404b540aSrobert 1580*404b540aSrobert* Menu: 1581*404b540aSrobert 1582*404b540aSrobert* Standard Predefined Macros:: 1583*404b540aSrobert* Common Predefined Macros:: 1584*404b540aSrobert* System-specific Predefined Macros:: 1585*404b540aSrobert* C++ Named Operators:: 1586*404b540aSrobert 1587*404b540aSrobert 1588*404b540aSrobertFile: cpp.info, Node: Standard Predefined Macros, Next: Common Predefined Macros, Up: Predefined Macros 1589*404b540aSrobert 1590*404b540aSrobert3.7.1 Standard Predefined Macros 1591*404b540aSrobert-------------------------------- 1592*404b540aSrobert 1593*404b540aSrobertThe standard predefined macros are specified by the relevant language 1594*404b540aSrobertstandards, so they are available with all compilers that implement 1595*404b540aSrobertthose standards. Older compilers may not provide all of them. Their 1596*404b540aSrobertnames all start with double underscores. 1597*404b540aSrobert 1598*404b540aSrobert`__FILE__' 1599*404b540aSrobert This macro expands to the name of the current input file, in the 1600*404b540aSrobert form of a C string constant. This is the path by which the 1601*404b540aSrobert preprocessor opened the file, not the short name specified in 1602*404b540aSrobert `#include' or as the input file name argument. For example, 1603*404b540aSrobert `"/usr/local/include/myheader.h"' is a possible expansion of this 1604*404b540aSrobert macro. 1605*404b540aSrobert 1606*404b540aSrobert`__LINE__' 1607*404b540aSrobert This macro expands to the current input line number, in the form 1608*404b540aSrobert of a decimal integer constant. While we call it a predefined 1609*404b540aSrobert macro, it's a pretty strange macro, since its "definition" changes 1610*404b540aSrobert with each new line of source code. 1611*404b540aSrobert 1612*404b540aSrobert `__FILE__' and `__LINE__' are useful in generating an error message 1613*404b540aSrobertto report an inconsistency detected by the program; the message can 1614*404b540aSrobertstate the source line at which the inconsistency was detected. For 1615*404b540aSrobertexample, 1616*404b540aSrobert 1617*404b540aSrobert fprintf (stderr, "Internal error: " 1618*404b540aSrobert "negative string length " 1619*404b540aSrobert "%d at %s, line %d.", 1620*404b540aSrobert length, __FILE__, __LINE__); 1621*404b540aSrobert 1622*404b540aSrobert An `#include' directive changes the expansions of `__FILE__' and 1623*404b540aSrobert`__LINE__' to correspond to the included file. At the end of that 1624*404b540aSrobertfile, when processing resumes on the input file that contained the 1625*404b540aSrobert`#include' directive, the expansions of `__FILE__' and `__LINE__' 1626*404b540aSrobertrevert to the values they had before the `#include' (but `__LINE__' is 1627*404b540aSrobertthen incremented by one as processing moves to the line after the 1628*404b540aSrobert`#include'). 1629*404b540aSrobert 1630*404b540aSrobert A `#line' directive changes `__LINE__', and may change `__FILE__' as 1631*404b540aSrobertwell. *Note Line Control::. 1632*404b540aSrobert 1633*404b540aSrobert C99 introduces `__func__', and GCC has provided `__FUNCTION__' for a 1634*404b540aSrobertlong time. Both of these are strings containing the name of the 1635*404b540aSrobertcurrent function (there are slight semantic differences; see the GCC 1636*404b540aSrobertmanual). Neither of them is a macro; the preprocessor does not know the 1637*404b540aSrobertname of the current function. They tend to be useful in conjunction 1638*404b540aSrobertwith `__FILE__' and `__LINE__', though. 1639*404b540aSrobert 1640*404b540aSrobert`__DATE__' 1641*404b540aSrobert This macro expands to a string constant that describes the date on 1642*404b540aSrobert which the preprocessor is being run. The string constant contains 1643*404b540aSrobert eleven characters and looks like `"Feb 12 1996"'. If the day of 1644*404b540aSrobert the month is less than 10, it is padded with a space on the left. 1645*404b540aSrobert 1646*404b540aSrobert If GCC cannot determine the current date, it will emit a warning 1647*404b540aSrobert message (once per compilation) and `__DATE__' will expand to 1648*404b540aSrobert `"??? ?? ????"'. 1649*404b540aSrobert 1650*404b540aSrobert`__TIME__' 1651*404b540aSrobert This macro expands to a string constant that describes the time at 1652*404b540aSrobert which the preprocessor is being run. The string constant contains 1653*404b540aSrobert eight characters and looks like `"23:59:01"'. 1654*404b540aSrobert 1655*404b540aSrobert If GCC cannot determine the current time, it will emit a warning 1656*404b540aSrobert message (once per compilation) and `__TIME__' will expand to 1657*404b540aSrobert `"??:??:??"'. 1658*404b540aSrobert 1659*404b540aSrobert`__STDC__' 1660*404b540aSrobert In normal operation, this macro expands to the constant 1, to 1661*404b540aSrobert signify that this compiler conforms to ISO Standard C. If GNU CPP 1662*404b540aSrobert is used with a compiler other than GCC, this is not necessarily 1663*404b540aSrobert true; however, the preprocessor always conforms to the standard 1664*404b540aSrobert unless the `-traditional-cpp' option is used. 1665*404b540aSrobert 1666*404b540aSrobert This macro is not defined if the `-traditional-cpp' option is used. 1667*404b540aSrobert 1668*404b540aSrobert On some hosts, the system compiler uses a different convention, 1669*404b540aSrobert where `__STDC__' is normally 0, but is 1 if the user specifies 1670*404b540aSrobert strict conformance to the C Standard. CPP follows the host 1671*404b540aSrobert convention when processing system header files, but when 1672*404b540aSrobert processing user files `__STDC__' is always 1. This has been 1673*404b540aSrobert reported to cause problems; for instance, some versions of Solaris 1674*404b540aSrobert provide X Windows headers that expect `__STDC__' to be either 1675*404b540aSrobert undefined or 1. *Note Invocation::. 1676*404b540aSrobert 1677*404b540aSrobert`__STDC_VERSION__' 1678*404b540aSrobert This macro expands to the C Standard's version number, a long 1679*404b540aSrobert integer constant of the form `YYYYMML' where YYYY and MM are the 1680*404b540aSrobert year and month of the Standard version. This signifies which 1681*404b540aSrobert version of the C Standard the compiler conforms to. Like 1682*404b540aSrobert `__STDC__', this is not necessarily accurate for the entire 1683*404b540aSrobert implementation, unless GNU CPP is being used with GCC. 1684*404b540aSrobert 1685*404b540aSrobert The value `199409L' signifies the 1989 C standard as amended in 1686*404b540aSrobert 1994, which is the current default; the value `199901L' signifies 1687*404b540aSrobert the 1999 revision of the C standard. Support for the 1999 1688*404b540aSrobert revision is not yet complete. 1689*404b540aSrobert 1690*404b540aSrobert This macro is not defined if the `-traditional-cpp' option is 1691*404b540aSrobert used, nor when compiling C++ or Objective-C. 1692*404b540aSrobert 1693*404b540aSrobert`__STDC_HOSTED__' 1694*404b540aSrobert This macro is defined, with value 1, if the compiler's target is a 1695*404b540aSrobert "hosted environment". A hosted environment has the complete 1696*404b540aSrobert facilities of the standard C library available. 1697*404b540aSrobert 1698*404b540aSrobert`__cplusplus' 1699*404b540aSrobert This macro is defined when the C++ compiler is in use. You can use 1700*404b540aSrobert `__cplusplus' to test whether a header is compiled by a C compiler 1701*404b540aSrobert or a C++ compiler. This macro is similar to `__STDC_VERSION__', in 1702*404b540aSrobert that it expands to a version number. A fully conforming 1703*404b540aSrobert implementation of the 1998 C++ standard will define this macro to 1704*404b540aSrobert `199711L'. The GNU C++ compiler is not yet fully conforming, so 1705*404b540aSrobert it uses `1' instead. It is hoped to complete the implementation 1706*404b540aSrobert of standard C++ in the near future. 1707*404b540aSrobert 1708*404b540aSrobert`__OBJC__' 1709*404b540aSrobert This macro is defined, with value 1, when the Objective-C compiler 1710*404b540aSrobert is in use. You can use `__OBJC__' to test whether a header is 1711*404b540aSrobert compiled by a C compiler or a Objective-C compiler. 1712*404b540aSrobert 1713*404b540aSrobert`__ASSEMBLER__' 1714*404b540aSrobert This macro is defined with value 1 when preprocessing assembly 1715*404b540aSrobert language. 1716*404b540aSrobert 1717*404b540aSrobert 1718*404b540aSrobert 1719*404b540aSrobertFile: cpp.info, Node: Common Predefined Macros, Next: System-specific Predefined Macros, Prev: Standard Predefined Macros, Up: Predefined Macros 1720*404b540aSrobert 1721*404b540aSrobert3.7.2 Common Predefined Macros 1722*404b540aSrobert------------------------------ 1723*404b540aSrobert 1724*404b540aSrobertThe common predefined macros are GNU C extensions. They are available 1725*404b540aSrobertwith the same meanings regardless of the machine or operating system on 1726*404b540aSrobertwhich you are using GNU C. Their names all start with double 1727*404b540aSrobertunderscores. 1728*404b540aSrobert 1729*404b540aSrobert`__GNUC__' 1730*404b540aSrobert`__GNUC_MINOR__' 1731*404b540aSrobert`__GNUC_PATCHLEVEL__' 1732*404b540aSrobert These macros are defined by all GNU compilers that use the C 1733*404b540aSrobert preprocessor: C, C++, and Objective-C. Their values are the major 1734*404b540aSrobert version, minor version, and patch level of the compiler, as integer 1735*404b540aSrobert constants. For example, GCC 3.2.1 will define `__GNUC__' to 3, 1736*404b540aSrobert `__GNUC_MINOR__' to 2, and `__GNUC_PATCHLEVEL__' to 1. These 1737*404b540aSrobert macros are also defined if you invoke the preprocessor directly. 1738*404b540aSrobert 1739*404b540aSrobert `__GNUC_PATCHLEVEL__' is new to GCC 3.0; it is also present in the 1740*404b540aSrobert widely-used development snapshots leading up to 3.0 (which identify 1741*404b540aSrobert themselves as GCC 2.96 or 2.97, depending on which snapshot you 1742*404b540aSrobert have). 1743*404b540aSrobert 1744*404b540aSrobert If all you need to know is whether or not your program is being 1745*404b540aSrobert compiled by GCC, or a non-GCC compiler that claims to accept the 1746*404b540aSrobert GNU C dialects, you can simply test `__GNUC__'. If you need to 1747*404b540aSrobert write code which depends on a specific version, you must be more 1748*404b540aSrobert careful. Each time the minor version is increased, the patch 1749*404b540aSrobert level is reset to zero; each time the major version is increased 1750*404b540aSrobert (which happens rarely), the minor version and patch level are 1751*404b540aSrobert reset. If you wish to use the predefined macros directly in the 1752*404b540aSrobert conditional, you will need to write it like this: 1753*404b540aSrobert 1754*404b540aSrobert /* Test for GCC > 3.2.0 */ 1755*404b540aSrobert #if __GNUC__ > 3 || \ 1756*404b540aSrobert (__GNUC__ == 3 && (__GNUC_MINOR__ > 2 || \ 1757*404b540aSrobert (__GNUC_MINOR__ == 2 && \ 1758*404b540aSrobert __GNUC_PATCHLEVEL__ > 0)) 1759*404b540aSrobert 1760*404b540aSrobert Another approach is to use the predefined macros to calculate a 1761*404b540aSrobert single number, then compare that against a threshold: 1762*404b540aSrobert 1763*404b540aSrobert #define GCC_VERSION (__GNUC__ * 10000 \ 1764*404b540aSrobert + __GNUC_MINOR__ * 100 \ 1765*404b540aSrobert + __GNUC_PATCHLEVEL__) 1766*404b540aSrobert ... 1767*404b540aSrobert /* Test for GCC > 3.2.0 */ 1768*404b540aSrobert #if GCC_VERSION > 30200 1769*404b540aSrobert 1770*404b540aSrobert Many people find this form easier to understand. 1771*404b540aSrobert 1772*404b540aSrobert`__GNUG__' 1773*404b540aSrobert The GNU C++ compiler defines this. Testing it is equivalent to 1774*404b540aSrobert testing `(__GNUC__ && __cplusplus)'. 1775*404b540aSrobert 1776*404b540aSrobert`__STRICT_ANSI__' 1777*404b540aSrobert GCC defines this macro if and only if the `-ansi' switch, or a 1778*404b540aSrobert `-std' switch specifying strict conformance to some version of ISO 1779*404b540aSrobert C, was specified when GCC was invoked. It is defined to `1'. 1780*404b540aSrobert This macro exists primarily to direct GNU libc's header files to 1781*404b540aSrobert restrict their definitions to the minimal set found in the 1989 C 1782*404b540aSrobert standard. 1783*404b540aSrobert 1784*404b540aSrobert`__BASE_FILE__' 1785*404b540aSrobert This macro expands to the name of the main input file, in the form 1786*404b540aSrobert of a C string constant. This is the source file that was specified 1787*404b540aSrobert on the command line of the preprocessor or C compiler. 1788*404b540aSrobert 1789*404b540aSrobert`__INCLUDE_LEVEL__' 1790*404b540aSrobert This macro expands to a decimal integer constant that represents 1791*404b540aSrobert the depth of nesting in include files. The value of this macro is 1792*404b540aSrobert incremented on every `#include' directive and decremented at the 1793*404b540aSrobert end of every included file. It starts out at 0, it's value within 1794*404b540aSrobert the base file specified on the command line. 1795*404b540aSrobert 1796*404b540aSrobert`__ELF__' 1797*404b540aSrobert This macro is defined if the target uses the ELF object format. 1798*404b540aSrobert 1799*404b540aSrobert`__VERSION__' 1800*404b540aSrobert This macro expands to a string constant which describes the 1801*404b540aSrobert version of the compiler in use. You should not rely on its 1802*404b540aSrobert contents having any particular form, but it can be counted on to 1803*404b540aSrobert contain at least the release number. 1804*404b540aSrobert 1805*404b540aSrobert`__OPTIMIZE__' 1806*404b540aSrobert`__OPTIMIZE_SIZE__' 1807*404b540aSrobert`__NO_INLINE__' 1808*404b540aSrobert These macros describe the compilation mode. `__OPTIMIZE__' is 1809*404b540aSrobert defined in all optimizing compilations. `__OPTIMIZE_SIZE__' is 1810*404b540aSrobert defined if the compiler is optimizing for size, not speed. 1811*404b540aSrobert `__NO_INLINE__' is defined if no functions will be inlined into 1812*404b540aSrobert their callers (when not optimizing, or when inlining has been 1813*404b540aSrobert specifically disabled by `-fno-inline'). 1814*404b540aSrobert 1815*404b540aSrobert These macros cause certain GNU header files to provide optimized 1816*404b540aSrobert definitions, using macros or inline functions, of system library 1817*404b540aSrobert functions. You should not use these macros in any way unless you 1818*404b540aSrobert make sure that programs will execute with the same effect whether 1819*404b540aSrobert or not they are defined. If they are defined, their value is 1. 1820*404b540aSrobert 1821*404b540aSrobert`__GNUC_GNU_INLINE__' 1822*404b540aSrobert GCC defines this macro if functions declared `inline' will be 1823*404b540aSrobert handled in GCC's traditional gnu89 mode. In this mode an `extern 1824*404b540aSrobert inline' function will never be compiled as a standalone function, 1825*404b540aSrobert and an `inline' function which is neither `extern' nor `static' 1826*404b540aSrobert will always be compiled as a standalone function. 1827*404b540aSrobert 1828*404b540aSrobert`__GNUC_STDC_INLINE__' 1829*404b540aSrobert GCC defines this macro if functions declared `inline' will be 1830*404b540aSrobert handled according to the ISO C99 standard. In this mode an 1831*404b540aSrobert `extern inline' function will always be compiled as a standalone 1832*404b540aSrobert externally visible function, and an `inline' function which is 1833*404b540aSrobert neither `extern' nor `static' will never be compiled as a 1834*404b540aSrobert standalone function. 1835*404b540aSrobert 1836*404b540aSrobert If this macro is defined, GCC supports the `gnu_inline' function 1837*404b540aSrobert attribute as a way to always get the gnu89 behaviour. Support for 1838*404b540aSrobert this and `__GNUC_GNU_INLINE__' was added in GCC 4.1.3. If neither 1839*404b540aSrobert macro is defined, an older version of GCC is being used: `inline' 1840*404b540aSrobert functions will be compiled in gnu89 mode, and the `gnu_inline' 1841*404b540aSrobert function attribute will not be recognized. 1842*404b540aSrobert 1843*404b540aSrobert`__CHAR_UNSIGNED__' 1844*404b540aSrobert GCC defines this macro if and only if the data type `char' is 1845*404b540aSrobert unsigned on the target machine. It exists to cause the standard 1846*404b540aSrobert header file `limits.h' to work correctly. You should not use this 1847*404b540aSrobert macro yourself; instead, refer to the standard macros defined in 1848*404b540aSrobert `limits.h'. 1849*404b540aSrobert 1850*404b540aSrobert`__WCHAR_UNSIGNED__' 1851*404b540aSrobert Like `__CHAR_UNSIGNED__', this macro is defined if and only if the 1852*404b540aSrobert data type `wchar_t' is unsigned and the front-end is in C++ mode. 1853*404b540aSrobert 1854*404b540aSrobert`__REGISTER_PREFIX__' 1855*404b540aSrobert This macro expands to a single token (not a string constant) which 1856*404b540aSrobert is the prefix applied to CPU register names in assembly language 1857*404b540aSrobert for this target. You can use it to write assembly that is usable 1858*404b540aSrobert in multiple environments. For example, in the `m68k-aout' 1859*404b540aSrobert environment it expands to nothing, but in the `m68k-coff' 1860*404b540aSrobert environment it expands to a single `%'. 1861*404b540aSrobert 1862*404b540aSrobert`__USER_LABEL_PREFIX__' 1863*404b540aSrobert This macro expands to a single token which is the prefix applied to 1864*404b540aSrobert user labels (symbols visible to C code) in assembly. For example, 1865*404b540aSrobert in the `m68k-aout' environment it expands to an `_', but in the 1866*404b540aSrobert `m68k-coff' environment it expands to nothing. 1867*404b540aSrobert 1868*404b540aSrobert This macro will have the correct definition even if 1869*404b540aSrobert `-f(no-)underscores' is in use, but it will not be correct if 1870*404b540aSrobert target-specific options that adjust this prefix are used (e.g. the 1871*404b540aSrobert OSF/rose `-mno-underscores' option). 1872*404b540aSrobert 1873*404b540aSrobert`__SIZE_TYPE__' 1874*404b540aSrobert`__PTRDIFF_TYPE__' 1875*404b540aSrobert`__WCHAR_TYPE__' 1876*404b540aSrobert`__WINT_TYPE__' 1877*404b540aSrobert`__INTMAX_TYPE__' 1878*404b540aSrobert`__UINTMAX_TYPE__' 1879*404b540aSrobert These macros are defined to the correct underlying types for the 1880*404b540aSrobert `size_t', `ptrdiff_t', `wchar_t', `wint_t', `intmax_t', and 1881*404b540aSrobert `uintmax_t' typedefs, respectively. They exist to make the 1882*404b540aSrobert standard header files `stddef.h' and `wchar.h' work correctly. 1883*404b540aSrobert You should not use these macros directly; instead, include the 1884*404b540aSrobert appropriate headers and use the typedefs. 1885*404b540aSrobert 1886*404b540aSrobert`__CHAR_BIT__' 1887*404b540aSrobert Defined to the number of bits used in the representation of the 1888*404b540aSrobert `char' data type. It exists to make the standard header given 1889*404b540aSrobert numerical limits work correctly. You should not use this macro 1890*404b540aSrobert directly; instead, include the appropriate headers. 1891*404b540aSrobert 1892*404b540aSrobert`__SCHAR_MAX__' 1893*404b540aSrobert`__WCHAR_MAX__' 1894*404b540aSrobert`__SHRT_MAX__' 1895*404b540aSrobert`__INT_MAX__' 1896*404b540aSrobert`__LONG_MAX__' 1897*404b540aSrobert`__LONG_LONG_MAX__' 1898*404b540aSrobert`__INTMAX_MAX__' 1899*404b540aSrobert Defined to the maximum value of the `signed char', `wchar_t', 1900*404b540aSrobert `signed short', `signed int', `signed long', `signed long long', 1901*404b540aSrobert and `intmax_t' types respectively. They exist to make the 1902*404b540aSrobert standard header given numerical limits work correctly. You should 1903*404b540aSrobert not use these macros directly; instead, include the appropriate 1904*404b540aSrobert headers. 1905*404b540aSrobert 1906*404b540aSrobert`__DEPRECATED' 1907*404b540aSrobert This macro is defined, with value 1, when compiling a C++ source 1908*404b540aSrobert file with warnings about deprecated constructs enabled. These 1909*404b540aSrobert warnings are enabled by default, but can be disabled with 1910*404b540aSrobert `-Wno-deprecated'. 1911*404b540aSrobert 1912*404b540aSrobert`__EXCEPTIONS' 1913*404b540aSrobert This macro is defined, with value 1, when compiling a C++ source 1914*404b540aSrobert file with exceptions enabled. If `-fno-exceptions' was used when 1915*404b540aSrobert compiling the file, then this macro will not be defined. 1916*404b540aSrobert 1917*404b540aSrobert`__USING_SJLJ_EXCEPTIONS__' 1918*404b540aSrobert This macro is defined, with value 1, if the compiler uses the old 1919*404b540aSrobert mechanism based on `setjmp' and `longjmp' for exception handling. 1920*404b540aSrobert 1921*404b540aSrobert`__GXX_WEAK__' 1922*404b540aSrobert This macro is defined when compiling a C++ source file. It has the 1923*404b540aSrobert value 1 if the compiler will use weak symbols, COMDAT sections, or 1924*404b540aSrobert other similar techniques to collapse symbols with "vague linkage" 1925*404b540aSrobert that are defined in multiple translation units. If the compiler 1926*404b540aSrobert will not collapse such symbols, this macro is defined with value 1927*404b540aSrobert 0. In general, user code should not need to make use of this 1928*404b540aSrobert macro; the purpose of this macro is to ease implementation of the 1929*404b540aSrobert C++ runtime library provided with G++. 1930*404b540aSrobert 1931*404b540aSrobert`__NEXT_RUNTIME__' 1932*404b540aSrobert This macro is defined, with value 1, if (and only if) the NeXT 1933*404b540aSrobert runtime (as in `-fnext-runtime') is in use for Objective-C. If 1934*404b540aSrobert the GNU runtime is used, this macro is not defined, so that you 1935*404b540aSrobert can use this macro to determine which runtime (NeXT or GNU) is 1936*404b540aSrobert being used. 1937*404b540aSrobert 1938*404b540aSrobert`__LP64__' 1939*404b540aSrobert`_LP64' 1940*404b540aSrobert These macros are defined, with value 1, if (and only if) the 1941*404b540aSrobert compilation is for a target where `long int' and pointer both use 1942*404b540aSrobert 64-bits and `int' uses 32-bit. 1943*404b540aSrobert 1944*404b540aSrobert`__SSP__' 1945*404b540aSrobert This macro is defined, with value 1, when `-fstack-protector' is in 1946*404b540aSrobert use. 1947*404b540aSrobert 1948*404b540aSrobert`__SSP_ALL__' 1949*404b540aSrobert This macro is defined, with value 2, when `-fstack-protector-all' 1950*404b540aSrobert is in use. 1951*404b540aSrobert 1952*404b540aSrobert`__TIMESTAMP__' 1953*404b540aSrobert This macro expands to a string constant that describes the date 1954*404b540aSrobert and time of the last modification of the current source file. The 1955*404b540aSrobert string constant contains abbreviated day of the week, month, day 1956*404b540aSrobert of the month, time in hh:mm:ss form, year and looks like 1957*404b540aSrobert `"Sun Sep 16 01:03:52 1973"'. If the day of the month is less 1958*404b540aSrobert than 10, it is padded with a space on the left. 1959*404b540aSrobert 1960*404b540aSrobert If GCC cannot determine the current date, it will emit a warning 1961*404b540aSrobert message (once per compilation) and `__TIMESTAMP__' will expand to 1962*404b540aSrobert `"??? ??? ?? ??:??:?? ????"'. 1963*404b540aSrobert 1964*404b540aSrobert 1965*404b540aSrobert 1966*404b540aSrobertFile: cpp.info, Node: System-specific Predefined Macros, Next: C++ Named Operators, Prev: Common Predefined Macros, Up: Predefined Macros 1967*404b540aSrobert 1968*404b540aSrobert3.7.3 System-specific Predefined Macros 1969*404b540aSrobert--------------------------------------- 1970*404b540aSrobert 1971*404b540aSrobertThe C preprocessor normally predefines several macros that indicate what 1972*404b540aSroberttype of system and machine is in use. They are obviously different on 1973*404b540aSroberteach target supported by GCC. This manual, being for all systems and 1974*404b540aSrobertmachines, cannot tell you what their names are, but you can use `cpp 1975*404b540aSrobert-dM' to see them all. *Note Invocation::. All system-specific 1976*404b540aSrobertpredefined macros expand to the constant 1, so you can test them with 1977*404b540aSroberteither `#ifdef' or `#if'. 1978*404b540aSrobert 1979*404b540aSrobert The C standard requires that all system-specific macros be part of 1980*404b540aSrobertthe "reserved namespace". All names which begin with two underscores, 1981*404b540aSrobertor an underscore and a capital letter, are reserved for the compiler and 1982*404b540aSrobertlibrary to use as they wish. However, historically system-specific 1983*404b540aSrobertmacros have had names with no special prefix; for instance, it is common 1984*404b540aSrobertto find `unix' defined on Unix systems. For all such macros, GCC 1985*404b540aSrobertprovides a parallel macro with two underscores added at the beginning 1986*404b540aSrobertand the end. If `unix' is defined, `__unix__' will be defined too. 1987*404b540aSrobertThere will never be more than two underscores; the parallel of `_mips' 1988*404b540aSrobertis `__mips__'. 1989*404b540aSrobert 1990*404b540aSrobert When the `-ansi' option, or any `-std' option that requests strict 1991*404b540aSrobertconformance, is given to the compiler, all the system-specific 1992*404b540aSrobertpredefined macros outside the reserved namespace are suppressed. The 1993*404b540aSrobertparallel macros, inside the reserved namespace, remain defined. 1994*404b540aSrobert 1995*404b540aSrobert We are slowly phasing out all predefined macros which are outside the 1996*404b540aSrobertreserved namespace. You should never use them in new programs, and we 1997*404b540aSrobertencourage you to correct older code to use the parallel macros whenever 1998*404b540aSrobertyou find it. We don't recommend you use the system-specific macros that 1999*404b540aSrobertare in the reserved namespace, either. It is better in the long run to 2000*404b540aSrobertcheck specifically for features you need, using a tool such as 2001*404b540aSrobert`autoconf'. 2002*404b540aSrobert 2003*404b540aSrobert 2004*404b540aSrobertFile: cpp.info, Node: C++ Named Operators, Prev: System-specific Predefined Macros, Up: Predefined Macros 2005*404b540aSrobert 2006*404b540aSrobert3.7.4 C++ Named Operators 2007*404b540aSrobert------------------------- 2008*404b540aSrobert 2009*404b540aSrobertIn C++, there are eleven keywords which are simply alternate spellings 2010*404b540aSrobertof operators normally written with punctuation. These keywords are 2011*404b540aSroberttreated as such even in the preprocessor. They function as operators in 2012*404b540aSrobert`#if', and they cannot be defined as macros or poisoned. In C, you can 2013*404b540aSrobertrequest that those keywords take their C++ meaning by including 2014*404b540aSrobert`iso646.h'. That header defines each one as a normal object-like macro 2015*404b540aSrobertexpanding to the appropriate punctuator. 2016*404b540aSrobert 2017*404b540aSrobert These are the named operators and their corresponding punctuators: 2018*404b540aSrobert 2019*404b540aSrobertNamed Operator Punctuator 2020*404b540aSrobert`and' `&&' 2021*404b540aSrobert`and_eq' `&=' 2022*404b540aSrobert`bitand' `&' 2023*404b540aSrobert`bitor' `|' 2024*404b540aSrobert`compl' `~' 2025*404b540aSrobert`not' `!' 2026*404b540aSrobert`not_eq' `!=' 2027*404b540aSrobert`or' `||' 2028*404b540aSrobert`or_eq' `|=' 2029*404b540aSrobert`xor' `^' 2030*404b540aSrobert`xor_eq' `^=' 2031*404b540aSrobert 2032*404b540aSrobert 2033*404b540aSrobertFile: cpp.info, Node: Undefining and Redefining Macros, Next: Directives Within Macro Arguments, Prev: Predefined Macros, Up: Macros 2034*404b540aSrobert 2035*404b540aSrobert3.8 Undefining and Redefining Macros 2036*404b540aSrobert==================================== 2037*404b540aSrobert 2038*404b540aSrobertIf a macro ceases to be useful, it may be "undefined" with the `#undef' 2039*404b540aSrobertdirective. `#undef' takes a single argument, the name of the macro to 2040*404b540aSrobertundefine. You use the bare macro name, even if the macro is 2041*404b540aSrobertfunction-like. It is an error if anything appears on the line after 2042*404b540aSrobertthe macro name. `#undef' has no effect if the name is not a macro. 2043*404b540aSrobert 2044*404b540aSrobert #define FOO 4 2045*404b540aSrobert x = FOO; ==> x = 4; 2046*404b540aSrobert #undef FOO 2047*404b540aSrobert x = FOO; ==> x = FOO; 2048*404b540aSrobert 2049*404b540aSrobert Once a macro has been undefined, that identifier may be "redefined" 2050*404b540aSrobertas a macro by a subsequent `#define' directive. The new definition 2051*404b540aSrobertneed not have any resemblance to the old definition. 2052*404b540aSrobert 2053*404b540aSrobert However, if an identifier which is currently a macro is redefined, 2054*404b540aSrobertthen the new definition must be "effectively the same" as the old one. 2055*404b540aSrobertTwo macro definitions are effectively the same if: 2056*404b540aSrobert * Both are the same type of macro (object- or function-like). 2057*404b540aSrobert 2058*404b540aSrobert * All the tokens of the replacement list are the same. 2059*404b540aSrobert 2060*404b540aSrobert * If there are any parameters, they are the same. 2061*404b540aSrobert 2062*404b540aSrobert * Whitespace appears in the same places in both. It need not be 2063*404b540aSrobert exactly the same amount of whitespace, though. Remember that 2064*404b540aSrobert comments count as whitespace. 2065*404b540aSrobert 2066*404b540aSrobertThese definitions are effectively the same: 2067*404b540aSrobert #define FOUR (2 + 2) 2068*404b540aSrobert #define FOUR (2 + 2) 2069*404b540aSrobert #define FOUR (2 /* two */ + 2) 2070*404b540aSrobert but these are not: 2071*404b540aSrobert #define FOUR (2 + 2) 2072*404b540aSrobert #define FOUR ( 2+2 ) 2073*404b540aSrobert #define FOUR (2 * 2) 2074*404b540aSrobert #define FOUR(score,and,seven,years,ago) (2 + 2) 2075*404b540aSrobert 2076*404b540aSrobert If a macro is redefined with a definition that is not effectively the 2077*404b540aSrobertsame as the old one, the preprocessor issues a warning and changes the 2078*404b540aSrobertmacro to use the new definition. If the new definition is effectively 2079*404b540aSrobertthe same, the redefinition is silently ignored. This allows, for 2080*404b540aSrobertinstance, two different headers to define a common macro. The 2081*404b540aSrobertpreprocessor will only complain if the definitions do not match. 2082*404b540aSrobert 2083*404b540aSrobert 2084*404b540aSrobertFile: cpp.info, Node: Directives Within Macro Arguments, Next: Macro Pitfalls, Prev: Undefining and Redefining Macros, Up: Macros 2085*404b540aSrobert 2086*404b540aSrobert3.9 Directives Within Macro Arguments 2087*404b540aSrobert===================================== 2088*404b540aSrobert 2089*404b540aSrobertOccasionally it is convenient to use preprocessor directives within the 2090*404b540aSrobertarguments of a macro. The C and C++ standards declare that behavior in 2091*404b540aSrobertthese cases is undefined. 2092*404b540aSrobert 2093*404b540aSrobert Versions of CPP prior to 3.2 would reject such constructs with an 2094*404b540aSroberterror message. This was the only syntactic difference between normal 2095*404b540aSrobertfunctions and function-like macros, so it seemed attractive to remove 2096*404b540aSrobertthis limitation, and people would often be surprised that they could 2097*404b540aSrobertnot use macros in this way. Moreover, sometimes people would use 2098*404b540aSrobertconditional compilation in the argument list to a normal library 2099*404b540aSrobertfunction like `printf', only to find that after a library upgrade 2100*404b540aSrobert`printf' had changed to be a function-like macro, and their code would 2101*404b540aSrobertno longer compile. So from version 3.2 we changed CPP to successfully 2102*404b540aSrobertprocess arbitrary directives within macro arguments in exactly the same 2103*404b540aSrobertway as it would have processed the directive were the function-like 2104*404b540aSrobertmacro invocation not present. 2105*404b540aSrobert 2106*404b540aSrobert If, within a macro invocation, that macro is redefined, then the new 2107*404b540aSrobertdefinition takes effect in time for argument pre-expansion, but the 2108*404b540aSrobertoriginal definition is still used for argument replacement. Here is a 2109*404b540aSrobertpathological example: 2110*404b540aSrobert 2111*404b540aSrobert #define f(x) x x 2112*404b540aSrobert f (1 2113*404b540aSrobert #undef f 2114*404b540aSrobert #define f 2 2115*404b540aSrobert f) 2116*404b540aSrobert 2117*404b540aSrobertwhich expands to 2118*404b540aSrobert 2119*404b540aSrobert 1 2 1 2 2120*404b540aSrobert 2121*404b540aSrobertwith the semantics described above. 2122*404b540aSrobert 2123*404b540aSrobert 2124*404b540aSrobertFile: cpp.info, Node: Macro Pitfalls, Prev: Directives Within Macro Arguments, Up: Macros 2125*404b540aSrobert 2126*404b540aSrobert3.10 Macro Pitfalls 2127*404b540aSrobert=================== 2128*404b540aSrobert 2129*404b540aSrobertIn this section we describe some special rules that apply to macros and 2130*404b540aSrobertmacro expansion, and point out certain cases in which the rules have 2131*404b540aSrobertcounter-intuitive consequences that you must watch out for. 2132*404b540aSrobert 2133*404b540aSrobert* Menu: 2134*404b540aSrobert 2135*404b540aSrobert* Misnesting:: 2136*404b540aSrobert* Operator Precedence Problems:: 2137*404b540aSrobert* Swallowing the Semicolon:: 2138*404b540aSrobert* Duplication of Side Effects:: 2139*404b540aSrobert* Self-Referential Macros:: 2140*404b540aSrobert* Argument Prescan:: 2141*404b540aSrobert* Newlines in Arguments:: 2142*404b540aSrobert 2143*404b540aSrobert 2144*404b540aSrobertFile: cpp.info, Node: Misnesting, Next: Operator Precedence Problems, Up: Macro Pitfalls 2145*404b540aSrobert 2146*404b540aSrobert3.10.1 Misnesting 2147*404b540aSrobert----------------- 2148*404b540aSrobert 2149*404b540aSrobertWhen a macro is called with arguments, the arguments are substituted 2150*404b540aSrobertinto the macro body and the result is checked, together with the rest of 2151*404b540aSrobertthe input file, for more macro calls. It is possible to piece together 2152*404b540aSroberta macro call coming partially from the macro body and partially from the 2153*404b540aSrobertarguments. For example, 2154*404b540aSrobert 2155*404b540aSrobert #define twice(x) (2*(x)) 2156*404b540aSrobert #define call_with_1(x) x(1) 2157*404b540aSrobert call_with_1 (twice) 2158*404b540aSrobert ==> twice(1) 2159*404b540aSrobert ==> (2*(1)) 2160*404b540aSrobert 2161*404b540aSrobert Macro definitions do not have to have balanced parentheses. By 2162*404b540aSrobertwriting an unbalanced open parenthesis in a macro body, it is possible 2163*404b540aSrobertto create a macro call that begins inside the macro body but ends 2164*404b540aSrobertoutside of it. For example, 2165*404b540aSrobert 2166*404b540aSrobert #define strange(file) fprintf (file, "%s %d", 2167*404b540aSrobert ... 2168*404b540aSrobert strange(stderr) p, 35) 2169*404b540aSrobert ==> fprintf (stderr, "%s %d", p, 35) 2170*404b540aSrobert 2171*404b540aSrobert The ability to piece together a macro call can be useful, but the 2172*404b540aSrobertuse of unbalanced open parentheses in a macro body is just confusing, 2173*404b540aSrobertand should be avoided. 2174*404b540aSrobert 2175*404b540aSrobert 2176*404b540aSrobertFile: cpp.info, Node: Operator Precedence Problems, Next: Swallowing the Semicolon, Prev: Misnesting, Up: Macro Pitfalls 2177*404b540aSrobert 2178*404b540aSrobert3.10.2 Operator Precedence Problems 2179*404b540aSrobert----------------------------------- 2180*404b540aSrobert 2181*404b540aSrobertYou may have noticed that in most of the macro definition examples shown 2182*404b540aSrobertabove, each occurrence of a macro argument name had parentheses around 2183*404b540aSrobertit. In addition, another pair of parentheses usually surround the 2184*404b540aSrobertentire macro definition. Here is why it is best to write macros that 2185*404b540aSrobertway. 2186*404b540aSrobert 2187*404b540aSrobert Suppose you define a macro as follows, 2188*404b540aSrobert 2189*404b540aSrobert #define ceil_div(x, y) (x + y - 1) / y 2190*404b540aSrobert 2191*404b540aSrobertwhose purpose is to divide, rounding up. (One use for this operation is 2192*404b540aSrobertto compute how many `int' objects are needed to hold a certain number 2193*404b540aSrobertof `char' objects.) Then suppose it is used as follows: 2194*404b540aSrobert 2195*404b540aSrobert a = ceil_div (b & c, sizeof (int)); 2196*404b540aSrobert ==> a = (b & c + sizeof (int) - 1) / sizeof (int); 2197*404b540aSrobert 2198*404b540aSrobertThis does not do what is intended. The operator-precedence rules of C 2199*404b540aSrobertmake it equivalent to this: 2200*404b540aSrobert 2201*404b540aSrobert a = (b & (c + sizeof (int) - 1)) / sizeof (int); 2202*404b540aSrobert 2203*404b540aSrobertWhat we want is this: 2204*404b540aSrobert 2205*404b540aSrobert a = ((b & c) + sizeof (int) - 1)) / sizeof (int); 2206*404b540aSrobert 2207*404b540aSrobertDefining the macro as 2208*404b540aSrobert 2209*404b540aSrobert #define ceil_div(x, y) ((x) + (y) - 1) / (y) 2210*404b540aSrobert 2211*404b540aSrobertprovides the desired result. 2212*404b540aSrobert 2213*404b540aSrobert Unintended grouping can result in another way. Consider `sizeof 2214*404b540aSrobertceil_div(1, 2)'. That has the appearance of a C expression that would 2215*404b540aSrobertcompute the size of the type of `ceil_div (1, 2)', but in fact it means 2216*404b540aSrobertsomething very different. Here is what it expands to: 2217*404b540aSrobert 2218*404b540aSrobert sizeof ((1) + (2) - 1) / (2) 2219*404b540aSrobert 2220*404b540aSrobertThis would take the size of an integer and divide it by two. The 2221*404b540aSrobertprecedence rules have put the division outside the `sizeof' when it was 2222*404b540aSrobertintended to be inside. 2223*404b540aSrobert 2224*404b540aSrobert Parentheses around the entire macro definition prevent such problems. 2225*404b540aSrobertHere, then, is the recommended way to define `ceil_div': 2226*404b540aSrobert 2227*404b540aSrobert #define ceil_div(x, y) (((x) + (y) - 1) / (y)) 2228*404b540aSrobert 2229*404b540aSrobert 2230*404b540aSrobertFile: cpp.info, Node: Swallowing the Semicolon, Next: Duplication of Side Effects, Prev: Operator Precedence Problems, Up: Macro Pitfalls 2231*404b540aSrobert 2232*404b540aSrobert3.10.3 Swallowing the Semicolon 2233*404b540aSrobert------------------------------- 2234*404b540aSrobert 2235*404b540aSrobertOften it is desirable to define a macro that expands into a compound 2236*404b540aSrobertstatement. Consider, for example, the following macro, that advances a 2237*404b540aSrobertpointer (the argument `p' says where to find it) across whitespace 2238*404b540aSrobertcharacters: 2239*404b540aSrobert 2240*404b540aSrobert #define SKIP_SPACES(p, limit) \ 2241*404b540aSrobert { char *lim = (limit); \ 2242*404b540aSrobert while (p < lim) { \ 2243*404b540aSrobert if (*p++ != ' ') { \ 2244*404b540aSrobert p--; break; }}} 2245*404b540aSrobert 2246*404b540aSrobertHere backslash-newline is used to split the macro definition, which must 2247*404b540aSrobertbe a single logical line, so that it resembles the way such code would 2248*404b540aSrobertbe laid out if not part of a macro definition. 2249*404b540aSrobert 2250*404b540aSrobert A call to this macro might be `SKIP_SPACES (p, lim)'. Strictly 2251*404b540aSrobertspeaking, the call expands to a compound statement, which is a complete 2252*404b540aSrobertstatement with no need for a semicolon to end it. However, since it 2253*404b540aSrobertlooks like a function call, it minimizes confusion if you can use it 2254*404b540aSrobertlike a function call, writing a semicolon afterward, as in `SKIP_SPACES 2255*404b540aSrobert(p, lim);' 2256*404b540aSrobert 2257*404b540aSrobert This can cause trouble before `else' statements, because the 2258*404b540aSrobertsemicolon is actually a null statement. Suppose you write 2259*404b540aSrobert 2260*404b540aSrobert if (*p != 0) 2261*404b540aSrobert SKIP_SPACES (p, lim); 2262*404b540aSrobert else ... 2263*404b540aSrobert 2264*404b540aSrobertThe presence of two statements--the compound statement and a null 2265*404b540aSrobertstatement--in between the `if' condition and the `else' makes invalid C 2266*404b540aSrobertcode. 2267*404b540aSrobert 2268*404b540aSrobert The definition of the macro `SKIP_SPACES' can be altered to solve 2269*404b540aSrobertthis problem, using a `do ... while' statement. Here is how: 2270*404b540aSrobert 2271*404b540aSrobert #define SKIP_SPACES(p, limit) \ 2272*404b540aSrobert do { char *lim = (limit); \ 2273*404b540aSrobert while (p < lim) { \ 2274*404b540aSrobert if (*p++ != ' ') { \ 2275*404b540aSrobert p--; break; }}} \ 2276*404b540aSrobert while (0) 2277*404b540aSrobert 2278*404b540aSrobert Now `SKIP_SPACES (p, lim);' expands into 2279*404b540aSrobert 2280*404b540aSrobert do {...} while (0); 2281*404b540aSrobert 2282*404b540aSrobertwhich is one statement. The loop executes exactly once; most compilers 2283*404b540aSrobertgenerate no extra code for it. 2284*404b540aSrobert 2285*404b540aSrobert 2286*404b540aSrobertFile: cpp.info, Node: Duplication of Side Effects, Next: Self-Referential Macros, Prev: Swallowing the Semicolon, Up: Macro Pitfalls 2287*404b540aSrobert 2288*404b540aSrobert3.10.4 Duplication of Side Effects 2289*404b540aSrobert---------------------------------- 2290*404b540aSrobert 2291*404b540aSrobertMany C programs define a macro `min', for "minimum", like this: 2292*404b540aSrobert 2293*404b540aSrobert #define min(X, Y) ((X) < (Y) ? (X) : (Y)) 2294*404b540aSrobert 2295*404b540aSrobert When you use this macro with an argument containing a side effect, 2296*404b540aSrobertas shown here, 2297*404b540aSrobert 2298*404b540aSrobert next = min (x + y, foo (z)); 2299*404b540aSrobert 2300*404b540aSrobertit expands as follows: 2301*404b540aSrobert 2302*404b540aSrobert next = ((x + y) < (foo (z)) ? (x + y) : (foo (z))); 2303*404b540aSrobert 2304*404b540aSrobertwhere `x + y' has been substituted for `X' and `foo (z)' for `Y'. 2305*404b540aSrobert 2306*404b540aSrobert The function `foo' is used only once in the statement as it appears 2307*404b540aSrobertin the program, but the expression `foo (z)' has been substituted twice 2308*404b540aSrobertinto the macro expansion. As a result, `foo' might be called two times 2309*404b540aSrobertwhen the statement is executed. If it has side effects or if it takes 2310*404b540aSroberta long time to compute, the results might not be what you intended. We 2311*404b540aSrobertsay that `min' is an "unsafe" macro. 2312*404b540aSrobert 2313*404b540aSrobert The best solution to this problem is to define `min' in a way that 2314*404b540aSrobertcomputes the value of `foo (z)' only once. The C language offers no 2315*404b540aSrobertstandard way to do this, but it can be done with GNU extensions as 2316*404b540aSrobertfollows: 2317*404b540aSrobert 2318*404b540aSrobert #define min(X, Y) \ 2319*404b540aSrobert ({ typeof (X) x_ = (X); \ 2320*404b540aSrobert typeof (Y) y_ = (Y); \ 2321*404b540aSrobert (x_ < y_) ? x_ : y_; }) 2322*404b540aSrobert 2323*404b540aSrobert The `({ ... })' notation produces a compound statement that acts as 2324*404b540aSrobertan expression. Its value is the value of its last statement. This 2325*404b540aSrobertpermits us to define local variables and assign each argument to one. 2326*404b540aSrobertThe local variables have underscores after their names to reduce the 2327*404b540aSrobertrisk of conflict with an identifier of wider scope (it is impossible to 2328*404b540aSrobertavoid this entirely). Now each argument is evaluated exactly once. 2329*404b540aSrobert 2330*404b540aSrobert If you do not wish to use GNU C extensions, the only solution is to 2331*404b540aSrobertbe careful when _using_ the macro `min'. For example, you can 2332*404b540aSrobertcalculate the value of `foo (z)', save it in a variable, and use that 2333*404b540aSrobertvariable in `min': 2334*404b540aSrobert 2335*404b540aSrobert #define min(X, Y) ((X) < (Y) ? (X) : (Y)) 2336*404b540aSrobert ... 2337*404b540aSrobert { 2338*404b540aSrobert int tem = foo (z); 2339*404b540aSrobert next = min (x + y, tem); 2340*404b540aSrobert } 2341*404b540aSrobert 2342*404b540aSrobert(where we assume that `foo' returns type `int'). 2343*404b540aSrobert 2344*404b540aSrobert 2345*404b540aSrobertFile: cpp.info, Node: Self-Referential Macros, Next: Argument Prescan, Prev: Duplication of Side Effects, Up: Macro Pitfalls 2346*404b540aSrobert 2347*404b540aSrobert3.10.5 Self-Referential Macros 2348*404b540aSrobert------------------------------ 2349*404b540aSrobert 2350*404b540aSrobertA "self-referential" macro is one whose name appears in its definition. 2351*404b540aSrobertRecall that all macro definitions are rescanned for more macros to 2352*404b540aSrobertreplace. If the self-reference were considered a use of the macro, it 2353*404b540aSrobertwould produce an infinitely large expansion. To prevent this, the 2354*404b540aSrobertself-reference is not considered a macro call. It is passed into the 2355*404b540aSrobertpreprocessor output unchanged. Consider an example: 2356*404b540aSrobert 2357*404b540aSrobert #define foo (4 + foo) 2358*404b540aSrobert 2359*404b540aSrobertwhere `foo' is also a variable in your program. 2360*404b540aSrobert 2361*404b540aSrobert Following the ordinary rules, each reference to `foo' will expand 2362*404b540aSrobertinto `(4 + foo)'; then this will be rescanned and will expand into `(4 2363*404b540aSrobert+ (4 + foo))'; and so on until the computer runs out of memory. 2364*404b540aSrobert 2365*404b540aSrobert The self-reference rule cuts this process short after one step, at 2366*404b540aSrobert`(4 + foo)'. Therefore, this macro definition has the possibly useful 2367*404b540aSroberteffect of causing the program to add 4 to the value of `foo' wherever 2368*404b540aSrobert`foo' is referred to. 2369*404b540aSrobert 2370*404b540aSrobert In most cases, it is a bad idea to take advantage of this feature. A 2371*404b540aSrobertperson reading the program who sees that `foo' is a variable will not 2372*404b540aSrobertexpect that it is a macro as well. The reader will come across the 2373*404b540aSrobertidentifier `foo' in the program and think its value should be that of 2374*404b540aSrobertthe variable `foo', whereas in fact the value is four greater. 2375*404b540aSrobert 2376*404b540aSrobert One common, useful use of self-reference is to create a macro which 2377*404b540aSrobertexpands to itself. If you write 2378*404b540aSrobert 2379*404b540aSrobert #define EPERM EPERM 2380*404b540aSrobert 2381*404b540aSrobertthen the macro `EPERM' expands to `EPERM'. Effectively, it is left 2382*404b540aSrobertalone by the preprocessor whenever it's used in running text. You can 2383*404b540aSroberttell that it's a macro with `#ifdef'. You might do this if you want to 2384*404b540aSrobertdefine numeric constants with an `enum', but have `#ifdef' be true for 2385*404b540aSroberteach constant. 2386*404b540aSrobert 2387*404b540aSrobert If a macro `x' expands to use a macro `y', and the expansion of `y' 2388*404b540aSrobertrefers to the macro `x', that is an "indirect self-reference" of `x'. 2389*404b540aSrobert`x' is not expanded in this case either. Thus, if we have 2390*404b540aSrobert 2391*404b540aSrobert #define x (4 + y) 2392*404b540aSrobert #define y (2 * x) 2393*404b540aSrobert 2394*404b540aSrobertthen `x' and `y' expand as follows: 2395*404b540aSrobert 2396*404b540aSrobert x ==> (4 + y) 2397*404b540aSrobert ==> (4 + (2 * x)) 2398*404b540aSrobert 2399*404b540aSrobert y ==> (2 * x) 2400*404b540aSrobert ==> (2 * (4 + y)) 2401*404b540aSrobert 2402*404b540aSrobertEach macro is expanded when it appears in the definition of the other 2403*404b540aSrobertmacro, but not when it indirectly appears in its own definition. 2404*404b540aSrobert 2405*404b540aSrobert 2406*404b540aSrobertFile: cpp.info, Node: Argument Prescan, Next: Newlines in Arguments, Prev: Self-Referential Macros, Up: Macro Pitfalls 2407*404b540aSrobert 2408*404b540aSrobert3.10.6 Argument Prescan 2409*404b540aSrobert----------------------- 2410*404b540aSrobert 2411*404b540aSrobertMacro arguments are completely macro-expanded before they are 2412*404b540aSrobertsubstituted into a macro body, unless they are stringified or pasted 2413*404b540aSrobertwith other tokens. After substitution, the entire macro body, including 2414*404b540aSrobertthe substituted arguments, is scanned again for macros to be expanded. 2415*404b540aSrobertThe result is that the arguments are scanned _twice_ to expand macro 2416*404b540aSrobertcalls in them. 2417*404b540aSrobert 2418*404b540aSrobert Most of the time, this has no effect. If the argument contained any 2419*404b540aSrobertmacro calls, they are expanded during the first scan. The result 2420*404b540aSroberttherefore contains no macro calls, so the second scan does not change 2421*404b540aSrobertit. If the argument were substituted as given, with no prescan, the 2422*404b540aSrobertsingle remaining scan would find the same macro calls and produce the 2423*404b540aSrobertsame results. 2424*404b540aSrobert 2425*404b540aSrobert You might expect the double scan to change the results when a 2426*404b540aSrobertself-referential macro is used in an argument of another macro (*note 2427*404b540aSrobertSelf-Referential Macros::): the self-referential macro would be 2428*404b540aSrobertexpanded once in the first scan, and a second time in the second scan. 2429*404b540aSrobertHowever, this is not what happens. The self-references that do not 2430*404b540aSrobertexpand in the first scan are marked so that they will not expand in the 2431*404b540aSrobertsecond scan either. 2432*404b540aSrobert 2433*404b540aSrobert You might wonder, "Why mention the prescan, if it makes no 2434*404b540aSrobertdifference? And why not skip it and make the preprocessor faster?" 2435*404b540aSrobertThe answer is that the prescan does make a difference in three special 2436*404b540aSrobertcases: 2437*404b540aSrobert 2438*404b540aSrobert * Nested calls to a macro. 2439*404b540aSrobert 2440*404b540aSrobert We say that "nested" calls to a macro occur when a macro's argument 2441*404b540aSrobert contains a call to that very macro. For example, if `f' is a macro 2442*404b540aSrobert that expects one argument, `f (f (1))' is a nested pair of calls to 2443*404b540aSrobert `f'. The desired expansion is made by expanding `f (1)' and 2444*404b540aSrobert substituting that into the definition of `f'. The prescan causes 2445*404b540aSrobert the expected result to happen. Without the prescan, `f (1)' itself 2446*404b540aSrobert would be substituted as an argument, and the inner use of `f' would 2447*404b540aSrobert appear during the main scan as an indirect self-reference and 2448*404b540aSrobert would not be expanded. 2449*404b540aSrobert 2450*404b540aSrobert * Macros that call other macros that stringify or concatenate. 2451*404b540aSrobert 2452*404b540aSrobert If an argument is stringified or concatenated, the prescan does not 2453*404b540aSrobert occur. If you _want_ to expand a macro, then stringify or 2454*404b540aSrobert concatenate its expansion, you can do that by causing one macro to 2455*404b540aSrobert call another macro that does the stringification or concatenation. 2456*404b540aSrobert For instance, if you have 2457*404b540aSrobert 2458*404b540aSrobert #define AFTERX(x) X_ ## x 2459*404b540aSrobert #define XAFTERX(x) AFTERX(x) 2460*404b540aSrobert #define TABLESIZE 1024 2461*404b540aSrobert #define BUFSIZE TABLESIZE 2462*404b540aSrobert 2463*404b540aSrobert then `AFTERX(BUFSIZE)' expands to `X_BUFSIZE', and 2464*404b540aSrobert `XAFTERX(BUFSIZE)' expands to `X_1024'. (Not to `X_TABLESIZE'. 2465*404b540aSrobert Prescan always does a complete expansion.) 2466*404b540aSrobert 2467*404b540aSrobert * Macros used in arguments, whose expansions contain unshielded 2468*404b540aSrobert commas. 2469*404b540aSrobert 2470*404b540aSrobert This can cause a macro expanded on the second scan to be called 2471*404b540aSrobert with the wrong number of arguments. Here is an example: 2472*404b540aSrobert 2473*404b540aSrobert #define foo a,b 2474*404b540aSrobert #define bar(x) lose(x) 2475*404b540aSrobert #define lose(x) (1 + (x)) 2476*404b540aSrobert 2477*404b540aSrobert We would like `bar(foo)' to turn into `(1 + (foo))', which would 2478*404b540aSrobert then turn into `(1 + (a,b))'. Instead, `bar(foo)' expands into 2479*404b540aSrobert `lose(a,b)', and you get an error because `lose' requires a single 2480*404b540aSrobert argument. In this case, the problem is easily solved by the same 2481*404b540aSrobert parentheses that ought to be used to prevent misnesting of 2482*404b540aSrobert arithmetic operations: 2483*404b540aSrobert 2484*404b540aSrobert #define foo (a,b) 2485*404b540aSrobert or 2486*404b540aSrobert #define bar(x) lose((x)) 2487*404b540aSrobert 2488*404b540aSrobert The extra pair of parentheses prevents the comma in `foo''s 2489*404b540aSrobert definition from being interpreted as an argument separator. 2490*404b540aSrobert 2491*404b540aSrobert 2492*404b540aSrobert 2493*404b540aSrobertFile: cpp.info, Node: Newlines in Arguments, Prev: Argument Prescan, Up: Macro Pitfalls 2494*404b540aSrobert 2495*404b540aSrobert3.10.7 Newlines in Arguments 2496*404b540aSrobert---------------------------- 2497*404b540aSrobert 2498*404b540aSrobertThe invocation of a function-like macro can extend over many logical 2499*404b540aSrobertlines. However, in the present implementation, the entire expansion 2500*404b540aSrobertcomes out on one line. Thus line numbers emitted by the compiler or 2501*404b540aSrobertdebugger refer to the line the invocation started on, which might be 2502*404b540aSrobertdifferent to the line containing the argument causing the problem. 2503*404b540aSrobert 2504*404b540aSrobert Here is an example illustrating this: 2505*404b540aSrobert 2506*404b540aSrobert #define ignore_second_arg(a,b,c) a; c 2507*404b540aSrobert 2508*404b540aSrobert ignore_second_arg (foo (), 2509*404b540aSrobert ignored (), 2510*404b540aSrobert syntax error); 2511*404b540aSrobert 2512*404b540aSrobertThe syntax error triggered by the tokens `syntax error' results in an 2513*404b540aSroberterror message citing line three--the line of ignore_second_arg-- even 2514*404b540aSrobertthough the problematic code comes from line five. 2515*404b540aSrobert 2516*404b540aSrobert We consider this a bug, and intend to fix it in the near future. 2517*404b540aSrobert 2518*404b540aSrobert 2519*404b540aSrobertFile: cpp.info, Node: Conditionals, Next: Diagnostics, Prev: Macros, Up: Top 2520*404b540aSrobert 2521*404b540aSrobert4 Conditionals 2522*404b540aSrobert************** 2523*404b540aSrobert 2524*404b540aSrobertA "conditional" is a directive that instructs the preprocessor to 2525*404b540aSrobertselect whether or not to include a chunk of code in the final token 2526*404b540aSrobertstream passed to the compiler. Preprocessor conditionals can test 2527*404b540aSrobertarithmetic expressions, or whether a name is defined as a macro, or both 2528*404b540aSrobertsimultaneously using the special `defined' operator. 2529*404b540aSrobert 2530*404b540aSrobert A conditional in the C preprocessor resembles in some ways an `if' 2531*404b540aSrobertstatement in C, but it is important to understand the difference between 2532*404b540aSrobertthem. The condition in an `if' statement is tested during the 2533*404b540aSrobertexecution of your program. Its purpose is to allow your program to 2534*404b540aSrobertbehave differently from run to run, depending on the data it is 2535*404b540aSrobertoperating on. The condition in a preprocessing conditional directive is 2536*404b540aSroberttested when your program is compiled. Its purpose is to allow different 2537*404b540aSrobertcode to be included in the program depending on the situation at the 2538*404b540aSroberttime of compilation. 2539*404b540aSrobert 2540*404b540aSrobert However, the distinction is becoming less clear. Modern compilers 2541*404b540aSrobertoften do test `if' statements when a program is compiled, if their 2542*404b540aSrobertconditions are known not to vary at run time, and eliminate code which 2543*404b540aSrobertcan never be executed. If you can count on your compiler to do this, 2544*404b540aSrobertyou may find that your program is more readable if you use `if' 2545*404b540aSrobertstatements with constant conditions (perhaps determined by macros). Of 2546*404b540aSrobertcourse, you can only use this to exclude code, not type definitions or 2547*404b540aSrobertother preprocessing directives, and you can only do it if the code 2548*404b540aSrobertremains syntactically valid when it is not to be used. 2549*404b540aSrobert 2550*404b540aSrobert GCC version 3 eliminates this kind of never-executed code even when 2551*404b540aSrobertnot optimizing. Older versions did it only when optimizing. 2552*404b540aSrobert 2553*404b540aSrobert* Menu: 2554*404b540aSrobert 2555*404b540aSrobert* Conditional Uses:: 2556*404b540aSrobert* Conditional Syntax:: 2557*404b540aSrobert* Deleted Code:: 2558*404b540aSrobert 2559*404b540aSrobert 2560*404b540aSrobertFile: cpp.info, Node: Conditional Uses, Next: Conditional Syntax, Up: Conditionals 2561*404b540aSrobert 2562*404b540aSrobert4.1 Conditional Uses 2563*404b540aSrobert==================== 2564*404b540aSrobert 2565*404b540aSrobertThere are three general reasons to use a conditional. 2566*404b540aSrobert 2567*404b540aSrobert * A program may need to use different code depending on the machine 2568*404b540aSrobert or operating system it is to run on. In some cases the code for 2569*404b540aSrobert one operating system may be erroneous on another operating system; 2570*404b540aSrobert for example, it might refer to data types or constants that do not 2571*404b540aSrobert exist on the other system. When this happens, it is not enough to 2572*404b540aSrobert avoid executing the invalid code. Its mere presence will cause 2573*404b540aSrobert the compiler to reject the program. With a preprocessing 2574*404b540aSrobert conditional, the offending code can be effectively excised from 2575*404b540aSrobert the program when it is not valid. 2576*404b540aSrobert 2577*404b540aSrobert * You may want to be able to compile the same source file into two 2578*404b540aSrobert different programs. One version might make frequent time-consuming 2579*404b540aSrobert consistency checks on its intermediate data, or print the values of 2580*404b540aSrobert those data for debugging, and the other not. 2581*404b540aSrobert 2582*404b540aSrobert * A conditional whose condition is always false is one way to 2583*404b540aSrobert exclude code from the program but keep it as a sort of comment for 2584*404b540aSrobert future reference. 2585*404b540aSrobert 2586*404b540aSrobert Simple programs that do not need system-specific logic or complex 2587*404b540aSrobertdebugging hooks generally will not need to use preprocessing 2588*404b540aSrobertconditionals. 2589*404b540aSrobert 2590*404b540aSrobert 2591*404b540aSrobertFile: cpp.info, Node: Conditional Syntax, Next: Deleted Code, Prev: Conditional Uses, Up: Conditionals 2592*404b540aSrobert 2593*404b540aSrobert4.2 Conditional Syntax 2594*404b540aSrobert====================== 2595*404b540aSrobert 2596*404b540aSrobertA conditional in the C preprocessor begins with a "conditional 2597*404b540aSrobertdirective": `#if', `#ifdef' or `#ifndef'. 2598*404b540aSrobert 2599*404b540aSrobert* Menu: 2600*404b540aSrobert 2601*404b540aSrobert* Ifdef:: 2602*404b540aSrobert* If:: 2603*404b540aSrobert* Defined:: 2604*404b540aSrobert* Else:: 2605*404b540aSrobert* Elif:: 2606*404b540aSrobert 2607*404b540aSrobert 2608*404b540aSrobertFile: cpp.info, Node: Ifdef, Next: If, Up: Conditional Syntax 2609*404b540aSrobert 2610*404b540aSrobert4.2.1 Ifdef 2611*404b540aSrobert----------- 2612*404b540aSrobert 2613*404b540aSrobertThe simplest sort of conditional is 2614*404b540aSrobert 2615*404b540aSrobert #ifdef MACRO 2616*404b540aSrobert 2617*404b540aSrobert CONTROLLED TEXT 2618*404b540aSrobert 2619*404b540aSrobert #endif /* MACRO */ 2620*404b540aSrobert 2621*404b540aSrobert This block is called a "conditional group". CONTROLLED TEXT will be 2622*404b540aSrobertincluded in the output of the preprocessor if and only if MACRO is 2623*404b540aSrobertdefined. We say that the conditional "succeeds" if MACRO is defined, 2624*404b540aSrobert"fails" if it is not. 2625*404b540aSrobert 2626*404b540aSrobert The CONTROLLED TEXT inside of a conditional can include 2627*404b540aSrobertpreprocessing directives. They are executed only if the conditional 2628*404b540aSrobertsucceeds. You can nest conditional groups inside other conditional 2629*404b540aSrobertgroups, but they must be completely nested. In other words, `#endif' 2630*404b540aSrobertalways matches the nearest `#ifdef' (or `#ifndef', or `#if'). Also, 2631*404b540aSrobertyou cannot start a conditional group in one file and end it in another. 2632*404b540aSrobert 2633*404b540aSrobert Even if a conditional fails, the CONTROLLED TEXT inside it is still 2634*404b540aSrobertrun through initial transformations and tokenization. Therefore, it 2635*404b540aSrobertmust all be lexically valid C. Normally the only way this matters is 2636*404b540aSrobertthat all comments and string literals inside a failing conditional group 2637*404b540aSrobertmust still be properly ended. 2638*404b540aSrobert 2639*404b540aSrobert The comment following the `#endif' is not required, but it is a good 2640*404b540aSrobertpractice if there is a lot of CONTROLLED TEXT, because it helps people 2641*404b540aSrobertmatch the `#endif' to the corresponding `#ifdef'. Older programs 2642*404b540aSrobertsometimes put MACRO directly after the `#endif' without enclosing it in 2643*404b540aSroberta comment. This is invalid code according to the C standard. CPP 2644*404b540aSrobertaccepts it with a warning. It never affects which `#ifndef' the 2645*404b540aSrobert`#endif' matches. 2646*404b540aSrobert 2647*404b540aSrobert Sometimes you wish to use some code if a macro is _not_ defined. 2648*404b540aSrobertYou can do this by writing `#ifndef' instead of `#ifdef'. One common 2649*404b540aSrobertuse of `#ifndef' is to include code only the first time a header file 2650*404b540aSrobertis included. *Note Once-Only Headers::. 2651*404b540aSrobert 2652*404b540aSrobert Macro definitions can vary between compilations for several reasons. 2653*404b540aSrobertHere are some samples. 2654*404b540aSrobert 2655*404b540aSrobert * Some macros are predefined on each kind of machine (*note 2656*404b540aSrobert System-specific Predefined Macros::). This allows you to provide 2657*404b540aSrobert code specially tuned for a particular machine. 2658*404b540aSrobert 2659*404b540aSrobert * System header files define more macros, associated with the 2660*404b540aSrobert features they implement. You can test these macros with 2661*404b540aSrobert conditionals to avoid using a system feature on a machine where it 2662*404b540aSrobert is not implemented. 2663*404b540aSrobert 2664*404b540aSrobert * Macros can be defined or undefined with the `-D' and `-U' command 2665*404b540aSrobert line options when you compile the program. You can arrange to 2666*404b540aSrobert compile the same source file into two different programs by 2667*404b540aSrobert choosing a macro name to specify which program you want, writing 2668*404b540aSrobert conditionals to test whether or how this macro is defined, and 2669*404b540aSrobert then controlling the state of the macro with command line options, 2670*404b540aSrobert perhaps set in the Makefile. *Note Invocation::. 2671*404b540aSrobert 2672*404b540aSrobert * Your program might have a special header file (often called 2673*404b540aSrobert `config.h') that is adjusted when the program is compiled. It can 2674*404b540aSrobert define or not define macros depending on the features of the 2675*404b540aSrobert system and the desired capabilities of the program. The 2676*404b540aSrobert adjustment can be automated by a tool such as `autoconf', or done 2677*404b540aSrobert by hand. 2678*404b540aSrobert 2679*404b540aSrobert 2680*404b540aSrobertFile: cpp.info, Node: If, Next: Defined, Prev: Ifdef, Up: Conditional Syntax 2681*404b540aSrobert 2682*404b540aSrobert4.2.2 If 2683*404b540aSrobert-------- 2684*404b540aSrobert 2685*404b540aSrobertThe `#if' directive allows you to test the value of an arithmetic 2686*404b540aSrobertexpression, rather than the mere existence of one macro. Its syntax is 2687*404b540aSrobert 2688*404b540aSrobert #if EXPRESSION 2689*404b540aSrobert 2690*404b540aSrobert CONTROLLED TEXT 2691*404b540aSrobert 2692*404b540aSrobert #endif /* EXPRESSION */ 2693*404b540aSrobert 2694*404b540aSrobert EXPRESSION is a C expression of integer type, subject to stringent 2695*404b540aSrobertrestrictions. It may contain 2696*404b540aSrobert 2697*404b540aSrobert * Integer constants. 2698*404b540aSrobert 2699*404b540aSrobert * Character constants, which are interpreted as they would be in 2700*404b540aSrobert normal code. 2701*404b540aSrobert 2702*404b540aSrobert * Arithmetic operators for addition, subtraction, multiplication, 2703*404b540aSrobert division, bitwise operations, shifts, comparisons, and logical 2704*404b540aSrobert operations (`&&' and `||'). The latter two obey the usual 2705*404b540aSrobert short-circuiting rules of standard C. 2706*404b540aSrobert 2707*404b540aSrobert * Macros. All macros in the expression are expanded before actual 2708*404b540aSrobert computation of the expression's value begins. 2709*404b540aSrobert 2710*404b540aSrobert * Uses of the `defined' operator, which lets you check whether macros 2711*404b540aSrobert are defined in the middle of an `#if'. 2712*404b540aSrobert 2713*404b540aSrobert * Identifiers that are not macros, which are all considered to be the 2714*404b540aSrobert number zero. This allows you to write `#if MACRO' instead of 2715*404b540aSrobert `#ifdef MACRO', if you know that MACRO, when defined, will always 2716*404b540aSrobert have a nonzero value. Function-like macros used without their 2717*404b540aSrobert function call parentheses are also treated as zero. 2718*404b540aSrobert 2719*404b540aSrobert In some contexts this shortcut is undesirable. The `-Wundef' 2720*404b540aSrobert option causes GCC to warn whenever it encounters an identifier 2721*404b540aSrobert which is not a macro in an `#if'. 2722*404b540aSrobert 2723*404b540aSrobert The preprocessor does not know anything about types in the language. 2724*404b540aSrobertTherefore, `sizeof' operators are not recognized in `#if', and neither 2725*404b540aSrobertare `enum' constants. They will be taken as identifiers which are not 2726*404b540aSrobertmacros, and replaced by zero. In the case of `sizeof', this is likely 2727*404b540aSrobertto cause the expression to be invalid. 2728*404b540aSrobert 2729*404b540aSrobert The preprocessor calculates the value of EXPRESSION. It carries out 2730*404b540aSrobertall calculations in the widest integer type known to the compiler; on 2731*404b540aSrobertmost machines supported by GCC this is 64 bits. This is not the same 2732*404b540aSrobertrule as the compiler uses to calculate the value of a constant 2733*404b540aSrobertexpression, and may give different results in some cases. If the value 2734*404b540aSrobertcomes out to be nonzero, the `#if' succeeds and the CONTROLLED TEXT is 2735*404b540aSrobertincluded; otherwise it is skipped. 2736*404b540aSrobert 2737*404b540aSrobert 2738*404b540aSrobertFile: cpp.info, Node: Defined, Next: Else, Prev: If, Up: Conditional Syntax 2739*404b540aSrobert 2740*404b540aSrobert4.2.3 Defined 2741*404b540aSrobert------------- 2742*404b540aSrobert 2743*404b540aSrobertThe special operator `defined' is used in `#if' and `#elif' expressions 2744*404b540aSrobertto test whether a certain name is defined as a macro. `defined NAME' 2745*404b540aSrobertand `defined (NAME)' are both expressions whose value is 1 if NAME is 2746*404b540aSrobertdefined as a macro at the current point in the program, and 0 2747*404b540aSrobertotherwise. Thus, `#if defined MACRO' is precisely equivalent to 2748*404b540aSrobert`#ifdef MACRO'. 2749*404b540aSrobert 2750*404b540aSrobert `defined' is useful when you wish to test more than one macro for 2751*404b540aSrobertexistence at once. For example, 2752*404b540aSrobert 2753*404b540aSrobert #if defined (__vax__) || defined (__ns16000__) 2754*404b540aSrobert 2755*404b540aSrobertwould succeed if either of the names `__vax__' or `__ns16000__' is 2756*404b540aSrobertdefined as a macro. 2757*404b540aSrobert 2758*404b540aSrobert Conditionals written like this: 2759*404b540aSrobert 2760*404b540aSrobert #if defined BUFSIZE && BUFSIZE >= 1024 2761*404b540aSrobert 2762*404b540aSrobertcan generally be simplified to just `#if BUFSIZE >= 1024', since if 2763*404b540aSrobert`BUFSIZE' is not defined, it will be interpreted as having the value 2764*404b540aSrobertzero. 2765*404b540aSrobert 2766*404b540aSrobert If the `defined' operator appears as a result of a macro expansion, 2767*404b540aSrobertthe C standard says the behavior is undefined. GNU cpp treats it as a 2768*404b540aSrobertgenuine `defined' operator and evaluates it normally. It will warn 2769*404b540aSrobertwherever your code uses this feature if you use the command-line option 2770*404b540aSrobert`-pedantic', since other compilers may handle it differently. 2771*404b540aSrobert 2772*404b540aSrobert 2773*404b540aSrobertFile: cpp.info, Node: Else, Next: Elif, Prev: Defined, Up: Conditional Syntax 2774*404b540aSrobert 2775*404b540aSrobert4.2.4 Else 2776*404b540aSrobert---------- 2777*404b540aSrobert 2778*404b540aSrobertThe `#else' directive can be added to a conditional to provide 2779*404b540aSrobertalternative text to be used if the condition fails. This is what it 2780*404b540aSrobertlooks like: 2781*404b540aSrobert 2782*404b540aSrobert #if EXPRESSION 2783*404b540aSrobert TEXT-IF-TRUE 2784*404b540aSrobert #else /* Not EXPRESSION */ 2785*404b540aSrobert TEXT-IF-FALSE 2786*404b540aSrobert #endif /* Not EXPRESSION */ 2787*404b540aSrobert 2788*404b540aSrobertIf EXPRESSION is nonzero, the TEXT-IF-TRUE is included and the 2789*404b540aSrobertTEXT-IF-FALSE is skipped. If EXPRESSION is zero, the opposite happens. 2790*404b540aSrobert 2791*404b540aSrobert You can use `#else' with `#ifdef' and `#ifndef', too. 2792*404b540aSrobert 2793*404b540aSrobert 2794*404b540aSrobertFile: cpp.info, Node: Elif, Prev: Else, Up: Conditional Syntax 2795*404b540aSrobert 2796*404b540aSrobert4.2.5 Elif 2797*404b540aSrobert---------- 2798*404b540aSrobert 2799*404b540aSrobertOne common case of nested conditionals is used to check for more than 2800*404b540aSroberttwo possible alternatives. For example, you might have 2801*404b540aSrobert 2802*404b540aSrobert #if X == 1 2803*404b540aSrobert ... 2804*404b540aSrobert #else /* X != 1 */ 2805*404b540aSrobert #if X == 2 2806*404b540aSrobert ... 2807*404b540aSrobert #else /* X != 2 */ 2808*404b540aSrobert ... 2809*404b540aSrobert #endif /* X != 2 */ 2810*404b540aSrobert #endif /* X != 1 */ 2811*404b540aSrobert 2812*404b540aSrobert Another conditional directive, `#elif', allows this to be 2813*404b540aSrobertabbreviated as follows: 2814*404b540aSrobert 2815*404b540aSrobert #if X == 1 2816*404b540aSrobert ... 2817*404b540aSrobert #elif X == 2 2818*404b540aSrobert ... 2819*404b540aSrobert #else /* X != 2 and X != 1*/ 2820*404b540aSrobert ... 2821*404b540aSrobert #endif /* X != 2 and X != 1*/ 2822*404b540aSrobert 2823*404b540aSrobert `#elif' stands for "else if". Like `#else', it goes in the middle 2824*404b540aSrobertof a conditional group and subdivides it; it does not require a 2825*404b540aSrobertmatching `#endif' of its own. Like `#if', the `#elif' directive 2826*404b540aSrobertincludes an expression to be tested. The text following the `#elif' is 2827*404b540aSrobertprocessed only if the original `#if'-condition failed and the `#elif' 2828*404b540aSrobertcondition succeeds. 2829*404b540aSrobert 2830*404b540aSrobert More than one `#elif' can go in the same conditional group. Then 2831*404b540aSrobertthe text after each `#elif' is processed only if the `#elif' condition 2832*404b540aSrobertsucceeds after the original `#if' and all previous `#elif' directives 2833*404b540aSrobertwithin it have failed. 2834*404b540aSrobert 2835*404b540aSrobert `#else' is allowed after any number of `#elif' directives, but 2836*404b540aSrobert`#elif' may not follow `#else'. 2837*404b540aSrobert 2838*404b540aSrobert 2839*404b540aSrobertFile: cpp.info, Node: Deleted Code, Prev: Conditional Syntax, Up: Conditionals 2840*404b540aSrobert 2841*404b540aSrobert4.3 Deleted Code 2842*404b540aSrobert================ 2843*404b540aSrobert 2844*404b540aSrobertIf you replace or delete a part of the program but want to keep the old 2845*404b540aSrobertcode around for future reference, you often cannot simply comment it 2846*404b540aSrobertout. Block comments do not nest, so the first comment inside the old 2847*404b540aSrobertcode will end the commenting-out. The probable result is a flood of 2848*404b540aSrobertsyntax errors. 2849*404b540aSrobert 2850*404b540aSrobert One way to avoid this problem is to use an always-false conditional 2851*404b540aSrobertinstead. For instance, put `#if 0' before the deleted code and 2852*404b540aSrobert`#endif' after it. This works even if the code being turned off 2853*404b540aSrobertcontains conditionals, but they must be entire conditionals (balanced 2854*404b540aSrobert`#if' and `#endif'). 2855*404b540aSrobert 2856*404b540aSrobert Some people use `#ifdef notdef' instead. This is risky, because 2857*404b540aSrobert`notdef' might be accidentally defined as a macro, and then the 2858*404b540aSrobertconditional would succeed. `#if 0' can be counted on to fail. 2859*404b540aSrobert 2860*404b540aSrobert Do not use `#if 0' for comments which are not C code. Use a real 2861*404b540aSrobertcomment, instead. The interior of `#if 0' must consist of complete 2862*404b540aSroberttokens; in particular, single-quote characters must balance. Comments 2863*404b540aSrobertoften contain unbalanced single-quote characters (known in English as 2864*404b540aSrobertapostrophes). These confuse `#if 0'. They don't confuse `/*'. 2865*404b540aSrobert 2866*404b540aSrobert 2867*404b540aSrobertFile: cpp.info, Node: Diagnostics, Next: Line Control, Prev: Conditionals, Up: Top 2868*404b540aSrobert 2869*404b540aSrobert5 Diagnostics 2870*404b540aSrobert************* 2871*404b540aSrobert 2872*404b540aSrobertThe directive `#error' causes the preprocessor to report a fatal error. 2873*404b540aSrobertThe tokens forming the rest of the line following `#error' are used as 2874*404b540aSrobertthe error message. 2875*404b540aSrobert 2876*404b540aSrobert You would use `#error' inside of a conditional that detects a 2877*404b540aSrobertcombination of parameters which you know the program does not properly 2878*404b540aSrobertsupport. For example, if you know that the program will not run 2879*404b540aSrobertproperly on a VAX, you might write 2880*404b540aSrobert 2881*404b540aSrobert #ifdef __vax__ 2882*404b540aSrobert #error "Won't work on VAXen. See comments at get_last_object." 2883*404b540aSrobert #endif 2884*404b540aSrobert 2885*404b540aSrobert If you have several configuration parameters that must be set up by 2886*404b540aSrobertthe installation in a consistent way, you can use conditionals to detect 2887*404b540aSrobertan inconsistency and report it with `#error'. For example, 2888*404b540aSrobert 2889*404b540aSrobert #if !defined(UNALIGNED_INT_ASM_OP) && defined(DWARF2_DEBUGGING_INFO) 2890*404b540aSrobert #error "DWARF2_DEBUGGING_INFO requires UNALIGNED_INT_ASM_OP." 2891*404b540aSrobert #endif 2892*404b540aSrobert 2893*404b540aSrobert The directive `#warning' is like `#error', but causes the 2894*404b540aSrobertpreprocessor to issue a warning and continue preprocessing. The tokens 2895*404b540aSrobertfollowing `#warning' are used as the warning message. 2896*404b540aSrobert 2897*404b540aSrobert You might use `#warning' in obsolete header files, with a message 2898*404b540aSrobertdirecting the user to the header file which should be used instead. 2899*404b540aSrobert 2900*404b540aSrobert Neither `#error' nor `#warning' macro-expands its argument. 2901*404b540aSrobertInternal whitespace sequences are each replaced with a single space. 2902*404b540aSrobertThe line must consist of complete tokens. It is wisest to make the 2903*404b540aSrobertargument of these directives be a single string constant; this avoids 2904*404b540aSrobertproblems with apostrophes and the like. 2905*404b540aSrobert 2906*404b540aSrobert 2907*404b540aSrobertFile: cpp.info, Node: Line Control, Next: Pragmas, Prev: Diagnostics, Up: Top 2908*404b540aSrobert 2909*404b540aSrobert6 Line Control 2910*404b540aSrobert************** 2911*404b540aSrobert 2912*404b540aSrobertThe C preprocessor informs the C compiler of the location in your source 2913*404b540aSrobertcode where each token came from. Presently, this is just the file name 2914*404b540aSrobertand line number. All the tokens resulting from macro expansion are 2915*404b540aSrobertreported as having appeared on the line of the source file where the 2916*404b540aSrobertoutermost macro was used. We intend to be more accurate in the future. 2917*404b540aSrobert 2918*404b540aSrobert If you write a program which generates source code, such as the 2919*404b540aSrobert`bison' parser generator, you may want to adjust the preprocessor's 2920*404b540aSrobertnotion of the current file name and line number by hand. Parts of the 2921*404b540aSrobertoutput from `bison' are generated from scratch, other parts come from a 2922*404b540aSrobertstandard parser file. The rest are copied verbatim from `bison''s 2923*404b540aSrobertinput. You would like compiler error messages and symbolic debuggers 2924*404b540aSrobertto be able to refer to `bison''s input file. 2925*404b540aSrobert 2926*404b540aSrobert `bison' or any such program can arrange this by writing `#line' 2927*404b540aSrobertdirectives into the output file. `#line' is a directive that specifies 2928*404b540aSrobertthe original line number and source file name for subsequent input in 2929*404b540aSrobertthe current preprocessor input file. `#line' has three variants: 2930*404b540aSrobert 2931*404b540aSrobert`#line LINENUM' 2932*404b540aSrobert LINENUM is a non-negative decimal integer constant. It specifies 2933*404b540aSrobert the line number which should be reported for the following line of 2934*404b540aSrobert input. Subsequent lines are counted from LINENUM. 2935*404b540aSrobert 2936*404b540aSrobert`#line LINENUM FILENAME' 2937*404b540aSrobert LINENUM is the same as for the first form, and has the same 2938*404b540aSrobert effect. In addition, FILENAME is a string constant. The 2939*404b540aSrobert following line and all subsequent lines are reported to come from 2940*404b540aSrobert the file it specifies, until something else happens to change that. 2941*404b540aSrobert FILENAME is interpreted according to the normal rules for a string 2942*404b540aSrobert constant: backslash escapes are interpreted. This is different 2943*404b540aSrobert from `#include'. 2944*404b540aSrobert 2945*404b540aSrobert Previous versions of CPP did not interpret escapes in `#line'; we 2946*404b540aSrobert have changed it because the standard requires they be interpreted, 2947*404b540aSrobert and most other compilers do. 2948*404b540aSrobert 2949*404b540aSrobert`#line ANYTHING ELSE' 2950*404b540aSrobert ANYTHING ELSE is checked for macro calls, which are expanded. The 2951*404b540aSrobert result should match one of the above two forms. 2952*404b540aSrobert 2953*404b540aSrobert `#line' directives alter the results of the `__FILE__' and 2954*404b540aSrobert`__LINE__' predefined macros from that point on. *Note Standard 2955*404b540aSrobertPredefined Macros::. They do not have any effect on `#include''s idea 2956*404b540aSrobertof the directory containing the current file. This is a change from 2957*404b540aSrobertGCC 2.95. Previously, a file reading 2958*404b540aSrobert 2959*404b540aSrobert #line 1 "../src/gram.y" 2960*404b540aSrobert #include "gram.h" 2961*404b540aSrobert 2962*404b540aSrobert would search for `gram.h' in `../src', then the `-I' chain; the 2963*404b540aSrobertdirectory containing the physical source file would not be searched. 2964*404b540aSrobertIn GCC 3.0 and later, the `#include' is not affected by the presence of 2965*404b540aSroberta `#line' referring to a different directory. 2966*404b540aSrobert 2967*404b540aSrobert We made this change because the old behavior caused problems when 2968*404b540aSrobertgenerated source files were transported between machines. For instance, 2969*404b540aSrobertit is common practice to ship generated parsers with a source release, 2970*404b540aSrobertso that people building the distribution do not need to have yacc or 2971*404b540aSrobertBison installed. These files frequently have `#line' directives 2972*404b540aSrobertreferring to the directory tree of the system where the distribution was 2973*404b540aSrobertcreated. If GCC tries to search for headers in those directories, the 2974*404b540aSrobertbuild is likely to fail. 2975*404b540aSrobert 2976*404b540aSrobert The new behavior can cause failures too, if the generated file is not 2977*404b540aSrobertin the same directory as its source and it attempts to include a header 2978*404b540aSrobertwhich would be visible searching from the directory containing the 2979*404b540aSrobertsource file. However, this problem is easily solved with an additional 2980*404b540aSrobert`-I' switch on the command line. The failures caused by the old 2981*404b540aSrobertsemantics could sometimes be corrected only by editing the generated 2982*404b540aSrobertfiles, which is difficult and error-prone. 2983*404b540aSrobert 2984*404b540aSrobert 2985*404b540aSrobertFile: cpp.info, Node: Pragmas, Next: Other Directives, Prev: Line Control, Up: Top 2986*404b540aSrobert 2987*404b540aSrobert7 Pragmas 2988*404b540aSrobert********* 2989*404b540aSrobert 2990*404b540aSrobertThe `#pragma' directive is the method specified by the C standard for 2991*404b540aSrobertproviding additional information to the compiler, beyond what is 2992*404b540aSrobertconveyed in the language itself. Three forms of this directive 2993*404b540aSrobert(commonly known as "pragmas") are specified by the 1999 C standard. A 2994*404b540aSrobertC compiler is free to attach any meaning it likes to other pragmas. 2995*404b540aSrobert 2996*404b540aSrobert GCC has historically preferred to use extensions to the syntax of the 2997*404b540aSrobertlanguage, such as `__attribute__', for this purpose. However, GCC does 2998*404b540aSrobertdefine a few pragmas of its own. These mostly have effects on the 2999*404b540aSrobertentire translation unit or source file. 3000*404b540aSrobert 3001*404b540aSrobert In GCC version 3, all GNU-defined, supported pragmas have been given 3002*404b540aSroberta `GCC' prefix. This is in line with the `STDC' prefix on all pragmas 3003*404b540aSrobertdefined by C99. For backward compatibility, pragmas which were 3004*404b540aSrobertrecognized by previous versions are still recognized without the `GCC' 3005*404b540aSrobertprefix, but that usage is deprecated. Some older pragmas are 3006*404b540aSrobertdeprecated in their entirety. They are not recognized with the `GCC' 3007*404b540aSrobertprefix. *Note Obsolete Features::. 3008*404b540aSrobert 3009*404b540aSrobert C99 introduces the `_Pragma' operator. This feature addresses a 3010*404b540aSrobertmajor problem with `#pragma': being a directive, it cannot be produced 3011*404b540aSrobertas the result of macro expansion. `_Pragma' is an operator, much like 3012*404b540aSrobert`sizeof' or `defined', and can be embedded in a macro. 3013*404b540aSrobert 3014*404b540aSrobert Its syntax is `_Pragma (STRING-LITERAL)', where STRING-LITERAL can 3015*404b540aSrobertbe either a normal or wide-character string literal. It is 3016*404b540aSrobertdestringized, by replacing all `\\' with a single `\' and all `\"' with 3017*404b540aSroberta `"'. The result is then processed as if it had appeared as the right 3018*404b540aSroberthand side of a `#pragma' directive. For example, 3019*404b540aSrobert 3020*404b540aSrobert _Pragma ("GCC dependency \"parse.y\"") 3021*404b540aSrobert 3022*404b540aSroberthas the same effect as `#pragma GCC dependency "parse.y"'. The same 3023*404b540aSroberteffect could be achieved using macros, for example 3024*404b540aSrobert 3025*404b540aSrobert #define DO_PRAGMA(x) _Pragma (#x) 3026*404b540aSrobert DO_PRAGMA (GCC dependency "parse.y") 3027*404b540aSrobert 3028*404b540aSrobert The standard is unclear on where a `_Pragma' operator can appear. 3029*404b540aSrobertThe preprocessor does not accept it within a preprocessing conditional 3030*404b540aSrobertdirective like `#if'. To be safe, you are probably best keeping it out 3031*404b540aSrobertof directives other than `#define', and putting it on a line of its own. 3032*404b540aSrobert 3033*404b540aSrobert This manual documents the pragmas which are meaningful to the 3034*404b540aSrobertpreprocessor itself. Other pragmas are meaningful to the C or C++ 3035*404b540aSrobertcompilers. They are documented in the GCC manual. 3036*404b540aSrobert 3037*404b540aSrobert`#pragma GCC dependency' 3038*404b540aSrobert `#pragma GCC dependency' allows you to check the relative dates of 3039*404b540aSrobert the current file and another file. If the other file is more 3040*404b540aSrobert recent than the current file, a warning is issued. This is useful 3041*404b540aSrobert if the current file is derived from the other file, and should be 3042*404b540aSrobert regenerated. The other file is searched for using the normal 3043*404b540aSrobert include search path. Optional trailing text can be used to give 3044*404b540aSrobert more information in the warning message. 3045*404b540aSrobert 3046*404b540aSrobert #pragma GCC dependency "parse.y" 3047*404b540aSrobert #pragma GCC dependency "/usr/include/time.h" rerun fixincludes 3048*404b540aSrobert 3049*404b540aSrobert`#pragma GCC poison' 3050*404b540aSrobert Sometimes, there is an identifier that you want to remove 3051*404b540aSrobert completely from your program, and make sure that it never creeps 3052*404b540aSrobert back in. To enforce this, you can "poison" the identifier with 3053*404b540aSrobert this pragma. `#pragma GCC poison' is followed by a list of 3054*404b540aSrobert identifiers to poison. If any of those identifiers appears 3055*404b540aSrobert anywhere in the source after the directive, it is a hard error. 3056*404b540aSrobert For example, 3057*404b540aSrobert 3058*404b540aSrobert #pragma GCC poison printf sprintf fprintf 3059*404b540aSrobert sprintf(some_string, "hello"); 3060*404b540aSrobert 3061*404b540aSrobert will produce an error. 3062*404b540aSrobert 3063*404b540aSrobert If a poisoned identifier appears as part of the expansion of a 3064*404b540aSrobert macro which was defined before the identifier was poisoned, it 3065*404b540aSrobert will _not_ cause an error. This lets you poison an identifier 3066*404b540aSrobert without worrying about system headers defining macros that use it. 3067*404b540aSrobert 3068*404b540aSrobert For example, 3069*404b540aSrobert 3070*404b540aSrobert #define strrchr rindex 3071*404b540aSrobert #pragma GCC poison rindex 3072*404b540aSrobert strrchr(some_string, 'h'); 3073*404b540aSrobert 3074*404b540aSrobert will not produce an error. 3075*404b540aSrobert 3076*404b540aSrobert`#pragma GCC system_header' 3077*404b540aSrobert This pragma takes no arguments. It causes the rest of the code in 3078*404b540aSrobert the current file to be treated as if it came from a system header. 3079*404b540aSrobert *Note System Headers::. 3080*404b540aSrobert 3081*404b540aSrobert 3082*404b540aSrobert 3083*404b540aSrobertFile: cpp.info, Node: Other Directives, Next: Preprocessor Output, Prev: Pragmas, Up: Top 3084*404b540aSrobert 3085*404b540aSrobert8 Other Directives 3086*404b540aSrobert****************** 3087*404b540aSrobert 3088*404b540aSrobertThe `#ident' directive takes one argument, a string constant. On some 3089*404b540aSrobertsystems, that string constant is copied into a special segment of the 3090*404b540aSrobertobject file. On other systems, the directive is ignored. The `#sccs' 3091*404b540aSrobertdirective is a synonym for `#ident'. 3092*404b540aSrobert 3093*404b540aSrobert These directives are not part of the C standard, but they are not 3094*404b540aSrobertofficial GNU extensions either. What historical information we have 3095*404b540aSrobertbeen able to find, suggests they originated with System V. 3096*404b540aSrobert 3097*404b540aSrobert The "null directive" consists of a `#' followed by a newline, with 3098*404b540aSrobertonly whitespace (including comments) in between. A null directive is 3099*404b540aSrobertunderstood as a preprocessing directive but has no effect on the 3100*404b540aSrobertpreprocessor output. The primary significance of the existence of the 3101*404b540aSrobertnull directive is that an input line consisting of just a `#' will 3102*404b540aSrobertproduce no output, rather than a line of output containing just a `#'. 3103*404b540aSrobertSupposedly some old C programs contain such lines. 3104*404b540aSrobert 3105*404b540aSrobert 3106*404b540aSrobertFile: cpp.info, Node: Preprocessor Output, Next: Traditional Mode, Prev: Other Directives, Up: Top 3107*404b540aSrobert 3108*404b540aSrobert9 Preprocessor Output 3109*404b540aSrobert********************* 3110*404b540aSrobert 3111*404b540aSrobertWhen the C preprocessor is used with the C, C++, or Objective-C 3112*404b540aSrobertcompilers, it is integrated into the compiler and communicates a stream 3113*404b540aSrobertof binary tokens directly to the compiler's parser. However, it can 3114*404b540aSrobertalso be used in the more conventional standalone mode, where it produces 3115*404b540aSroberttextual output. 3116*404b540aSrobert 3117*404b540aSrobert The output from the C preprocessor looks much like the input, except 3118*404b540aSrobertthat all preprocessing directive lines have been replaced with blank 3119*404b540aSrobertlines and all comments with spaces. Long runs of blank lines are 3120*404b540aSrobertdiscarded. 3121*404b540aSrobert 3122*404b540aSrobert The ISO standard specifies that it is implementation defined whether 3123*404b540aSroberta preprocessor preserves whitespace between tokens, or replaces it with 3124*404b540aSroberte.g. a single space. In GNU CPP, whitespace between tokens is collapsed 3125*404b540aSrobertto become a single space, with the exception that the first token on a 3126*404b540aSrobertnon-directive line is preceded with sufficient spaces that it appears in 3127*404b540aSrobertthe same column in the preprocessed output that it appeared in the 3128*404b540aSrobertoriginal source file. This is so the output is easy to read. *Note 3129*404b540aSrobertDifferences from previous versions::. CPP does not insert any 3130*404b540aSrobertwhitespace where there was none in the original source, except where 3131*404b540aSrobertnecessary to prevent an accidental token paste. 3132*404b540aSrobert 3133*404b540aSrobert Source file name and line number information is conveyed by lines of 3134*404b540aSrobertthe form 3135*404b540aSrobert 3136*404b540aSrobert # LINENUM FILENAME FLAGS 3137*404b540aSrobert 3138*404b540aSrobertThese are called "linemarkers". They are inserted as needed into the 3139*404b540aSrobertoutput (but never within a string or character constant). They mean 3140*404b540aSrobertthat the following line originated in file FILENAME at line LINENUM. 3141*404b540aSrobertFILENAME will never contain any non-printing characters; they are 3142*404b540aSrobertreplaced with octal escape sequences. 3143*404b540aSrobert 3144*404b540aSrobert After the file name comes zero or more flags, which are `1', `2', 3145*404b540aSrobert`3', or `4'. If there are multiple flags, spaces separate them. Here 3146*404b540aSrobertis what the flags mean: 3147*404b540aSrobert 3148*404b540aSrobert`1' 3149*404b540aSrobert This indicates the start of a new file. 3150*404b540aSrobert 3151*404b540aSrobert`2' 3152*404b540aSrobert This indicates returning to a file (after having included another 3153*404b540aSrobert file). 3154*404b540aSrobert 3155*404b540aSrobert`3' 3156*404b540aSrobert This indicates that the following text comes from a system header 3157*404b540aSrobert file, so certain warnings should be suppressed. 3158*404b540aSrobert 3159*404b540aSrobert`4' 3160*404b540aSrobert This indicates that the following text should be treated as being 3161*404b540aSrobert wrapped in an implicit `extern "C"' block. 3162*404b540aSrobert 3163*404b540aSrobert As an extension, the preprocessor accepts linemarkers in 3164*404b540aSrobertnon-assembler input files. They are treated like the corresponding 3165*404b540aSrobert`#line' directive, (*note Line Control::), except that trailing flags 3166*404b540aSrobertare permitted, and are interpreted with the meanings described above. 3167*404b540aSrobertIf multiple flags are given, they must be in ascending order. 3168*404b540aSrobert 3169*404b540aSrobert Some directives may be duplicated in the output of the preprocessor. 3170*404b540aSrobertThese are `#ident' (always), `#pragma' (only if the preprocessor does 3171*404b540aSrobertnot handle the pragma itself), and `#define' and `#undef' (with certain 3172*404b540aSrobertdebugging options). If this happens, the `#' of the directive will 3173*404b540aSrobertalways be in the first column, and there will be no space between the 3174*404b540aSrobert`#' and the directive name. If macro expansion happens to generate 3175*404b540aSroberttokens which might be mistaken for a duplicated directive, a space will 3176*404b540aSrobertbe inserted between the `#' and the directive name. 3177*404b540aSrobert 3178*404b540aSrobert 3179*404b540aSrobertFile: cpp.info, Node: Traditional Mode, Next: Implementation Details, Prev: Preprocessor Output, Up: Top 3180*404b540aSrobert 3181*404b540aSrobert10 Traditional Mode 3182*404b540aSrobert******************* 3183*404b540aSrobert 3184*404b540aSrobertTraditional (pre-standard) C preprocessing is rather different from the 3185*404b540aSrobertpreprocessing specified by the standard. When GCC is given the 3186*404b540aSrobert`-traditional-cpp' option, it attempts to emulate a traditional 3187*404b540aSrobertpreprocessor. 3188*404b540aSrobert 3189*404b540aSrobert GCC versions 3.2 and later only support traditional mode semantics in 3190*404b540aSrobertthe preprocessor, and not in the compiler front ends. This chapter 3191*404b540aSrobertoutlines the traditional preprocessor semantics we implemented. 3192*404b540aSrobert 3193*404b540aSrobert The implementation does not correspond precisely to the behavior of 3194*404b540aSrobertearlier versions of GCC, nor to any true traditional preprocessor. 3195*404b540aSrobertAfter all, inconsistencies among traditional implementations were a 3196*404b540aSrobertmajor motivation for C standardization. However, we intend that it 3197*404b540aSrobertshould be compatible with true traditional preprocessors in all ways 3198*404b540aSrobertthat actually matter. 3199*404b540aSrobert 3200*404b540aSrobert* Menu: 3201*404b540aSrobert 3202*404b540aSrobert* Traditional lexical analysis:: 3203*404b540aSrobert* Traditional macros:: 3204*404b540aSrobert* Traditional miscellany:: 3205*404b540aSrobert* Traditional warnings:: 3206*404b540aSrobert 3207*404b540aSrobert 3208*404b540aSrobertFile: cpp.info, Node: Traditional lexical analysis, Next: Traditional macros, Up: Traditional Mode 3209*404b540aSrobert 3210*404b540aSrobert10.1 Traditional lexical analysis 3211*404b540aSrobert================================= 3212*404b540aSrobert 3213*404b540aSrobertThe traditional preprocessor does not decompose its input into tokens 3214*404b540aSrobertthe same way a standards-conforming preprocessor does. The input is 3215*404b540aSrobertsimply treated as a stream of text with minimal internal form. 3216*404b540aSrobert 3217*404b540aSrobert This implementation does not treat trigraphs (*note trigraphs::) 3218*404b540aSrobertspecially since they were an invention of the standards committee. It 3219*404b540aSroberthandles arbitrarily-positioned escaped newlines properly and splices 3220*404b540aSrobertthe lines as you would expect; many traditional preprocessors did not 3221*404b540aSrobertdo this. 3222*404b540aSrobert 3223*404b540aSrobert The form of horizontal whitespace in the input file is preserved in 3224*404b540aSrobertthe output. In particular, hard tabs remain hard tabs. This can be 3225*404b540aSrobertuseful if, for example, you are preprocessing a Makefile. 3226*404b540aSrobert 3227*404b540aSrobert Traditional CPP only recognizes C-style block comments, and treats 3228*404b540aSrobertthe `/*' sequence as introducing a comment only if it lies outside 3229*404b540aSrobertquoted text. Quoted text is introduced by the usual single and double 3230*404b540aSrobertquotes, and also by an initial `<' in a `#include' directive. 3231*404b540aSrobert 3232*404b540aSrobert Traditionally, comments are completely removed and are not replaced 3233*404b540aSrobertwith a space. Since a traditional compiler does its own tokenization 3234*404b540aSrobertof the output of the preprocessor, this means that comments can 3235*404b540aSroberteffectively be used as token paste operators. However, comments behave 3236*404b540aSrobertlike separators for text handled by the preprocessor itself, since it 3237*404b540aSrobertdoesn't re-lex its input. For example, in 3238*404b540aSrobert 3239*404b540aSrobert #if foo/**/bar 3240*404b540aSrobert 3241*404b540aSrobert`foo' and `bar' are distinct identifiers and expanded separately if 3242*404b540aSrobertthey happen to be macros. In other words, this directive is equivalent 3243*404b540aSrobertto 3244*404b540aSrobert 3245*404b540aSrobert #if foo bar 3246*404b540aSrobert 3247*404b540aSrobertrather than 3248*404b540aSrobert 3249*404b540aSrobert #if foobar 3250*404b540aSrobert 3251*404b540aSrobert Generally speaking, in traditional mode an opening quote need not 3252*404b540aSroberthave a matching closing quote. In particular, a macro may be defined 3253*404b540aSrobertwith replacement text that contains an unmatched quote. Of course, if 3254*404b540aSrobertyou attempt to compile preprocessed output containing an unmatched quote 3255*404b540aSrobertyou will get a syntax error. 3256*404b540aSrobert 3257*404b540aSrobert However, all preprocessing directives other than `#define' require 3258*404b540aSrobertmatching quotes. For example: 3259*404b540aSrobert 3260*404b540aSrobert #define m This macro's fine and has an unmatched quote 3261*404b540aSrobert "/* This is not a comment. */ 3262*404b540aSrobert /* This is a comment. The following #include directive 3263*404b540aSrobert is ill-formed. */ 3264*404b540aSrobert #include <stdio.h 3265*404b540aSrobert 3266*404b540aSrobert Just as for the ISO preprocessor, what would be a closing quote can 3267*404b540aSrobertbe escaped with a backslash to prevent the quoted text from closing. 3268*404b540aSrobert 3269*404b540aSrobert 3270*404b540aSrobertFile: cpp.info, Node: Traditional macros, Next: Traditional miscellany, Prev: Traditional lexical analysis, Up: Traditional Mode 3271*404b540aSrobert 3272*404b540aSrobert10.2 Traditional macros 3273*404b540aSrobert======================= 3274*404b540aSrobert 3275*404b540aSrobertThe major difference between traditional and ISO macros is that the 3276*404b540aSrobertformer expand to text rather than to a token sequence. CPP removes all 3277*404b540aSrobertleading and trailing horizontal whitespace from a macro's replacement 3278*404b540aSroberttext before storing it, but preserves the form of internal whitespace. 3279*404b540aSrobert 3280*404b540aSrobert One consequence is that it is legitimate for the replacement text to 3281*404b540aSrobertcontain an unmatched quote (*note Traditional lexical analysis::). An 3282*404b540aSrobertunclosed string or character constant continues into the text following 3283*404b540aSrobertthe macro call. Similarly, the text at the end of a macro's expansion 3284*404b540aSrobertcan run together with the text after the macro invocation to produce a 3285*404b540aSrobertsingle token. 3286*404b540aSrobert 3287*404b540aSrobert Normally comments are removed from the replacement text after the 3288*404b540aSrobertmacro is expanded, but if the `-CC' option is passed on the command 3289*404b540aSrobertline comments are preserved. (In fact, the current implementation 3290*404b540aSrobertremoves comments even before saving the macro replacement text, but it 3291*404b540aSrobertcareful to do it in such a way that the observed effect is identical 3292*404b540aSroberteven in the function-like macro case.) 3293*404b540aSrobert 3294*404b540aSrobert The ISO stringification operator `#' and token paste operator `##' 3295*404b540aSroberthave no special meaning. As explained later, an effect similar to 3296*404b540aSrobertthese operators can be obtained in a different way. Macro names that 3297*404b540aSrobertare embedded in quotes, either from the main file or after macro 3298*404b540aSrobertreplacement, do not expand. 3299*404b540aSrobert 3300*404b540aSrobert CPP replaces an unquoted object-like macro name with its replacement 3301*404b540aSroberttext, and then rescans it for further macros to replace. Unlike 3302*404b540aSrobertstandard macro expansion, traditional macro expansion has no provision 3303*404b540aSrobertto prevent recursion. If an object-like macro appears unquoted in its 3304*404b540aSrobertreplacement text, it will be replaced again during the rescan pass, and 3305*404b540aSrobertso on _ad infinitum_. GCC detects when it is expanding recursive 3306*404b540aSrobertmacros, emits an error message, and continues after the offending macro 3307*404b540aSrobertinvocation. 3308*404b540aSrobert 3309*404b540aSrobert #define PLUS + 3310*404b540aSrobert #define INC(x) PLUS+x 3311*404b540aSrobert INC(foo); 3312*404b540aSrobert ==> ++foo; 3313*404b540aSrobert 3314*404b540aSrobert Function-like macros are similar in form but quite different in 3315*404b540aSrobertbehavior to their ISO counterparts. Their arguments are contained 3316*404b540aSrobertwithin parentheses, are comma-separated, and can cross physical lines. 3317*404b540aSrobertCommas within nested parentheses are not treated as argument 3318*404b540aSrobertseparators. Similarly, a quote in an argument cannot be left unclosed; 3319*404b540aSroberta following comma or parenthesis that comes before the closing quote is 3320*404b540aSroberttreated like any other character. There is no facility for handling 3321*404b540aSrobertvariadic macros. 3322*404b540aSrobert 3323*404b540aSrobert This implementation removes all comments from macro arguments, unless 3324*404b540aSrobertthe `-C' option is given. The form of all other horizontal whitespace 3325*404b540aSrobertin arguments is preserved, including leading and trailing whitespace. 3326*404b540aSrobertIn particular 3327*404b540aSrobert 3328*404b540aSrobert f( ) 3329*404b540aSrobert 3330*404b540aSrobertis treated as an invocation of the macro `f' with a single argument 3331*404b540aSrobertconsisting of a single space. If you want to invoke a function-like 3332*404b540aSrobertmacro that takes no arguments, you must not leave any whitespace 3333*404b540aSrobertbetween the parentheses. 3334*404b540aSrobert 3335*404b540aSrobert If a macro argument crosses a new line, the new line is replaced with 3336*404b540aSroberta space when forming the argument. If the previous line contained an 3337*404b540aSrobertunterminated quote, the following line inherits the quoted state. 3338*404b540aSrobert 3339*404b540aSrobert Traditional preprocessors replace parameters in the replacement text 3340*404b540aSrobertwith their arguments regardless of whether the parameters are within 3341*404b540aSrobertquotes or not. This provides a way to stringize arguments. For example 3342*404b540aSrobert 3343*404b540aSrobert #define str(x) "x" 3344*404b540aSrobert str(/* A comment */some text ) 3345*404b540aSrobert ==> "some text " 3346*404b540aSrobert 3347*404b540aSrobertNote that the comment is removed, but that the trailing space is 3348*404b540aSrobertpreserved. Here is an example of using a comment to effect token 3349*404b540aSrobertpasting. 3350*404b540aSrobert 3351*404b540aSrobert #define suffix(x) foo_/**/x 3352*404b540aSrobert suffix(bar) 3353*404b540aSrobert ==> foo_bar 3354*404b540aSrobert 3355*404b540aSrobert 3356*404b540aSrobertFile: cpp.info, Node: Traditional miscellany, Next: Traditional warnings, Prev: Traditional macros, Up: Traditional Mode 3357*404b540aSrobert 3358*404b540aSrobert10.3 Traditional miscellany 3359*404b540aSrobert=========================== 3360*404b540aSrobert 3361*404b540aSrobertHere are some things to be aware of when using the traditional 3362*404b540aSrobertpreprocessor. 3363*404b540aSrobert 3364*404b540aSrobert * Preprocessing directives are recognized only when their leading 3365*404b540aSrobert `#' appears in the first column. There can be no whitespace 3366*404b540aSrobert between the beginning of the line and the `#', but whitespace can 3367*404b540aSrobert follow the `#'. 3368*404b540aSrobert 3369*404b540aSrobert * A true traditional C preprocessor does not recognize `#error' or 3370*404b540aSrobert `#pragma', and may not recognize `#elif'. CPP supports all the 3371*404b540aSrobert directives in traditional mode that it supports in ISO mode, 3372*404b540aSrobert including extensions, with the exception that the effects of 3373*404b540aSrobert `#pragma GCC poison' are undefined. 3374*404b540aSrobert 3375*404b540aSrobert * __STDC__ is not defined. 3376*404b540aSrobert 3377*404b540aSrobert * If you use digraphs the behavior is undefined. 3378*404b540aSrobert 3379*404b540aSrobert * If a line that looks like a directive appears within macro 3380*404b540aSrobert arguments, the behavior is undefined. 3381*404b540aSrobert 3382*404b540aSrobert 3383*404b540aSrobert 3384*404b540aSrobertFile: cpp.info, Node: Traditional warnings, Prev: Traditional miscellany, Up: Traditional Mode 3385*404b540aSrobert 3386*404b540aSrobert10.4 Traditional warnings 3387*404b540aSrobert========================= 3388*404b540aSrobert 3389*404b540aSrobertYou can request warnings about features that did not exist, or worked 3390*404b540aSrobertdifferently, in traditional C with the `-Wtraditional' option. GCC 3391*404b540aSrobertdoes not warn about features of ISO C which you must use when you are 3392*404b540aSrobertusing a conforming compiler, such as the `#' and `##' operators. 3393*404b540aSrobert 3394*404b540aSrobert Presently `-Wtraditional' warns about: 3395*404b540aSrobert 3396*404b540aSrobert * Macro parameters that appear within string literals in the macro 3397*404b540aSrobert body. In traditional C macro replacement takes place within 3398*404b540aSrobert string literals, but does not in ISO C. 3399*404b540aSrobert 3400*404b540aSrobert * In traditional C, some preprocessor directives did not exist. 3401*404b540aSrobert Traditional preprocessors would only consider a line to be a 3402*404b540aSrobert directive if the `#' appeared in column 1 on the line. Therefore 3403*404b540aSrobert `-Wtraditional' warns about directives that traditional C 3404*404b540aSrobert understands but would ignore because the `#' does not appear as the 3405*404b540aSrobert first character on the line. It also suggests you hide directives 3406*404b540aSrobert like `#pragma' not understood by traditional C by indenting them. 3407*404b540aSrobert Some traditional implementations would not recognize `#elif', so it 3408*404b540aSrobert suggests avoiding it altogether. 3409*404b540aSrobert 3410*404b540aSrobert * A function-like macro that appears without an argument list. In 3411*404b540aSrobert some traditional preprocessors this was an error. In ISO C it 3412*404b540aSrobert merely means that the macro is not expanded. 3413*404b540aSrobert 3414*404b540aSrobert * The unary plus operator. This did not exist in traditional C. 3415*404b540aSrobert 3416*404b540aSrobert * The `U' and `LL' integer constant suffixes, which were not 3417*404b540aSrobert available in traditional C. (Traditional C does support the `L' 3418*404b540aSrobert suffix for simple long integer constants.) You are not warned 3419*404b540aSrobert about uses of these suffixes in macros defined in system headers. 3420*404b540aSrobert For instance, `UINT_MAX' may well be defined as `4294967295U', but 3421*404b540aSrobert you will not be warned if you use `UINT_MAX'. 3422*404b540aSrobert 3423*404b540aSrobert You can usually avoid the warning, and the related warning about 3424*404b540aSrobert constants which are so large that they are unsigned, by writing the 3425*404b540aSrobert integer constant in question in hexadecimal, with no U suffix. 3426*404b540aSrobert Take care, though, because this gives the wrong result in exotic 3427*404b540aSrobert cases. 3428*404b540aSrobert 3429*404b540aSrobert 3430*404b540aSrobertFile: cpp.info, Node: Implementation Details, Next: Invocation, Prev: Traditional Mode, Up: Top 3431*404b540aSrobert 3432*404b540aSrobert11 Implementation Details 3433*404b540aSrobert************************* 3434*404b540aSrobert 3435*404b540aSrobertHere we document details of how the preprocessor's implementation 3436*404b540aSrobertaffects its user-visible behavior. You should try to avoid undue 3437*404b540aSrobertreliance on behavior described here, as it is possible that it will 3438*404b540aSrobertchange subtly in future implementations. 3439*404b540aSrobert 3440*404b540aSrobert Also documented here are obsolete features and changes from previous 3441*404b540aSrobertversions of CPP. 3442*404b540aSrobert 3443*404b540aSrobert* Menu: 3444*404b540aSrobert 3445*404b540aSrobert* Implementation-defined behavior:: 3446*404b540aSrobert* Implementation limits:: 3447*404b540aSrobert* Obsolete Features:: 3448*404b540aSrobert* Differences from previous versions:: 3449*404b540aSrobert 3450*404b540aSrobert 3451*404b540aSrobertFile: cpp.info, Node: Implementation-defined behavior, Next: Implementation limits, Up: Implementation Details 3452*404b540aSrobert 3453*404b540aSrobert11.1 Implementation-defined behavior 3454*404b540aSrobert==================================== 3455*404b540aSrobert 3456*404b540aSrobertThis is how CPP behaves in all the cases which the C standard describes 3457*404b540aSrobertas "implementation-defined". This term means that the implementation 3458*404b540aSrobertis free to do what it likes, but must document its choice and stick to 3459*404b540aSrobertit. 3460*404b540aSrobert 3461*404b540aSrobert * The mapping of physical source file multi-byte characters to the 3462*404b540aSrobert execution character set. 3463*404b540aSrobert 3464*404b540aSrobert Currently, CPP requires its input to be ASCII or UTF-8. The 3465*404b540aSrobert execution character set may be controlled by the user, with the 3466*404b540aSrobert `-fexec-charset' and `-fwide-exec-charset' options. 3467*404b540aSrobert 3468*404b540aSrobert * Identifier characters. 3469*404b540aSrobert 3470*404b540aSrobert The C and C++ standards allow identifiers to be composed of `_' 3471*404b540aSrobert and the alphanumeric characters. C++ and C99 also allow universal 3472*404b540aSrobert character names, and C99 further permits implementation-defined 3473*404b540aSrobert characters. GCC currently only permits universal character names 3474*404b540aSrobert if `-fextended-identifiers' is used, because the implementation of 3475*404b540aSrobert universal character names in identifiers is experimental. 3476*404b540aSrobert 3477*404b540aSrobert GCC allows the `$' character in identifiers as an extension for 3478*404b540aSrobert most targets. This is true regardless of the `std=' switch, since 3479*404b540aSrobert this extension cannot conflict with standards-conforming programs. 3480*404b540aSrobert When preprocessing assembler, however, dollars are not identifier 3481*404b540aSrobert characters by default. 3482*404b540aSrobert 3483*404b540aSrobert Currently the targets that by default do not permit `$' are AVR, 3484*404b540aSrobert IP2K, MMIX, MIPS Irix 3, ARM aout, and PowerPC targets for the AIX 3485*404b540aSrobert and BeOS operating systems. 3486*404b540aSrobert 3487*404b540aSrobert You can override the default with `-fdollars-in-identifiers' or 3488*404b540aSrobert `fno-dollars-in-identifiers'. *Note fdollars-in-identifiers::. 3489*404b540aSrobert 3490*404b540aSrobert * Non-empty sequences of whitespace characters. 3491*404b540aSrobert 3492*404b540aSrobert In textual output, each whitespace sequence is collapsed to a 3493*404b540aSrobert single space. For aesthetic reasons, the first token on each 3494*404b540aSrobert non-directive line of output is preceded with sufficient spaces 3495*404b540aSrobert that it appears in the same column as it did in the original 3496*404b540aSrobert source file. 3497*404b540aSrobert 3498*404b540aSrobert * The numeric value of character constants in preprocessor 3499*404b540aSrobert expressions. 3500*404b540aSrobert 3501*404b540aSrobert The preprocessor and compiler interpret character constants in the 3502*404b540aSrobert same way; i.e. escape sequences such as `\a' are given the values 3503*404b540aSrobert they would have on the target machine. 3504*404b540aSrobert 3505*404b540aSrobert The compiler values a multi-character character constant a 3506*404b540aSrobert character at a time, shifting the previous value left by the 3507*404b540aSrobert number of bits per target character, and then or-ing in the 3508*404b540aSrobert bit-pattern of the new character truncated to the width of a 3509*404b540aSrobert target character. The final bit-pattern is given type `int', and 3510*404b540aSrobert is therefore signed, regardless of whether single characters are 3511*404b540aSrobert signed or not (a slight change from versions 3.1 and earlier of 3512*404b540aSrobert GCC). If there are more characters in the constant than would fit 3513*404b540aSrobert in the target `int' the compiler issues a warning, and the excess 3514*404b540aSrobert leading characters are ignored. 3515*404b540aSrobert 3516*404b540aSrobert For example, `'ab'' for a target with an 8-bit `char' would be 3517*404b540aSrobert interpreted as 3518*404b540aSrobert `(int) ((unsigned char) 'a' * 256 + (unsigned char) 'b')', and 3519*404b540aSrobert `'\234a'' as 3520*404b540aSrobert `(int) ((unsigned char) '\234' * 256 + (unsigned char) 'a')'. 3521*404b540aSrobert 3522*404b540aSrobert * Source file inclusion. 3523*404b540aSrobert 3524*404b540aSrobert For a discussion on how the preprocessor locates header files, 3525*404b540aSrobert *Note Include Operation::. 3526*404b540aSrobert 3527*404b540aSrobert * Interpretation of the filename resulting from a macro-expanded 3528*404b540aSrobert `#include' directive. 3529*404b540aSrobert 3530*404b540aSrobert *Note Computed Includes::. 3531*404b540aSrobert 3532*404b540aSrobert * Treatment of a `#pragma' directive that after macro-expansion 3533*404b540aSrobert results in a standard pragma. 3534*404b540aSrobert 3535*404b540aSrobert No macro expansion occurs on any `#pragma' directive line, so the 3536*404b540aSrobert question does not arise. 3537*404b540aSrobert 3538*404b540aSrobert Note that GCC does not yet implement any of the standard pragmas. 3539*404b540aSrobert 3540*404b540aSrobert 3541*404b540aSrobert 3542*404b540aSrobertFile: cpp.info, Node: Implementation limits, Next: Obsolete Features, Prev: Implementation-defined behavior, Up: Implementation Details 3543*404b540aSrobert 3544*404b540aSrobert11.2 Implementation limits 3545*404b540aSrobert========================== 3546*404b540aSrobert 3547*404b540aSrobertCPP has a small number of internal limits. This section lists the 3548*404b540aSrobertlimits which the C standard requires to be no lower than some minimum, 3549*404b540aSrobertand all the others known. It is intended that there should be as few 3550*404b540aSrobertlimits as possible. If you encounter an undocumented or inconvenient 3551*404b540aSrobertlimit, please report that as a bug. *Note Reporting Bugs: (gcc)Bugs. 3552*404b540aSrobert 3553*404b540aSrobert Where we say something is limited "only by available memory", that 3554*404b540aSrobertmeans that internal data structures impose no intrinsic limit, and space 3555*404b540aSrobertis allocated with `malloc' or equivalent. The actual limit will 3556*404b540aSroberttherefore depend on many things, such as the size of other things 3557*404b540aSrobertallocated by the compiler at the same time, the amount of memory 3558*404b540aSrobertconsumed by other processes on the same computer, etc. 3559*404b540aSrobert 3560*404b540aSrobert * Nesting levels of `#include' files. 3561*404b540aSrobert 3562*404b540aSrobert We impose an arbitrary limit of 200 levels, to avoid runaway 3563*404b540aSrobert recursion. The standard requires at least 15 levels. 3564*404b540aSrobert 3565*404b540aSrobert * Nesting levels of conditional inclusion. 3566*404b540aSrobert 3567*404b540aSrobert The C standard mandates this be at least 63. CPP is limited only 3568*404b540aSrobert by available memory. 3569*404b540aSrobert 3570*404b540aSrobert * Levels of parenthesized expressions within a full expression. 3571*404b540aSrobert 3572*404b540aSrobert The C standard requires this to be at least 63. In preprocessor 3573*404b540aSrobert conditional expressions, it is limited only by available memory. 3574*404b540aSrobert 3575*404b540aSrobert * Significant initial characters in an identifier or macro name. 3576*404b540aSrobert 3577*404b540aSrobert The preprocessor treats all characters as significant. The C 3578*404b540aSrobert standard requires only that the first 63 be significant. 3579*404b540aSrobert 3580*404b540aSrobert * Number of macros simultaneously defined in a single translation 3581*404b540aSrobert unit. 3582*404b540aSrobert 3583*404b540aSrobert The standard requires at least 4095 be possible. CPP is limited 3584*404b540aSrobert only by available memory. 3585*404b540aSrobert 3586*404b540aSrobert * Number of parameters in a macro definition and arguments in a 3587*404b540aSrobert macro call. 3588*404b540aSrobert 3589*404b540aSrobert We allow `USHRT_MAX', which is no smaller than 65,535. The minimum 3590*404b540aSrobert required by the standard is 127. 3591*404b540aSrobert 3592*404b540aSrobert * Number of characters on a logical source line. 3593*404b540aSrobert 3594*404b540aSrobert The C standard requires a minimum of 4096 be permitted. CPP places 3595*404b540aSrobert no limits on this, but you may get incorrect column numbers 3596*404b540aSrobert reported in diagnostics for lines longer than 65,535 characters. 3597*404b540aSrobert 3598*404b540aSrobert * Maximum size of a source file. 3599*404b540aSrobert 3600*404b540aSrobert The standard does not specify any lower limit on the maximum size 3601*404b540aSrobert of a source file. GNU cpp maps files into memory, so it is 3602*404b540aSrobert limited by the available address space. This is generally at 3603*404b540aSrobert least two gigabytes. Depending on the operating system, the size 3604*404b540aSrobert of physical memory may or may not be a limitation. 3605*404b540aSrobert 3606*404b540aSrobert 3607*404b540aSrobert 3608*404b540aSrobertFile: cpp.info, Node: Obsolete Features, Next: Differences from previous versions, Prev: Implementation limits, Up: Implementation Details 3609*404b540aSrobert 3610*404b540aSrobert11.3 Obsolete Features 3611*404b540aSrobert====================== 3612*404b540aSrobert 3613*404b540aSrobertCPP has a number of features which are present mainly for compatibility 3614*404b540aSrobertwith older programs. We discourage their use in new code. In some 3615*404b540aSrobertcases, we plan to remove the feature in a future version of GCC. 3616*404b540aSrobert 3617*404b540aSrobert* Menu: 3618*404b540aSrobert 3619*404b540aSrobert* Assertions:: 3620*404b540aSrobert* Obsolete once-only headers:: 3621*404b540aSrobert 3622*404b540aSrobert 3623*404b540aSrobertFile: cpp.info, Node: Assertions, Next: Obsolete once-only headers, Up: Obsolete Features 3624*404b540aSrobert 3625*404b540aSrobert11.3.1 Assertions 3626*404b540aSrobert----------------- 3627*404b540aSrobert 3628*404b540aSrobert"Assertions" are a deprecated alternative to macros in writing 3629*404b540aSrobertconditionals to test what sort of computer or system the compiled 3630*404b540aSrobertprogram will run on. Assertions are usually predefined, but you can 3631*404b540aSrobertdefine them with preprocessing directives or command-line options. 3632*404b540aSrobert 3633*404b540aSrobert Assertions were intended to provide a more systematic way to describe 3634*404b540aSrobertthe compiler's target system. However, in practice they are just as 3635*404b540aSrobertunpredictable as the system-specific predefined macros. In addition, 3636*404b540aSrobertthey are not part of any standard, and only a few compilers support 3637*404b540aSrobertthem. Therefore, the use of assertions is *less* portable than the use 3638*404b540aSrobertof system-specific predefined macros. We recommend you do not use them 3639*404b540aSrobertat all. 3640*404b540aSrobert 3641*404b540aSrobert An assertion looks like this: 3642*404b540aSrobert 3643*404b540aSrobert #PREDICATE (ANSWER) 3644*404b540aSrobert 3645*404b540aSrobertPREDICATE must be a single identifier. ANSWER can be any sequence of 3646*404b540aSroberttokens; all characters are significant except for leading and trailing 3647*404b540aSrobertwhitespace, and differences in internal whitespace sequences are 3648*404b540aSrobertignored. (This is similar to the rules governing macro redefinition.) 3649*404b540aSrobertThus, `(x + y)' is different from `(x+y)' but equivalent to 3650*404b540aSrobert`( x + y )'. Parentheses do not nest inside an answer. 3651*404b540aSrobert 3652*404b540aSrobert To test an assertion, you write it in an `#if'. For example, this 3653*404b540aSrobertconditional succeeds if either `vax' or `ns16000' has been asserted as 3654*404b540aSrobertan answer for `machine'. 3655*404b540aSrobert 3656*404b540aSrobert #if #machine (vax) || #machine (ns16000) 3657*404b540aSrobert 3658*404b540aSrobertYou can test whether _any_ answer is asserted for a predicate by 3659*404b540aSrobertomitting the answer in the conditional: 3660*404b540aSrobert 3661*404b540aSrobert #if #machine 3662*404b540aSrobert 3663*404b540aSrobert Assertions are made with the `#assert' directive. Its sole argument 3664*404b540aSrobertis the assertion to make, without the leading `#' that identifies 3665*404b540aSrobertassertions in conditionals. 3666*404b540aSrobert 3667*404b540aSrobert #assert PREDICATE (ANSWER) 3668*404b540aSrobert 3669*404b540aSrobertYou may make several assertions with the same predicate and different 3670*404b540aSrobertanswers. Subsequent assertions do not override previous ones for the 3671*404b540aSrobertsame predicate. All the answers for any given predicate are 3672*404b540aSrobertsimultaneously true. 3673*404b540aSrobert 3674*404b540aSrobert Assertions can be canceled with the `#unassert' directive. It has 3675*404b540aSrobertthe same syntax as `#assert'. In that form it cancels only the answer 3676*404b540aSrobertwhich was specified on the `#unassert' line; other answers for that 3677*404b540aSrobertpredicate remain true. You can cancel an entire predicate by leaving 3678*404b540aSrobertout the answer: 3679*404b540aSrobert 3680*404b540aSrobert #unassert PREDICATE 3681*404b540aSrobert 3682*404b540aSrobertIn either form, if no such assertion has been made, `#unassert' has no 3683*404b540aSroberteffect. 3684*404b540aSrobert 3685*404b540aSrobert You can also make or cancel assertions using command line options. 3686*404b540aSrobert*Note Invocation::. 3687*404b540aSrobert 3688*404b540aSrobert 3689*404b540aSrobertFile: cpp.info, Node: Obsolete once-only headers, Prev: Assertions, Up: Obsolete Features 3690*404b540aSrobert 3691*404b540aSrobert11.3.2 Obsolete once-only headers 3692*404b540aSrobert--------------------------------- 3693*404b540aSrobert 3694*404b540aSrobertCPP supports two more ways of indicating that a header file should be 3695*404b540aSrobertread only once. Neither one is as portable as a wrapper `#ifndef', and 3696*404b540aSrobertwe recommend you do not use them in new programs. 3697*404b540aSrobert 3698*404b540aSrobert In the Objective-C language, there is a variant of `#include' called 3699*404b540aSrobert`#import' which includes a file, but does so at most once. If you use 3700*404b540aSrobert`#import' instead of `#include', then you don't need the conditionals 3701*404b540aSrobertinside the header file to prevent multiple inclusion of the contents. 3702*404b540aSrobertGCC permits the use of `#import' in C and C++ as well as Objective-C. 3703*404b540aSrobertHowever, it is not in standard C or C++ and should therefore not be 3704*404b540aSrobertused by portable programs. 3705*404b540aSrobert 3706*404b540aSrobert `#import' is not a well designed feature. It requires the users of 3707*404b540aSroberta header file to know that it should only be included once. It is much 3708*404b540aSrobertbetter for the header file's implementor to write the file so that users 3709*404b540aSrobertdon't need to know this. Using a wrapper `#ifndef' accomplishes this 3710*404b540aSrobertgoal. 3711*404b540aSrobert 3712*404b540aSrobert In the present implementation, a single use of `#import' will 3713*404b540aSrobertprevent the file from ever being read again, by either `#import' or 3714*404b540aSrobert`#include'. You should not rely on this; do not use both `#import' and 3715*404b540aSrobert`#include' to refer to the same header file. 3716*404b540aSrobert 3717*404b540aSrobert Another way to prevent a header file from being included more than 3718*404b540aSrobertonce is with the `#pragma once' directive. If `#pragma once' is seen 3719*404b540aSrobertwhen scanning a header file, that file will never be read again, no 3720*404b540aSrobertmatter what. 3721*404b540aSrobert 3722*404b540aSrobert `#pragma once' does not have the problems that `#import' does, but 3723*404b540aSrobertit is not recognized by all preprocessors, so you cannot rely on it in 3724*404b540aSroberta portable program. 3725*404b540aSrobert 3726*404b540aSrobert 3727*404b540aSrobertFile: cpp.info, Node: Differences from previous versions, Prev: Obsolete Features, Up: Implementation Details 3728*404b540aSrobert 3729*404b540aSrobert11.4 Differences from previous versions 3730*404b540aSrobert======================================= 3731*404b540aSrobert 3732*404b540aSrobertThis section details behavior which has changed from previous versions 3733*404b540aSrobertof CPP. We do not plan to change it again in the near future, but we 3734*404b540aSrobertdo not promise not to, either. 3735*404b540aSrobert 3736*404b540aSrobert The "previous versions" discussed here are 2.95 and before. The 3737*404b540aSrobertbehavior of GCC 3.0 is mostly the same as the behavior of the widely 3738*404b540aSrobertused 2.96 and 2.97 development snapshots. Where there are differences, 3739*404b540aSrobertthey generally represent bugs in the snapshots. 3740*404b540aSrobert 3741*404b540aSrobert * -I- deprecated 3742*404b540aSrobert 3743*404b540aSrobert This option has been deprecated in 4.0. `-iquote' is meant to 3744*404b540aSrobert replace the need for this option. 3745*404b540aSrobert 3746*404b540aSrobert * Order of evaluation of `#' and `##' operators 3747*404b540aSrobert 3748*404b540aSrobert The standard does not specify the order of evaluation of a chain of 3749*404b540aSrobert `##' operators, nor whether `#' is evaluated before, after, or at 3750*404b540aSrobert the same time as `##'. You should therefore not write any code 3751*404b540aSrobert which depends on any specific ordering. It is possible to 3752*404b540aSrobert guarantee an ordering, if you need one, by suitable use of nested 3753*404b540aSrobert macros. 3754*404b540aSrobert 3755*404b540aSrobert An example of where this might matter is pasting the arguments `1', 3756*404b540aSrobert `e' and `-2'. This would be fine for left-to-right pasting, but 3757*404b540aSrobert right-to-left pasting would produce an invalid token `e-2'. 3758*404b540aSrobert 3759*404b540aSrobert GCC 3.0 evaluates `#' and `##' at the same time and strictly left 3760*404b540aSrobert to right. Older versions evaluated all `#' operators first, then 3761*404b540aSrobert all `##' operators, in an unreliable order. 3762*404b540aSrobert 3763*404b540aSrobert * The form of whitespace between tokens in preprocessor output 3764*404b540aSrobert 3765*404b540aSrobert *Note Preprocessor Output::, for the current textual format. This 3766*404b540aSrobert is also the format used by stringification. Normally, the 3767*404b540aSrobert preprocessor communicates tokens directly to the compiler's 3768*404b540aSrobert parser, and whitespace does not come up at all. 3769*404b540aSrobert 3770*404b540aSrobert Older versions of GCC preserved all whitespace provided by the 3771*404b540aSrobert user and inserted lots more whitespace of their own, because they 3772*404b540aSrobert could not accurately predict when extra spaces were needed to 3773*404b540aSrobert prevent accidental token pasting. 3774*404b540aSrobert 3775*404b540aSrobert * Optional argument when invoking rest argument macros 3776*404b540aSrobert 3777*404b540aSrobert As an extension, GCC permits you to omit the variable arguments 3778*404b540aSrobert entirely when you use a variable argument macro. This is 3779*404b540aSrobert forbidden by the 1999 C standard, and will provoke a pedantic 3780*404b540aSrobert warning with GCC 3.0. Previous versions accepted it silently. 3781*404b540aSrobert 3782*404b540aSrobert * `##' swallowing preceding text in rest argument macros 3783*404b540aSrobert 3784*404b540aSrobert Formerly, in a macro expansion, if `##' appeared before a variable 3785*404b540aSrobert arguments parameter, and the set of tokens specified for that 3786*404b540aSrobert argument in the macro invocation was empty, previous versions of 3787*404b540aSrobert CPP would back up and remove the preceding sequence of 3788*404b540aSrobert non-whitespace characters (*not* the preceding token). This 3789*404b540aSrobert extension is in direct conflict with the 1999 C standard and has 3790*404b540aSrobert been drastically pared back. 3791*404b540aSrobert 3792*404b540aSrobert In the current version of the preprocessor, if `##' appears between 3793*404b540aSrobert a comma and a variable arguments parameter, and the variable 3794*404b540aSrobert argument is omitted entirely, the comma will be removed from the 3795*404b540aSrobert expansion. If the variable argument is empty, or the token before 3796*404b540aSrobert `##' is not a comma, then `##' behaves as a normal token paste. 3797*404b540aSrobert 3798*404b540aSrobert * `#line' and `#include' 3799*404b540aSrobert 3800*404b540aSrobert The `#line' directive used to change GCC's notion of the 3801*404b540aSrobert "directory containing the current file", used by `#include' with a 3802*404b540aSrobert double-quoted header file name. In 3.0 and later, it does not. 3803*404b540aSrobert *Note Line Control::, for further explanation. 3804*404b540aSrobert 3805*404b540aSrobert * Syntax of `#line' 3806*404b540aSrobert 3807*404b540aSrobert In GCC 2.95 and previous, the string constant argument to `#line' 3808*404b540aSrobert was treated the same way as the argument to `#include': backslash 3809*404b540aSrobert escapes were not honored, and the string ended at the second `"'. 3810*404b540aSrobert This is not compliant with the C standard. In GCC 3.0, an attempt 3811*404b540aSrobert was made to correct the behavior, so that the string was treated 3812*404b540aSrobert as a real string constant, but it turned out to be buggy. In 3.1, 3813*404b540aSrobert the bugs have been fixed. (We are not fixing the bugs in 3.0 3814*404b540aSrobert because they affect relatively few people and the fix is quite 3815*404b540aSrobert invasive.) 3816*404b540aSrobert 3817*404b540aSrobert 3818*404b540aSrobert 3819*404b540aSrobertFile: cpp.info, Node: Invocation, Next: Environment Variables, Prev: Implementation Details, Up: Top 3820*404b540aSrobert 3821*404b540aSrobert12 Invocation 3822*404b540aSrobert************* 3823*404b540aSrobert 3824*404b540aSrobertMost often when you use the C preprocessor you will not have to invoke 3825*404b540aSrobertit explicitly: the C compiler will do so automatically. However, the 3826*404b540aSrobertpreprocessor is sometimes useful on its own. All the options listed 3827*404b540aSroberthere are also acceptable to the C compiler and have the same meaning, 3828*404b540aSrobertexcept that the C compiler has different rules for specifying the output 3829*404b540aSrobertfile. 3830*404b540aSrobert 3831*404b540aSrobert _Note:_ Whether you use the preprocessor by way of `gcc' or `cpp', 3832*404b540aSrobertthe "compiler driver" is run first. This program's purpose is to 3833*404b540aSroberttranslate your command into invocations of the programs that do the 3834*404b540aSrobertactual work. Their command line interfaces are similar but not 3835*404b540aSrobertidentical to the documented interface, and may change without notice. 3836*404b540aSrobert 3837*404b540aSrobert The C preprocessor expects two file names as arguments, INFILE and 3838*404b540aSrobertOUTFILE. The preprocessor reads INFILE together with any other files 3839*404b540aSrobertit specifies with `#include'. All the output generated by the combined 3840*404b540aSrobertinput files is written in OUTFILE. 3841*404b540aSrobert 3842*404b540aSrobert Either INFILE or OUTFILE may be `-', which as INFILE means to read 3843*404b540aSrobertfrom standard input and as OUTFILE means to write to standard output. 3844*404b540aSrobertAlso, if either file is omitted, it means the same as if `-' had been 3845*404b540aSrobertspecified for that file. 3846*404b540aSrobert 3847*404b540aSrobert Unless otherwise noted, or the option ends in `=', all options which 3848*404b540aSroberttake an argument may have that argument appear either immediately after 3849*404b540aSrobertthe option, or with a space between option and argument: `-Ifoo' and 3850*404b540aSrobert`-I foo' have the same effect. 3851*404b540aSrobert 3852*404b540aSrobert Many options have multi-letter names; therefore multiple 3853*404b540aSrobertsingle-letter options may _not_ be grouped: `-dM' is very different from 3854*404b540aSrobert`-d -M'. 3855*404b540aSrobert 3856*404b540aSrobert`-D NAME' 3857*404b540aSrobert Predefine NAME as a macro, with definition `1'. 3858*404b540aSrobert 3859*404b540aSrobert`-D NAME=DEFINITION' 3860*404b540aSrobert The contents of DEFINITION are tokenized and processed as if they 3861*404b540aSrobert appeared during translation phase three in a `#define' directive. 3862*404b540aSrobert In particular, the definition will be truncated by embedded 3863*404b540aSrobert newline characters. 3864*404b540aSrobert 3865*404b540aSrobert If you are invoking the preprocessor from a shell or shell-like 3866*404b540aSrobert program you may need to use the shell's quoting syntax to protect 3867*404b540aSrobert characters such as spaces that have a meaning in the shell syntax. 3868*404b540aSrobert 3869*404b540aSrobert If you wish to define a function-like macro on the command line, 3870*404b540aSrobert write its argument list with surrounding parentheses before the 3871*404b540aSrobert equals sign (if any). Parentheses are meaningful to most shells, 3872*404b540aSrobert so you will need to quote the option. With `sh' and `csh', 3873*404b540aSrobert `-D'NAME(ARGS...)=DEFINITION'' works. 3874*404b540aSrobert 3875*404b540aSrobert `-D' and `-U' options are processed in the order they are given on 3876*404b540aSrobert the command line. All `-imacros FILE' and `-include FILE' options 3877*404b540aSrobert are processed after all `-D' and `-U' options. 3878*404b540aSrobert 3879*404b540aSrobert`-U NAME' 3880*404b540aSrobert Cancel any previous definition of NAME, either built in or 3881*404b540aSrobert provided with a `-D' option. 3882*404b540aSrobert 3883*404b540aSrobert`-undef' 3884*404b540aSrobert Do not predefine any system-specific or GCC-specific macros. The 3885*404b540aSrobert standard predefined macros remain defined. *Note Standard 3886*404b540aSrobert Predefined Macros::. 3887*404b540aSrobert 3888*404b540aSrobert`-I DIR' 3889*404b540aSrobert Add the directory DIR to the list of directories to be searched 3890*404b540aSrobert for header files. *Note Search Path::. Directories named by `-I' 3891*404b540aSrobert are searched before the standard system include directories. If 3892*404b540aSrobert the directory DIR is a standard system include directory, the 3893*404b540aSrobert option is ignored to ensure that the default search order for 3894*404b540aSrobert system directories and the special treatment of system headers are 3895*404b540aSrobert not defeated (*note System Headers::) . 3896*404b540aSrobert 3897*404b540aSrobert`-o FILE' 3898*404b540aSrobert Write output to FILE. This is the same as specifying FILE as the 3899*404b540aSrobert second non-option argument to `cpp'. `gcc' has a different 3900*404b540aSrobert interpretation of a second non-option argument, so you must use 3901*404b540aSrobert `-o' to specify the output file. 3902*404b540aSrobert 3903*404b540aSrobert`-Wall' 3904*404b540aSrobert Turns on all optional warnings which are desirable for normal code. 3905*404b540aSrobert At present this is `-Wcomment', `-Wtrigraphs', `-Wmultichar' and a 3906*404b540aSrobert warning about integer promotion causing a change of sign in `#if' 3907*404b540aSrobert expressions. Note that many of the preprocessor's warnings are on 3908*404b540aSrobert by default and have no options to control them. 3909*404b540aSrobert 3910*404b540aSrobert`-Wcomment' 3911*404b540aSrobert`-Wcomments' 3912*404b540aSrobert Warn whenever a comment-start sequence `/*' appears in a `/*' 3913*404b540aSrobert comment, or whenever a backslash-newline appears in a `//' comment. 3914*404b540aSrobert (Both forms have the same effect.) 3915*404b540aSrobert 3916*404b540aSrobert`-Wtrigraphs' 3917*404b540aSrobert Most trigraphs in comments cannot affect the meaning of the 3918*404b540aSrobert program. However, a trigraph that would form an escaped newline 3919*404b540aSrobert (`??/' at the end of a line) can, by changing where the comment 3920*404b540aSrobert begins or ends. Therefore, only trigraphs that would form escaped 3921*404b540aSrobert newlines produce warnings inside a comment. 3922*404b540aSrobert 3923*404b540aSrobert This option is implied by `-Wall'. If `-Wall' is not given, this 3924*404b540aSrobert option is still enabled unless trigraphs are enabled. To get 3925*404b540aSrobert trigraph conversion without warnings, but get the other `-Wall' 3926*404b540aSrobert warnings, use `-trigraphs -Wall -Wno-trigraphs'. 3927*404b540aSrobert 3928*404b540aSrobert`-Wtraditional' 3929*404b540aSrobert Warn about certain constructs that behave differently in 3930*404b540aSrobert traditional and ISO C. Also warn about ISO C constructs that have 3931*404b540aSrobert no traditional C equivalent, and problematic constructs which 3932*404b540aSrobert should be avoided. *Note Traditional Mode::. 3933*404b540aSrobert 3934*404b540aSrobert`-Wimport' 3935*404b540aSrobert Warn the first time `#import' is used. 3936*404b540aSrobert 3937*404b540aSrobert`-Wundef' 3938*404b540aSrobert Warn whenever an identifier which is not a macro is encountered in 3939*404b540aSrobert an `#if' directive, outside of `defined'. Such identifiers are 3940*404b540aSrobert replaced with zero. 3941*404b540aSrobert 3942*404b540aSrobert`-Wunused-macros' 3943*404b540aSrobert Warn about macros defined in the main file that are unused. A 3944*404b540aSrobert macro is "used" if it is expanded or tested for existence at least 3945*404b540aSrobert once. The preprocessor will also warn if the macro has not been 3946*404b540aSrobert used at the time it is redefined or undefined. 3947*404b540aSrobert 3948*404b540aSrobert Built-in macros, macros defined on the command line, and macros 3949*404b540aSrobert defined in include files are not warned about. 3950*404b540aSrobert 3951*404b540aSrobert _Note:_ If a macro is actually used, but only used in skipped 3952*404b540aSrobert conditional blocks, then CPP will report it as unused. To avoid 3953*404b540aSrobert the warning in such a case, you might improve the scope of the 3954*404b540aSrobert macro's definition by, for example, moving it into the first 3955*404b540aSrobert skipped block. Alternatively, you could provide a dummy use with 3956*404b540aSrobert something like: 3957*404b540aSrobert 3958*404b540aSrobert #if defined the_macro_causing_the_warning 3959*404b540aSrobert #endif 3960*404b540aSrobert 3961*404b540aSrobert`-Wendif-labels' 3962*404b540aSrobert Warn whenever an `#else' or an `#endif' are followed by text. 3963*404b540aSrobert This usually happens in code of the form 3964*404b540aSrobert 3965*404b540aSrobert #if FOO 3966*404b540aSrobert ... 3967*404b540aSrobert #else FOO 3968*404b540aSrobert ... 3969*404b540aSrobert #endif FOO 3970*404b540aSrobert 3971*404b540aSrobert The second and third `FOO' should be in comments, but often are not 3972*404b540aSrobert in older programs. This warning is on by default. 3973*404b540aSrobert 3974*404b540aSrobert`-Werror' 3975*404b540aSrobert Make all warnings into hard errors. Source code which triggers 3976*404b540aSrobert warnings will be rejected. 3977*404b540aSrobert 3978*404b540aSrobert`-Wsystem-headers' 3979*404b540aSrobert Issue warnings for code in system headers. These are normally 3980*404b540aSrobert unhelpful in finding bugs in your own code, therefore suppressed. 3981*404b540aSrobert If you are responsible for the system library, you may want to see 3982*404b540aSrobert them. 3983*404b540aSrobert 3984*404b540aSrobert`-w' 3985*404b540aSrobert Suppress all warnings, including those which GNU CPP issues by 3986*404b540aSrobert default. 3987*404b540aSrobert 3988*404b540aSrobert`-pedantic' 3989*404b540aSrobert Issue all the mandatory diagnostics listed in the C standard. 3990*404b540aSrobert Some of them are left out by default, since they trigger 3991*404b540aSrobert frequently on harmless code. 3992*404b540aSrobert 3993*404b540aSrobert`-pedantic-errors' 3994*404b540aSrobert Issue all the mandatory diagnostics, and make all mandatory 3995*404b540aSrobert diagnostics into errors. This includes mandatory diagnostics that 3996*404b540aSrobert GCC issues without `-pedantic' but treats as warnings. 3997*404b540aSrobert 3998*404b540aSrobert`-M' 3999*404b540aSrobert Instead of outputting the result of preprocessing, output a rule 4000*404b540aSrobert suitable for `make' describing the dependencies of the main source 4001*404b540aSrobert file. The preprocessor outputs one `make' rule containing the 4002*404b540aSrobert object file name for that source file, a colon, and the names of 4003*404b540aSrobert all the included files, including those coming from `-include' or 4004*404b540aSrobert `-imacros' command line options. 4005*404b540aSrobert 4006*404b540aSrobert Unless specified explicitly (with `-MT' or `-MQ'), the object file 4007*404b540aSrobert name consists of the basename of the source file with any suffix 4008*404b540aSrobert replaced with object file suffix. If there are many included 4009*404b540aSrobert files then the rule is split into several lines using `\'-newline. 4010*404b540aSrobert The rule has no commands. 4011*404b540aSrobert 4012*404b540aSrobert This option does not suppress the preprocessor's debug output, 4013*404b540aSrobert such as `-dM'. To avoid mixing such debug output with the 4014*404b540aSrobert dependency rules you should explicitly specify the dependency 4015*404b540aSrobert output file with `-MF', or use an environment variable like 4016*404b540aSrobert `DEPENDENCIES_OUTPUT' (*note Environment Variables::). Debug 4017*404b540aSrobert output will still be sent to the regular output stream as normal. 4018*404b540aSrobert 4019*404b540aSrobert Passing `-M' to the driver implies `-E', and suppresses warnings 4020*404b540aSrobert with an implicit `-w'. 4021*404b540aSrobert 4022*404b540aSrobert`-MM' 4023*404b540aSrobert Like `-M' but do not mention header files that are found in system 4024*404b540aSrobert header directories, nor header files that are included, directly 4025*404b540aSrobert or indirectly, from such a header. 4026*404b540aSrobert 4027*404b540aSrobert This implies that the choice of angle brackets or double quotes in 4028*404b540aSrobert an `#include' directive does not in itself determine whether that 4029*404b540aSrobert header will appear in `-MM' dependency output. This is a slight 4030*404b540aSrobert change in semantics from GCC versions 3.0 and earlier. 4031*404b540aSrobert 4032*404b540aSrobert`-MF FILE' 4033*404b540aSrobert When used with `-M' or `-MM', specifies a file to write the 4034*404b540aSrobert dependencies to. If no `-MF' switch is given the preprocessor 4035*404b540aSrobert sends the rules to the same place it would have sent preprocessed 4036*404b540aSrobert output. 4037*404b540aSrobert 4038*404b540aSrobert When used with the driver options `-MD' or `-MMD', `-MF' overrides 4039*404b540aSrobert the default dependency output file. 4040*404b540aSrobert 4041*404b540aSrobert`-MG' 4042*404b540aSrobert In conjunction with an option such as `-M' requesting dependency 4043*404b540aSrobert generation, `-MG' assumes missing header files are generated files 4044*404b540aSrobert and adds them to the dependency list without raising an error. 4045*404b540aSrobert The dependency filename is taken directly from the `#include' 4046*404b540aSrobert directive without prepending any path. `-MG' also suppresses 4047*404b540aSrobert preprocessed output, as a missing header file renders this useless. 4048*404b540aSrobert 4049*404b540aSrobert This feature is used in automatic updating of makefiles. 4050*404b540aSrobert 4051*404b540aSrobert`-MP' 4052*404b540aSrobert This option instructs CPP to add a phony target for each dependency 4053*404b540aSrobert other than the main file, causing each to depend on nothing. These 4054*404b540aSrobert dummy rules work around errors `make' gives if you remove header 4055*404b540aSrobert files without updating the `Makefile' to match. 4056*404b540aSrobert 4057*404b540aSrobert This is typical output: 4058*404b540aSrobert 4059*404b540aSrobert test.o: test.c test.h 4060*404b540aSrobert 4061*404b540aSrobert test.h: 4062*404b540aSrobert 4063*404b540aSrobert`-MT TARGET' 4064*404b540aSrobert Change the target of the rule emitted by dependency generation. By 4065*404b540aSrobert default CPP takes the name of the main input file, including any 4066*404b540aSrobert path, deletes any file suffix such as `.c', and appends the 4067*404b540aSrobert platform's usual object suffix. The result is the target. 4068*404b540aSrobert 4069*404b540aSrobert An `-MT' option will set the target to be exactly the string you 4070*404b540aSrobert specify. If you want multiple targets, you can specify them as a 4071*404b540aSrobert single argument to `-MT', or use multiple `-MT' options. 4072*404b540aSrobert 4073*404b540aSrobert For example, `-MT '$(objpfx)foo.o'' might give 4074*404b540aSrobert 4075*404b540aSrobert $(objpfx)foo.o: foo.c 4076*404b540aSrobert 4077*404b540aSrobert`-MQ TARGET' 4078*404b540aSrobert Same as `-MT', but it quotes any characters which are special to 4079*404b540aSrobert Make. `-MQ '$(objpfx)foo.o'' gives 4080*404b540aSrobert 4081*404b540aSrobert $$(objpfx)foo.o: foo.c 4082*404b540aSrobert 4083*404b540aSrobert The default target is automatically quoted, as if it were given 4084*404b540aSrobert with `-MQ'. 4085*404b540aSrobert 4086*404b540aSrobert`-MD' 4087*404b540aSrobert `-MD' is equivalent to `-M -MF FILE', except that `-E' is not 4088*404b540aSrobert implied. The driver determines FILE based on whether an `-o' 4089*404b540aSrobert option is given. If it is, the driver uses its argument but with 4090*404b540aSrobert a suffix of `.d', otherwise it take the basename of the input file 4091*404b540aSrobert and applies a `.d' suffix. 4092*404b540aSrobert 4093*404b540aSrobert If `-MD' is used in conjunction with `-E', any `-o' switch is 4094*404b540aSrobert understood to specify the dependency output file (*note -MF: 4095*404b540aSrobert dashMF.), but if used without `-E', each `-o' is understood to 4096*404b540aSrobert specify a target object file. 4097*404b540aSrobert 4098*404b540aSrobert Since `-E' is not implied, `-MD' can be used to generate a 4099*404b540aSrobert dependency output file as a side-effect of the compilation process. 4100*404b540aSrobert 4101*404b540aSrobert`-MMD' 4102*404b540aSrobert Like `-MD' except mention only user header files, not system 4103*404b540aSrobert header files. 4104*404b540aSrobert 4105*404b540aSrobert`-x c' 4106*404b540aSrobert`-x c++' 4107*404b540aSrobert`-x objective-c' 4108*404b540aSrobert`-x assembler-with-cpp' 4109*404b540aSrobert Specify the source language: C, C++, Objective-C, or assembly. 4110*404b540aSrobert This has nothing to do with standards conformance or extensions; 4111*404b540aSrobert it merely selects which base syntax to expect. If you give none 4112*404b540aSrobert of these options, cpp will deduce the language from the extension 4113*404b540aSrobert of the source file: `.c', `.cc', `.m', or `.S'. Some other common 4114*404b540aSrobert extensions for C++ and assembly are also recognized. If cpp does 4115*404b540aSrobert not recognize the extension, it will treat the file as C; this is 4116*404b540aSrobert the most generic mode. 4117*404b540aSrobert 4118*404b540aSrobert _Note:_ Previous versions of cpp accepted a `-lang' option which 4119*404b540aSrobert selected both the language and the standards conformance level. 4120*404b540aSrobert This option has been removed, because it conflicts with the `-l' 4121*404b540aSrobert option. 4122*404b540aSrobert 4123*404b540aSrobert`-std=STANDARD' 4124*404b540aSrobert`-ansi' 4125*404b540aSrobert Specify the standard to which the code should conform. Currently 4126*404b540aSrobert CPP knows about C and C++ standards; others may be added in the 4127*404b540aSrobert future. 4128*404b540aSrobert 4129*404b540aSrobert STANDARD may be one of: 4130*404b540aSrobert `iso9899:1990' 4131*404b540aSrobert `c89' 4132*404b540aSrobert The ISO C standard from 1990. `c89' is the customary 4133*404b540aSrobert shorthand for this version of the standard. 4134*404b540aSrobert 4135*404b540aSrobert The `-ansi' option is equivalent to `-std=c89'. 4136*404b540aSrobert 4137*404b540aSrobert `iso9899:199409' 4138*404b540aSrobert The 1990 C standard, as amended in 1994. 4139*404b540aSrobert 4140*404b540aSrobert `iso9899:1999' 4141*404b540aSrobert `c99' 4142*404b540aSrobert `iso9899:199x' 4143*404b540aSrobert `c9x' 4144*404b540aSrobert The revised ISO C standard, published in December 1999. 4145*404b540aSrobert Before publication, this was known as C9X. 4146*404b540aSrobert 4147*404b540aSrobert `gnu89' 4148*404b540aSrobert The 1990 C standard plus GNU extensions. This is the default. 4149*404b540aSrobert 4150*404b540aSrobert `gnu99' 4151*404b540aSrobert `gnu9x' 4152*404b540aSrobert The 1999 C standard plus GNU extensions. 4153*404b540aSrobert 4154*404b540aSrobert `c++98' 4155*404b540aSrobert The 1998 ISO C++ standard plus amendments. 4156*404b540aSrobert 4157*404b540aSrobert `gnu++98' 4158*404b540aSrobert The same as `-std=c++98' plus GNU extensions. This is the 4159*404b540aSrobert default for C++ code. 4160*404b540aSrobert 4161*404b540aSrobert`-I-' 4162*404b540aSrobert Split the include path. Any directories specified with `-I' 4163*404b540aSrobert options before `-I-' are searched only for headers requested with 4164*404b540aSrobert `#include "FILE"'; they are not searched for `#include <FILE>'. 4165*404b540aSrobert If additional directories are specified with `-I' options after 4166*404b540aSrobert the `-I-', those directories are searched for all `#include' 4167*404b540aSrobert directives. 4168*404b540aSrobert 4169*404b540aSrobert In addition, `-I-' inhibits the use of the directory of the current 4170*404b540aSrobert file directory as the first search directory for `#include "FILE"'. 4171*404b540aSrobert *Note Search Path::. This option has been deprecated. 4172*404b540aSrobert 4173*404b540aSrobert`-nostdinc' 4174*404b540aSrobert Do not search the standard system directories for header files. 4175*404b540aSrobert Only the directories you have specified with `-I' options (and the 4176*404b540aSrobert directory of the current file, if appropriate) are searched. 4177*404b540aSrobert 4178*404b540aSrobert`-nostdinc++' 4179*404b540aSrobert Do not search for header files in the C++-specific standard 4180*404b540aSrobert directories, but do still search the other standard directories. 4181*404b540aSrobert (This option is used when building the C++ library.) 4182*404b540aSrobert 4183*404b540aSrobert`-include FILE' 4184*404b540aSrobert Process FILE as if `#include "file"' appeared as the first line of 4185*404b540aSrobert the primary source file. However, the first directory searched 4186*404b540aSrobert for FILE is the preprocessor's working directory _instead of_ the 4187*404b540aSrobert directory containing the main source file. If not found there, it 4188*404b540aSrobert is searched for in the remainder of the `#include "..."' search 4189*404b540aSrobert chain as normal. 4190*404b540aSrobert 4191*404b540aSrobert If multiple `-include' options are given, the files are included 4192*404b540aSrobert in the order they appear on the command line. 4193*404b540aSrobert 4194*404b540aSrobert`-imacros FILE' 4195*404b540aSrobert Exactly like `-include', except that any output produced by 4196*404b540aSrobert scanning FILE is thrown away. Macros it defines remain defined. 4197*404b540aSrobert This allows you to acquire all the macros from a header without 4198*404b540aSrobert also processing its declarations. 4199*404b540aSrobert 4200*404b540aSrobert All files specified by `-imacros' are processed before all files 4201*404b540aSrobert specified by `-include'. 4202*404b540aSrobert 4203*404b540aSrobert`-idirafter DIR' 4204*404b540aSrobert Search DIR for header files, but do it _after_ all directories 4205*404b540aSrobert specified with `-I' and the standard system directories have been 4206*404b540aSrobert exhausted. DIR is treated as a system include directory. 4207*404b540aSrobert 4208*404b540aSrobert`-iprefix PREFIX' 4209*404b540aSrobert Specify PREFIX as the prefix for subsequent `-iwithprefix' 4210*404b540aSrobert options. If the prefix represents a directory, you should include 4211*404b540aSrobert the final `/'. 4212*404b540aSrobert 4213*404b540aSrobert`-iwithprefix DIR' 4214*404b540aSrobert`-iwithprefixbefore DIR' 4215*404b540aSrobert Append DIR to the prefix specified previously with `-iprefix', and 4216*404b540aSrobert add the resulting directory to the include search path. 4217*404b540aSrobert `-iwithprefixbefore' puts it in the same place `-I' would; 4218*404b540aSrobert `-iwithprefix' puts it where `-idirafter' would. 4219*404b540aSrobert 4220*404b540aSrobert`-isysroot DIR' 4221*404b540aSrobert This option is like the `--sysroot' option, but applies only to 4222*404b540aSrobert header files. See the `--sysroot' option for more information. 4223*404b540aSrobert 4224*404b540aSrobert`-imultilib DIR' 4225*404b540aSrobert Use DIR as a subdirectory of the directory containing 4226*404b540aSrobert target-specific C++ headers. 4227*404b540aSrobert 4228*404b540aSrobert`-isystem DIR' 4229*404b540aSrobert Search DIR for header files, after all directories specified by 4230*404b540aSrobert `-I' but before the standard system directories. Mark it as a 4231*404b540aSrobert system directory, so that it gets the same special treatment as is 4232*404b540aSrobert applied to the standard system directories. *Note System 4233*404b540aSrobert Headers::. 4234*404b540aSrobert 4235*404b540aSrobert`-iquote DIR' 4236*404b540aSrobert Search DIR only for header files requested with `#include "FILE"'; 4237*404b540aSrobert they are not searched for `#include <FILE>', before all 4238*404b540aSrobert directories specified by `-I' and before the standard system 4239*404b540aSrobert directories. *Note Search Path::. 4240*404b540aSrobert 4241*404b540aSrobert`-fdollars-in-identifiers' 4242*404b540aSrobert Accept `$' in identifiers. *Note Identifier characters::. 4243*404b540aSrobert 4244*404b540aSrobert`-fextended-identifiers' 4245*404b540aSrobert Accept universal character names in identifiers. This option is 4246*404b540aSrobert experimental; in a future version of GCC, it will be enabled by 4247*404b540aSrobert default for C99 and C++. 4248*404b540aSrobert 4249*404b540aSrobert`-fpreprocessed' 4250*404b540aSrobert Indicate to the preprocessor that the input file has already been 4251*404b540aSrobert preprocessed. This suppresses things like macro expansion, 4252*404b540aSrobert trigraph conversion, escaped newline splicing, and processing of 4253*404b540aSrobert most directives. The preprocessor still recognizes and removes 4254*404b540aSrobert comments, so that you can pass a file preprocessed with `-C' to 4255*404b540aSrobert the compiler without problems. In this mode the integrated 4256*404b540aSrobert preprocessor is little more than a tokenizer for the front ends. 4257*404b540aSrobert 4258*404b540aSrobert `-fpreprocessed' is implicit if the input file has one of the 4259*404b540aSrobert extensions `.i', `.ii' or `.mi'. These are the extensions that 4260*404b540aSrobert GCC uses for preprocessed files created by `-save-temps'. 4261*404b540aSrobert 4262*404b540aSrobert`-ftabstop=WIDTH' 4263*404b540aSrobert Set the distance between tab stops. This helps the preprocessor 4264*404b540aSrobert report correct column numbers in warnings or errors, even if tabs 4265*404b540aSrobert appear on the line. If the value is less than 1 or greater than 4266*404b540aSrobert 100, the option is ignored. The default is 8. 4267*404b540aSrobert 4268*404b540aSrobert`-fexec-charset=CHARSET' 4269*404b540aSrobert Set the execution character set, used for string and character 4270*404b540aSrobert constants. The default is UTF-8. CHARSET can be any encoding 4271*404b540aSrobert supported by the system's `iconv' library routine. 4272*404b540aSrobert 4273*404b540aSrobert`-fwide-exec-charset=CHARSET' 4274*404b540aSrobert Set the wide execution character set, used for wide string and 4275*404b540aSrobert character constants. The default is UTF-32 or UTF-16, whichever 4276*404b540aSrobert corresponds to the width of `wchar_t'. As with `-fexec-charset', 4277*404b540aSrobert CHARSET can be any encoding supported by the system's `iconv' 4278*404b540aSrobert library routine; however, you will have problems with encodings 4279*404b540aSrobert that do not fit exactly in `wchar_t'. 4280*404b540aSrobert 4281*404b540aSrobert`-finput-charset=CHARSET' 4282*404b540aSrobert Set the input character set, used for translation from the 4283*404b540aSrobert character set of the input file to the source character set used 4284*404b540aSrobert by GCC. If the locale does not specify, or GCC cannot get this 4285*404b540aSrobert information from the locale, the default is UTF-8. This can be 4286*404b540aSrobert overridden by either the locale or this command line option. 4287*404b540aSrobert Currently the command line option takes precedence if there's a 4288*404b540aSrobert conflict. CHARSET can be any encoding supported by the system's 4289*404b540aSrobert `iconv' library routine. 4290*404b540aSrobert 4291*404b540aSrobert`-fworking-directory' 4292*404b540aSrobert Enable generation of linemarkers in the preprocessor output that 4293*404b540aSrobert will let the compiler know the current working directory at the 4294*404b540aSrobert time of preprocessing. When this option is enabled, the 4295*404b540aSrobert preprocessor will emit, after the initial linemarker, a second 4296*404b540aSrobert linemarker with the current working directory followed by two 4297*404b540aSrobert slashes. GCC will use this directory, when it's present in the 4298*404b540aSrobert preprocessed input, as the directory emitted as the current 4299*404b540aSrobert working directory in some debugging information formats. This 4300*404b540aSrobert option is implicitly enabled if debugging information is enabled, 4301*404b540aSrobert but this can be inhibited with the negated form 4302*404b540aSrobert `-fno-working-directory'. If the `-P' flag is present in the 4303*404b540aSrobert command line, this option has no effect, since no `#line' 4304*404b540aSrobert directives are emitted whatsoever. 4305*404b540aSrobert 4306*404b540aSrobert`-fno-show-column' 4307*404b540aSrobert Do not print column numbers in diagnostics. This may be necessary 4308*404b540aSrobert if diagnostics are being scanned by a program that does not 4309*404b540aSrobert understand the column numbers, such as `dejagnu'. 4310*404b540aSrobert 4311*404b540aSrobert`-A PREDICATE=ANSWER' 4312*404b540aSrobert Make an assertion with the predicate PREDICATE and answer ANSWER. 4313*404b540aSrobert This form is preferred to the older form `-A PREDICATE(ANSWER)', 4314*404b540aSrobert which is still supported, because it does not use shell special 4315*404b540aSrobert characters. *Note Assertions::. 4316*404b540aSrobert 4317*404b540aSrobert`-A -PREDICATE=ANSWER' 4318*404b540aSrobert Cancel an assertion with the predicate PREDICATE and answer ANSWER. 4319*404b540aSrobert 4320*404b540aSrobert`-dCHARS' 4321*404b540aSrobert CHARS is a sequence of one or more of the following characters, 4322*404b540aSrobert and must not be preceded by a space. Other characters are 4323*404b540aSrobert interpreted by the compiler proper, or reserved for future 4324*404b540aSrobert versions of GCC, and so are silently ignored. If you specify 4325*404b540aSrobert characters whose behavior conflicts, the result is undefined. 4326*404b540aSrobert 4327*404b540aSrobert `M' 4328*404b540aSrobert Instead of the normal output, generate a list of `#define' 4329*404b540aSrobert directives for all the macros defined during the execution of 4330*404b540aSrobert the preprocessor, including predefined macros. This gives 4331*404b540aSrobert you a way of finding out what is predefined in your version 4332*404b540aSrobert of the preprocessor. Assuming you have no file `foo.h', the 4333*404b540aSrobert command 4334*404b540aSrobert 4335*404b540aSrobert touch foo.h; cpp -dM foo.h 4336*404b540aSrobert 4337*404b540aSrobert will show all the predefined macros. 4338*404b540aSrobert 4339*404b540aSrobert `D' 4340*404b540aSrobert Like `M' except in two respects: it does _not_ include the 4341*404b540aSrobert predefined macros, and it outputs _both_ the `#define' 4342*404b540aSrobert directives and the result of preprocessing. Both kinds of 4343*404b540aSrobert output go to the standard output file. 4344*404b540aSrobert 4345*404b540aSrobert `N' 4346*404b540aSrobert Like `D', but emit only the macro names, not their expansions. 4347*404b540aSrobert 4348*404b540aSrobert `I' 4349*404b540aSrobert Output `#include' directives in addition to the result of 4350*404b540aSrobert preprocessing. 4351*404b540aSrobert 4352*404b540aSrobert`-P' 4353*404b540aSrobert Inhibit generation of linemarkers in the output from the 4354*404b540aSrobert preprocessor. This might be useful when running the preprocessor 4355*404b540aSrobert on something that is not C code, and will be sent to a program 4356*404b540aSrobert which might be confused by the linemarkers. *Note Preprocessor 4357*404b540aSrobert Output::. 4358*404b540aSrobert 4359*404b540aSrobert`-C' 4360*404b540aSrobert Do not discard comments. All comments are passed through to the 4361*404b540aSrobert output file, except for comments in processed directives, which 4362*404b540aSrobert are deleted along with the directive. 4363*404b540aSrobert 4364*404b540aSrobert You should be prepared for side effects when using `-C'; it causes 4365*404b540aSrobert the preprocessor to treat comments as tokens in their own right. 4366*404b540aSrobert For example, comments appearing at the start of what would be a 4367*404b540aSrobert directive line have the effect of turning that line into an 4368*404b540aSrobert ordinary source line, since the first token on the line is no 4369*404b540aSrobert longer a `#'. 4370*404b540aSrobert 4371*404b540aSrobert`-CC' 4372*404b540aSrobert Do not discard comments, including during macro expansion. This is 4373*404b540aSrobert like `-C', except that comments contained within macros are also 4374*404b540aSrobert passed through to the output file where the macro is expanded. 4375*404b540aSrobert 4376*404b540aSrobert In addition to the side-effects of the `-C' option, the `-CC' 4377*404b540aSrobert option causes all C++-style comments inside a macro to be 4378*404b540aSrobert converted to C-style comments. This is to prevent later use of 4379*404b540aSrobert that macro from inadvertently commenting out the remainder of the 4380*404b540aSrobert source line. 4381*404b540aSrobert 4382*404b540aSrobert The `-CC' option is generally used to support lint comments. 4383*404b540aSrobert 4384*404b540aSrobert`-traditional-cpp' 4385*404b540aSrobert Try to imitate the behavior of old-fashioned C preprocessors, as 4386*404b540aSrobert opposed to ISO C preprocessors. *Note Traditional Mode::. 4387*404b540aSrobert 4388*404b540aSrobert`-trigraphs' 4389*404b540aSrobert Process trigraph sequences. *Note Initial processing::. 4390*404b540aSrobert 4391*404b540aSrobert`-remap' 4392*404b540aSrobert Enable special code to work around file systems which only permit 4393*404b540aSrobert very short file names, such as MS-DOS. 4394*404b540aSrobert 4395*404b540aSrobert`--help' 4396*404b540aSrobert`--target-help' 4397*404b540aSrobert Print text describing all the command line options instead of 4398*404b540aSrobert preprocessing anything. 4399*404b540aSrobert 4400*404b540aSrobert`-v' 4401*404b540aSrobert Verbose mode. Print out GNU CPP's version number at the beginning 4402*404b540aSrobert of execution, and report the final form of the include path. 4403*404b540aSrobert 4404*404b540aSrobert`-H' 4405*404b540aSrobert Print the name of each header file used, in addition to other 4406*404b540aSrobert normal activities. Each name is indented to show how deep in the 4407*404b540aSrobert `#include' stack it is. Precompiled header files are also 4408*404b540aSrobert printed, even if they are found to be invalid; an invalid 4409*404b540aSrobert precompiled header file is printed with `...x' and a valid one 4410*404b540aSrobert with `...!' . 4411*404b540aSrobert 4412*404b540aSrobert`-version' 4413*404b540aSrobert`--version' 4414*404b540aSrobert Print out GNU CPP's version number. With one dash, proceed to 4415*404b540aSrobert preprocess as normal. With two dashes, exit immediately. 4416*404b540aSrobert 4417*404b540aSrobert 4418*404b540aSrobertFile: cpp.info, Node: Environment Variables, Next: GNU Free Documentation License, Prev: Invocation, Up: Top 4419*404b540aSrobert 4420*404b540aSrobert13 Environment Variables 4421*404b540aSrobert************************ 4422*404b540aSrobert 4423*404b540aSrobertThis section describes the environment variables that affect how CPP 4424*404b540aSrobertoperates. You can use them to specify directories or prefixes to use 4425*404b540aSrobertwhen searching for include files, or to control dependency output. 4426*404b540aSrobert 4427*404b540aSrobert Note that you can also specify places to search using options such as 4428*404b540aSrobert`-I', and control dependency output with options like `-M' (*note 4429*404b540aSrobertInvocation::). These take precedence over environment variables, which 4430*404b540aSrobertin turn take precedence over the configuration of GCC. 4431*404b540aSrobert 4432*404b540aSrobert`CPATH' 4433*404b540aSrobert`C_INCLUDE_PATH' 4434*404b540aSrobert`CPLUS_INCLUDE_PATH' 4435*404b540aSrobert`OBJC_INCLUDE_PATH' 4436*404b540aSrobert Each variable's value is a list of directories separated by a 4437*404b540aSrobert special character, much like `PATH', in which to look for header 4438*404b540aSrobert files. The special character, `PATH_SEPARATOR', is 4439*404b540aSrobert target-dependent and determined at GCC build time. For Microsoft 4440*404b540aSrobert Windows-based targets it is a semicolon, and for almost all other 4441*404b540aSrobert targets it is a colon. 4442*404b540aSrobert 4443*404b540aSrobert `CPATH' specifies a list of directories to be searched as if 4444*404b540aSrobert specified with `-I', but after any paths given with `-I' options 4445*404b540aSrobert on the command line. This environment variable is used regardless 4446*404b540aSrobert of which language is being preprocessed. 4447*404b540aSrobert 4448*404b540aSrobert The remaining environment variables apply only when preprocessing 4449*404b540aSrobert the particular language indicated. Each specifies a list of 4450*404b540aSrobert directories to be searched as if specified with `-isystem', but 4451*404b540aSrobert after any paths given with `-isystem' options on the command line. 4452*404b540aSrobert 4453*404b540aSrobert In all these variables, an empty element instructs the compiler to 4454*404b540aSrobert search its current working directory. Empty elements can appear 4455*404b540aSrobert at the beginning or end of a path. For instance, if the value of 4456*404b540aSrobert `CPATH' is `:/special/include', that has the same effect as 4457*404b540aSrobert `-I. -I/special/include'. 4458*404b540aSrobert 4459*404b540aSrobert See also *Note Search Path::. 4460*404b540aSrobert 4461*404b540aSrobert`DEPENDENCIES_OUTPUT' 4462*404b540aSrobert If this variable is set, its value specifies how to output 4463*404b540aSrobert dependencies for Make based on the non-system header files 4464*404b540aSrobert processed by the compiler. System header files are ignored in the 4465*404b540aSrobert dependency output. 4466*404b540aSrobert 4467*404b540aSrobert The value of `DEPENDENCIES_OUTPUT' can be just a file name, in 4468*404b540aSrobert which case the Make rules are written to that file, guessing the 4469*404b540aSrobert target name from the source file name. Or the value can have the 4470*404b540aSrobert form `FILE TARGET', in which case the rules are written to file 4471*404b540aSrobert FILE using TARGET as the target name. 4472*404b540aSrobert 4473*404b540aSrobert In other words, this environment variable is equivalent to 4474*404b540aSrobert combining the options `-MM' and `-MF' (*note Invocation::), with 4475*404b540aSrobert an optional `-MT' switch too. 4476*404b540aSrobert 4477*404b540aSrobert`SUNPRO_DEPENDENCIES' 4478*404b540aSrobert This variable is the same as `DEPENDENCIES_OUTPUT' (see above), 4479*404b540aSrobert except that system header files are not ignored, so it implies 4480*404b540aSrobert `-M' rather than `-MM'. However, the dependence on the main input 4481*404b540aSrobert file is omitted. *Note Invocation::. 4482*404b540aSrobert 4483*404b540aSrobert 4484*404b540aSrobertFile: cpp.info, Node: GNU Free Documentation License, Next: Index of Directives, Prev: Environment Variables, Up: Top 4485*404b540aSrobert 4486*404b540aSrobertGNU Free Documentation License 4487*404b540aSrobert****************************** 4488*404b540aSrobert 4489*404b540aSrobert Version 1.2, November 2002 4490*404b540aSrobert 4491*404b540aSrobert Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 4492*404b540aSrobert 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA 4493*404b540aSrobert 4494*404b540aSrobert Everyone is permitted to copy and distribute verbatim copies 4495*404b540aSrobert of this license document, but changing it is not allowed. 4496*404b540aSrobert 4497*404b540aSrobert 0. PREAMBLE 4498*404b540aSrobert 4499*404b540aSrobert The purpose of this License is to make a manual, textbook, or other 4500*404b540aSrobert functional and useful document "free" in the sense of freedom: to 4501*404b540aSrobert assure everyone the effective freedom to copy and redistribute it, 4502*404b540aSrobert with or without modifying it, either commercially or 4503*404b540aSrobert noncommercially. Secondarily, this License preserves for the 4504*404b540aSrobert author and publisher a way to get credit for their work, while not 4505*404b540aSrobert being considered responsible for modifications made by others. 4506*404b540aSrobert 4507*404b540aSrobert This License is a kind of "copyleft", which means that derivative 4508*404b540aSrobert works of the document must themselves be free in the same sense. 4509*404b540aSrobert It complements the GNU General Public License, which is a copyleft 4510*404b540aSrobert license designed for free software. 4511*404b540aSrobert 4512*404b540aSrobert We have designed this License in order to use it for manuals for 4513*404b540aSrobert free software, because free software needs free documentation: a 4514*404b540aSrobert free program should come with manuals providing the same freedoms 4515*404b540aSrobert that the software does. But this License is not limited to 4516*404b540aSrobert software manuals; it can be used for any textual work, regardless 4517*404b540aSrobert of subject matter or whether it is published as a printed book. 4518*404b540aSrobert We recommend this License principally for works whose purpose is 4519*404b540aSrobert instruction or reference. 4520*404b540aSrobert 4521*404b540aSrobert 1. APPLICABILITY AND DEFINITIONS 4522*404b540aSrobert 4523*404b540aSrobert This License applies to any manual or other work, in any medium, 4524*404b540aSrobert that contains a notice placed by the copyright holder saying it 4525*404b540aSrobert can be distributed under the terms of this License. Such a notice 4526*404b540aSrobert grants a world-wide, royalty-free license, unlimited in duration, 4527*404b540aSrobert to use that work under the conditions stated herein. The 4528*404b540aSrobert "Document", below, refers to any such manual or work. Any member 4529*404b540aSrobert of the public is a licensee, and is addressed as "you". You 4530*404b540aSrobert accept the license if you copy, modify or distribute the work in a 4531*404b540aSrobert way requiring permission under copyright law. 4532*404b540aSrobert 4533*404b540aSrobert A "Modified Version" of the Document means any work containing the 4534*404b540aSrobert Document or a portion of it, either copied verbatim, or with 4535*404b540aSrobert modifications and/or translated into another language. 4536*404b540aSrobert 4537*404b540aSrobert A "Secondary Section" is a named appendix or a front-matter section 4538*404b540aSrobert of the Document that deals exclusively with the relationship of the 4539*404b540aSrobert publishers or authors of the Document to the Document's overall 4540*404b540aSrobert subject (or to related matters) and contains nothing that could 4541*404b540aSrobert fall directly within that overall subject. (Thus, if the Document 4542*404b540aSrobert is in part a textbook of mathematics, a Secondary Section may not 4543*404b540aSrobert explain any mathematics.) The relationship could be a matter of 4544*404b540aSrobert historical connection with the subject or with related matters, or 4545*404b540aSrobert of legal, commercial, philosophical, ethical or political position 4546*404b540aSrobert regarding them. 4547*404b540aSrobert 4548*404b540aSrobert The "Invariant Sections" are certain Secondary Sections whose 4549*404b540aSrobert titles are designated, as being those of Invariant Sections, in 4550*404b540aSrobert the notice that says that the Document is released under this 4551*404b540aSrobert License. If a section does not fit the above definition of 4552*404b540aSrobert Secondary then it is not allowed to be designated as Invariant. 4553*404b540aSrobert The Document may contain zero Invariant Sections. If the Document 4554*404b540aSrobert does not identify any Invariant Sections then there are none. 4555*404b540aSrobert 4556*404b540aSrobert The "Cover Texts" are certain short passages of text that are 4557*404b540aSrobert listed, as Front-Cover Texts or Back-Cover Texts, in the notice 4558*404b540aSrobert that says that the Document is released under this License. A 4559*404b540aSrobert Front-Cover Text may be at most 5 words, and a Back-Cover Text may 4560*404b540aSrobert be at most 25 words. 4561*404b540aSrobert 4562*404b540aSrobert A "Transparent" copy of the Document means a machine-readable copy, 4563*404b540aSrobert represented in a format whose specification is available to the 4564*404b540aSrobert general public, that is suitable for revising the document 4565*404b540aSrobert straightforwardly with generic text editors or (for images 4566*404b540aSrobert composed of pixels) generic paint programs or (for drawings) some 4567*404b540aSrobert widely available drawing editor, and that is suitable for input to 4568*404b540aSrobert text formatters or for automatic translation to a variety of 4569*404b540aSrobert formats suitable for input to text formatters. A copy made in an 4570*404b540aSrobert otherwise Transparent file format whose markup, or absence of 4571*404b540aSrobert markup, has been arranged to thwart or discourage subsequent 4572*404b540aSrobert modification by readers is not Transparent. An image format is 4573*404b540aSrobert not Transparent if used for any substantial amount of text. A 4574*404b540aSrobert copy that is not "Transparent" is called "Opaque". 4575*404b540aSrobert 4576*404b540aSrobert Examples of suitable formats for Transparent copies include plain 4577*404b540aSrobert ASCII without markup, Texinfo input format, LaTeX input format, 4578*404b540aSrobert SGML or XML using a publicly available DTD, and 4579*404b540aSrobert standard-conforming simple HTML, PostScript or PDF designed for 4580*404b540aSrobert human modification. Examples of transparent image formats include 4581*404b540aSrobert PNG, XCF and JPG. Opaque formats include proprietary formats that 4582*404b540aSrobert can be read and edited only by proprietary word processors, SGML or 4583*404b540aSrobert XML for which the DTD and/or processing tools are not generally 4584*404b540aSrobert available, and the machine-generated HTML, PostScript or PDF 4585*404b540aSrobert produced by some word processors for output purposes only. 4586*404b540aSrobert 4587*404b540aSrobert The "Title Page" means, for a printed book, the title page itself, 4588*404b540aSrobert plus such following pages as are needed to hold, legibly, the 4589*404b540aSrobert material this License requires to appear in the title page. For 4590*404b540aSrobert works in formats which do not have any title page as such, "Title 4591*404b540aSrobert Page" means the text near the most prominent appearance of the 4592*404b540aSrobert work's title, preceding the beginning of the body of the text. 4593*404b540aSrobert 4594*404b540aSrobert A section "Entitled XYZ" means a named subunit of the Document 4595*404b540aSrobert whose title either is precisely XYZ or contains XYZ in parentheses 4596*404b540aSrobert following text that translates XYZ in another language. (Here XYZ 4597*404b540aSrobert stands for a specific section name mentioned below, such as 4598*404b540aSrobert "Acknowledgements", "Dedications", "Endorsements", or "History".) 4599*404b540aSrobert To "Preserve the Title" of such a section when you modify the 4600*404b540aSrobert Document means that it remains a section "Entitled XYZ" according 4601*404b540aSrobert to this definition. 4602*404b540aSrobert 4603*404b540aSrobert The Document may include Warranty Disclaimers next to the notice 4604*404b540aSrobert which states that this License applies to the Document. These 4605*404b540aSrobert Warranty Disclaimers are considered to be included by reference in 4606*404b540aSrobert this License, but only as regards disclaiming warranties: any other 4607*404b540aSrobert implication that these Warranty Disclaimers may have is void and 4608*404b540aSrobert has no effect on the meaning of this License. 4609*404b540aSrobert 4610*404b540aSrobert 2. VERBATIM COPYING 4611*404b540aSrobert 4612*404b540aSrobert You may copy and distribute the Document in any medium, either 4613*404b540aSrobert commercially or noncommercially, provided that this License, the 4614*404b540aSrobert copyright notices, and the license notice saying this License 4615*404b540aSrobert applies to the Document are reproduced in all copies, and that you 4616*404b540aSrobert add no other conditions whatsoever to those of this License. You 4617*404b540aSrobert may not use technical measures to obstruct or control the reading 4618*404b540aSrobert or further copying of the copies you make or distribute. However, 4619*404b540aSrobert you may accept compensation in exchange for copies. If you 4620*404b540aSrobert distribute a large enough number of copies you must also follow 4621*404b540aSrobert the conditions in section 3. 4622*404b540aSrobert 4623*404b540aSrobert You may also lend copies, under the same conditions stated above, 4624*404b540aSrobert and you may publicly display copies. 4625*404b540aSrobert 4626*404b540aSrobert 3. COPYING IN QUANTITY 4627*404b540aSrobert 4628*404b540aSrobert If you publish printed copies (or copies in media that commonly 4629*404b540aSrobert have printed covers) of the Document, numbering more than 100, and 4630*404b540aSrobert the Document's license notice requires Cover Texts, you must 4631*404b540aSrobert enclose the copies in covers that carry, clearly and legibly, all 4632*404b540aSrobert these Cover Texts: Front-Cover Texts on the front cover, and 4633*404b540aSrobert Back-Cover Texts on the back cover. Both covers must also clearly 4634*404b540aSrobert and legibly identify you as the publisher of these copies. The 4635*404b540aSrobert front cover must present the full title with all words of the 4636*404b540aSrobert title equally prominent and visible. You may add other material 4637*404b540aSrobert on the covers in addition. Copying with changes limited to the 4638*404b540aSrobert covers, as long as they preserve the title of the Document and 4639*404b540aSrobert satisfy these conditions, can be treated as verbatim copying in 4640*404b540aSrobert other respects. 4641*404b540aSrobert 4642*404b540aSrobert If the required texts for either cover are too voluminous to fit 4643*404b540aSrobert legibly, you should put the first ones listed (as many as fit 4644*404b540aSrobert reasonably) on the actual cover, and continue the rest onto 4645*404b540aSrobert adjacent pages. 4646*404b540aSrobert 4647*404b540aSrobert If you publish or distribute Opaque copies of the Document 4648*404b540aSrobert numbering more than 100, you must either include a 4649*404b540aSrobert machine-readable Transparent copy along with each Opaque copy, or 4650*404b540aSrobert state in or with each Opaque copy a computer-network location from 4651*404b540aSrobert which the general network-using public has access to download 4652*404b540aSrobert using public-standard network protocols a complete Transparent 4653*404b540aSrobert copy of the Document, free of added material. If you use the 4654*404b540aSrobert latter option, you must take reasonably prudent steps, when you 4655*404b540aSrobert begin distribution of Opaque copies in quantity, to ensure that 4656*404b540aSrobert this Transparent copy will remain thus accessible at the stated 4657*404b540aSrobert location until at least one year after the last time you 4658*404b540aSrobert distribute an Opaque copy (directly or through your agents or 4659*404b540aSrobert retailers) of that edition to the public. 4660*404b540aSrobert 4661*404b540aSrobert It is requested, but not required, that you contact the authors of 4662*404b540aSrobert the Document well before redistributing any large number of 4663*404b540aSrobert copies, to give them a chance to provide you with an updated 4664*404b540aSrobert version of the Document. 4665*404b540aSrobert 4666*404b540aSrobert 4. MODIFICATIONS 4667*404b540aSrobert 4668*404b540aSrobert You may copy and distribute a Modified Version of the Document 4669*404b540aSrobert under the conditions of sections 2 and 3 above, provided that you 4670*404b540aSrobert release the Modified Version under precisely this License, with 4671*404b540aSrobert the Modified Version filling the role of the Document, thus 4672*404b540aSrobert licensing distribution and modification of the Modified Version to 4673*404b540aSrobert whoever possesses a copy of it. In addition, you must do these 4674*404b540aSrobert things in the Modified Version: 4675*404b540aSrobert 4676*404b540aSrobert A. Use in the Title Page (and on the covers, if any) a title 4677*404b540aSrobert distinct from that of the Document, and from those of 4678*404b540aSrobert previous versions (which should, if there were any, be listed 4679*404b540aSrobert in the History section of the Document). You may use the 4680*404b540aSrobert same title as a previous version if the original publisher of 4681*404b540aSrobert that version gives permission. 4682*404b540aSrobert 4683*404b540aSrobert B. List on the Title Page, as authors, one or more persons or 4684*404b540aSrobert entities responsible for authorship of the modifications in 4685*404b540aSrobert the Modified Version, together with at least five of the 4686*404b540aSrobert principal authors of the Document (all of its principal 4687*404b540aSrobert authors, if it has fewer than five), unless they release you 4688*404b540aSrobert from this requirement. 4689*404b540aSrobert 4690*404b540aSrobert C. State on the Title page the name of the publisher of the 4691*404b540aSrobert Modified Version, as the publisher. 4692*404b540aSrobert 4693*404b540aSrobert D. Preserve all the copyright notices of the Document. 4694*404b540aSrobert 4695*404b540aSrobert E. Add an appropriate copyright notice for your modifications 4696*404b540aSrobert adjacent to the other copyright notices. 4697*404b540aSrobert 4698*404b540aSrobert F. Include, immediately after the copyright notices, a license 4699*404b540aSrobert notice giving the public permission to use the Modified 4700*404b540aSrobert Version under the terms of this License, in the form shown in 4701*404b540aSrobert the Addendum below. 4702*404b540aSrobert 4703*404b540aSrobert G. Preserve in that license notice the full lists of Invariant 4704*404b540aSrobert Sections and required Cover Texts given in the Document's 4705*404b540aSrobert license notice. 4706*404b540aSrobert 4707*404b540aSrobert H. Include an unaltered copy of this License. 4708*404b540aSrobert 4709*404b540aSrobert I. Preserve the section Entitled "History", Preserve its Title, 4710*404b540aSrobert and add to it an item stating at least the title, year, new 4711*404b540aSrobert authors, and publisher of the Modified Version as given on 4712*404b540aSrobert the Title Page. If there is no section Entitled "History" in 4713*404b540aSrobert the Document, create one stating the title, year, authors, 4714*404b540aSrobert and publisher of the Document as given on its Title Page, 4715*404b540aSrobert then add an item describing the Modified Version as stated in 4716*404b540aSrobert the previous sentence. 4717*404b540aSrobert 4718*404b540aSrobert J. Preserve the network location, if any, given in the Document 4719*404b540aSrobert for public access to a Transparent copy of the Document, and 4720*404b540aSrobert likewise the network locations given in the Document for 4721*404b540aSrobert previous versions it was based on. These may be placed in 4722*404b540aSrobert the "History" section. You may omit a network location for a 4723*404b540aSrobert work that was published at least four years before the 4724*404b540aSrobert Document itself, or if the original publisher of the version 4725*404b540aSrobert it refers to gives permission. 4726*404b540aSrobert 4727*404b540aSrobert K. For any section Entitled "Acknowledgements" or "Dedications", 4728*404b540aSrobert Preserve the Title of the section, and preserve in the 4729*404b540aSrobert section all the substance and tone of each of the contributor 4730*404b540aSrobert acknowledgements and/or dedications given therein. 4731*404b540aSrobert 4732*404b540aSrobert L. Preserve all the Invariant Sections of the Document, 4733*404b540aSrobert unaltered in their text and in their titles. Section numbers 4734*404b540aSrobert or the equivalent are not considered part of the section 4735*404b540aSrobert titles. 4736*404b540aSrobert 4737*404b540aSrobert M. Delete any section Entitled "Endorsements". Such a section 4738*404b540aSrobert may not be included in the Modified Version. 4739*404b540aSrobert 4740*404b540aSrobert N. Do not retitle any existing section to be Entitled 4741*404b540aSrobert "Endorsements" or to conflict in title with any Invariant 4742*404b540aSrobert Section. 4743*404b540aSrobert 4744*404b540aSrobert O. Preserve any Warranty Disclaimers. 4745*404b540aSrobert 4746*404b540aSrobert If the Modified Version includes new front-matter sections or 4747*404b540aSrobert appendices that qualify as Secondary Sections and contain no 4748*404b540aSrobert material copied from the Document, you may at your option 4749*404b540aSrobert designate some or all of these sections as invariant. To do this, 4750*404b540aSrobert add their titles to the list of Invariant Sections in the Modified 4751*404b540aSrobert Version's license notice. These titles must be distinct from any 4752*404b540aSrobert other section titles. 4753*404b540aSrobert 4754*404b540aSrobert You may add a section Entitled "Endorsements", provided it contains 4755*404b540aSrobert nothing but endorsements of your Modified Version by various 4756*404b540aSrobert parties--for example, statements of peer review or that the text 4757*404b540aSrobert has been approved by an organization as the authoritative 4758*404b540aSrobert definition of a standard. 4759*404b540aSrobert 4760*404b540aSrobert You may add a passage of up to five words as a Front-Cover Text, 4761*404b540aSrobert and a passage of up to 25 words as a Back-Cover Text, to the end 4762*404b540aSrobert of the list of Cover Texts in the Modified Version. Only one 4763*404b540aSrobert passage of Front-Cover Text and one of Back-Cover Text may be 4764*404b540aSrobert added by (or through arrangements made by) any one entity. If the 4765*404b540aSrobert Document already includes a cover text for the same cover, 4766*404b540aSrobert previously added by you or by arrangement made by the same entity 4767*404b540aSrobert you are acting on behalf of, you may not add another; but you may 4768*404b540aSrobert replace the old one, on explicit permission from the previous 4769*404b540aSrobert publisher that added the old one. 4770*404b540aSrobert 4771*404b540aSrobert The author(s) and publisher(s) of the Document do not by this 4772*404b540aSrobert License give permission to use their names for publicity for or to 4773*404b540aSrobert assert or imply endorsement of any Modified Version. 4774*404b540aSrobert 4775*404b540aSrobert 5. COMBINING DOCUMENTS 4776*404b540aSrobert 4777*404b540aSrobert You may combine the Document with other documents released under 4778*404b540aSrobert this License, under the terms defined in section 4 above for 4779*404b540aSrobert modified versions, provided that you include in the combination 4780*404b540aSrobert all of the Invariant Sections of all of the original documents, 4781*404b540aSrobert unmodified, and list them all as Invariant Sections of your 4782*404b540aSrobert combined work in its license notice, and that you preserve all 4783*404b540aSrobert their Warranty Disclaimers. 4784*404b540aSrobert 4785*404b540aSrobert The combined work need only contain one copy of this License, and 4786*404b540aSrobert multiple identical Invariant Sections may be replaced with a single 4787*404b540aSrobert copy. If there are multiple Invariant Sections with the same name 4788*404b540aSrobert but different contents, make the title of each such section unique 4789*404b540aSrobert by adding at the end of it, in parentheses, the name of the 4790*404b540aSrobert original author or publisher of that section if known, or else a 4791*404b540aSrobert unique number. Make the same adjustment to the section titles in 4792*404b540aSrobert the list of Invariant Sections in the license notice of the 4793*404b540aSrobert combined work. 4794*404b540aSrobert 4795*404b540aSrobert In the combination, you must combine any sections Entitled 4796*404b540aSrobert "History" in the various original documents, forming one section 4797*404b540aSrobert Entitled "History"; likewise combine any sections Entitled 4798*404b540aSrobert "Acknowledgements", and any sections Entitled "Dedications". You 4799*404b540aSrobert must delete all sections Entitled "Endorsements." 4800*404b540aSrobert 4801*404b540aSrobert 6. COLLECTIONS OF DOCUMENTS 4802*404b540aSrobert 4803*404b540aSrobert You may make a collection consisting of the Document and other 4804*404b540aSrobert documents released under this License, and replace the individual 4805*404b540aSrobert copies of this License in the various documents with a single copy 4806*404b540aSrobert that is included in the collection, provided that you follow the 4807*404b540aSrobert rules of this License for verbatim copying of each of the 4808*404b540aSrobert documents in all other respects. 4809*404b540aSrobert 4810*404b540aSrobert You may extract a single document from such a collection, and 4811*404b540aSrobert distribute it individually under this License, provided you insert 4812*404b540aSrobert a copy of this License into the extracted document, and follow 4813*404b540aSrobert this License in all other respects regarding verbatim copying of 4814*404b540aSrobert that document. 4815*404b540aSrobert 4816*404b540aSrobert 7. AGGREGATION WITH INDEPENDENT WORKS 4817*404b540aSrobert 4818*404b540aSrobert A compilation of the Document or its derivatives with other 4819*404b540aSrobert separate and independent documents or works, in or on a volume of 4820*404b540aSrobert a storage or distribution medium, is called an "aggregate" if the 4821*404b540aSrobert copyright resulting from the compilation is not used to limit the 4822*404b540aSrobert legal rights of the compilation's users beyond what the individual 4823*404b540aSrobert works permit. When the Document is included in an aggregate, this 4824*404b540aSrobert License does not apply to the other works in the aggregate which 4825*404b540aSrobert are not themselves derivative works of the Document. 4826*404b540aSrobert 4827*404b540aSrobert If the Cover Text requirement of section 3 is applicable to these 4828*404b540aSrobert copies of the Document, then if the Document is less than one half 4829*404b540aSrobert of the entire aggregate, the Document's Cover Texts may be placed 4830*404b540aSrobert on covers that bracket the Document within the aggregate, or the 4831*404b540aSrobert electronic equivalent of covers if the Document is in electronic 4832*404b540aSrobert form. Otherwise they must appear on printed covers that bracket 4833*404b540aSrobert the whole aggregate. 4834*404b540aSrobert 4835*404b540aSrobert 8. TRANSLATION 4836*404b540aSrobert 4837*404b540aSrobert Translation is considered a kind of modification, so you may 4838*404b540aSrobert distribute translations of the Document under the terms of section 4839*404b540aSrobert 4. Replacing Invariant Sections with translations requires special 4840*404b540aSrobert permission from their copyright holders, but you may include 4841*404b540aSrobert translations of some or all Invariant Sections in addition to the 4842*404b540aSrobert original versions of these Invariant Sections. You may include a 4843*404b540aSrobert translation of this License, and all the license notices in the 4844*404b540aSrobert Document, and any Warranty Disclaimers, provided that you also 4845*404b540aSrobert include the original English version of this License and the 4846*404b540aSrobert original versions of those notices and disclaimers. In case of a 4847*404b540aSrobert disagreement between the translation and the original version of 4848*404b540aSrobert this License or a notice or disclaimer, the original version will 4849*404b540aSrobert prevail. 4850*404b540aSrobert 4851*404b540aSrobert If a section in the Document is Entitled "Acknowledgements", 4852*404b540aSrobert "Dedications", or "History", the requirement (section 4) to 4853*404b540aSrobert Preserve its Title (section 1) will typically require changing the 4854*404b540aSrobert actual title. 4855*404b540aSrobert 4856*404b540aSrobert 9. TERMINATION 4857*404b540aSrobert 4858*404b540aSrobert You may not copy, modify, sublicense, or distribute the Document 4859*404b540aSrobert except as expressly provided for under this License. Any other 4860*404b540aSrobert attempt to copy, modify, sublicense or distribute the Document is 4861*404b540aSrobert void, and will automatically terminate your rights under this 4862*404b540aSrobert License. However, parties who have received copies, or rights, 4863*404b540aSrobert from you under this License will not have their licenses 4864*404b540aSrobert terminated so long as such parties remain in full compliance. 4865*404b540aSrobert 4866*404b540aSrobert 10. FUTURE REVISIONS OF THIS LICENSE 4867*404b540aSrobert 4868*404b540aSrobert The Free Software Foundation may publish new, revised versions of 4869*404b540aSrobert the GNU Free Documentation License from time to time. Such new 4870*404b540aSrobert versions will be similar in spirit to the present version, but may 4871*404b540aSrobert differ in detail to address new problems or concerns. See 4872*404b540aSrobert `http://www.gnu.org/copyleft/'. 4873*404b540aSrobert 4874*404b540aSrobert Each version of the License is given a distinguishing version 4875*404b540aSrobert number. If the Document specifies that a particular numbered 4876*404b540aSrobert version of this License "or any later version" applies to it, you 4877*404b540aSrobert have the option of following the terms and conditions either of 4878*404b540aSrobert that specified version or of any later version that has been 4879*404b540aSrobert published (not as a draft) by the Free Software Foundation. If 4880*404b540aSrobert the Document does not specify a version number of this License, 4881*404b540aSrobert you may choose any version ever published (not as a draft) by the 4882*404b540aSrobert Free Software Foundation. 4883*404b540aSrobert 4884*404b540aSrobertADDENDUM: How to use this License for your documents 4885*404b540aSrobert==================================================== 4886*404b540aSrobert 4887*404b540aSrobertTo use this License in a document you have written, include a copy of 4888*404b540aSrobertthe License in the document and put the following copyright and license 4889*404b540aSrobertnotices just after the title page: 4890*404b540aSrobert 4891*404b540aSrobert Copyright (C) YEAR YOUR NAME. 4892*404b540aSrobert Permission is granted to copy, distribute and/or modify this document 4893*404b540aSrobert under the terms of the GNU Free Documentation License, Version 1.2 4894*404b540aSrobert or any later version published by the Free Software Foundation; 4895*404b540aSrobert with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 4896*404b540aSrobert Texts. A copy of the license is included in the section entitled ``GNU 4897*404b540aSrobert Free Documentation License''. 4898*404b540aSrobert 4899*404b540aSrobert If you have Invariant Sections, Front-Cover Texts and Back-Cover 4900*404b540aSrobertTexts, replace the "with...Texts." line with this: 4901*404b540aSrobert 4902*404b540aSrobert with the Invariant Sections being LIST THEIR TITLES, with 4903*404b540aSrobert the Front-Cover Texts being LIST, and with the Back-Cover Texts 4904*404b540aSrobert being LIST. 4905*404b540aSrobert 4906*404b540aSrobert If you have Invariant Sections without Cover Texts, or some other 4907*404b540aSrobertcombination of the three, merge those two alternatives to suit the 4908*404b540aSrobertsituation. 4909*404b540aSrobert 4910*404b540aSrobert If your document contains nontrivial examples of program code, we 4911*404b540aSrobertrecommend releasing these examples in parallel under your choice of 4912*404b540aSrobertfree software license, such as the GNU General Public License, to 4913*404b540aSrobertpermit their use in free software. 4914*404b540aSrobert 4915*404b540aSrobert 4916*404b540aSrobertFile: cpp.info, Node: Index of Directives, Next: Option Index, Prev: GNU Free Documentation License, Up: Top 4917*404b540aSrobert 4918*404b540aSrobertIndex of Directives 4919*404b540aSrobert******************* 4920*404b540aSrobert 4921*404b540aSrobert[index] 4922*404b540aSrobert* Menu: 4923*404b540aSrobert 4924*404b540aSrobert* #assert: Assertions. (line 41) 4925*404b540aSrobert* #define: Object-like Macros. (line 11) 4926*404b540aSrobert* #elif: Elif. (line 6) 4927*404b540aSrobert* #else: Else. (line 6) 4928*404b540aSrobert* #endif: Ifdef. (line 6) 4929*404b540aSrobert* #error: Diagnostics. (line 6) 4930*404b540aSrobert* #ident: Other Directives. (line 6) 4931*404b540aSrobert* #if: Conditional Syntax. (line 6) 4932*404b540aSrobert* #ifdef: Ifdef. (line 6) 4933*404b540aSrobert* #ifndef: Ifdef. (line 40) 4934*404b540aSrobert* #import: Obsolete once-only headers. 4935*404b540aSrobert (line 10) 4936*404b540aSrobert* #include: Include Syntax. (line 6) 4937*404b540aSrobert* #include_next: Wrapper Headers. (line 6) 4938*404b540aSrobert* #line: Line Control. (line 20) 4939*404b540aSrobert* #pragma GCC dependency: Pragmas. (line 53) 4940*404b540aSrobert* #pragma GCC poison: Pragmas. (line 65) 4941*404b540aSrobert* #pragma GCC system_header <1>: Pragmas. (line 92) 4942*404b540aSrobert* #pragma GCC system_header: System Headers. (line 31) 4943*404b540aSrobert* #sccs: Other Directives. (line 6) 4944*404b540aSrobert* #unassert: Assertions. (line 52) 4945*404b540aSrobert* #undef: Undefining and Redefining Macros. 4946*404b540aSrobert (line 6) 4947*404b540aSrobert* #warning: Diagnostics. (line 27) 4948*404b540aSrobert 4949*404b540aSrobert 4950*404b540aSrobertFile: cpp.info, Node: Option Index, Next: Concept Index, Prev: Index of Directives, Up: Top 4951*404b540aSrobert 4952*404b540aSrobertOption Index 4953*404b540aSrobert************ 4954*404b540aSrobert 4955*404b540aSrobertCPP's command line options and environment variables are indexed here 4956*404b540aSrobertwithout any initial `-' or `--'. 4957*404b540aSrobert 4958*404b540aSrobert[index] 4959*404b540aSrobert* Menu: 4960*404b540aSrobert 4961*404b540aSrobert* A: Invocation. (line 494) 4962*404b540aSrobert* ansi: Invocation. (line 307) 4963*404b540aSrobert* C: Invocation. (line 542) 4964*404b540aSrobert* C_INCLUDE_PATH: Environment Variables. 4965*404b540aSrobert (line 16) 4966*404b540aSrobert* CPATH: Environment Variables. 4967*404b540aSrobert (line 15) 4968*404b540aSrobert* CPLUS_INCLUDE_PATH: Environment Variables. 4969*404b540aSrobert (line 17) 4970*404b540aSrobert* D: Invocation. (line 39) 4971*404b540aSrobert* dD: Invocation. (line 522) 4972*404b540aSrobert* DEPENDENCIES_OUTPUT: Environment Variables. 4973*404b540aSrobert (line 44) 4974*404b540aSrobert* dI: Invocation. (line 531) 4975*404b540aSrobert* dM: Invocation. (line 510) 4976*404b540aSrobert* dN: Invocation. (line 528) 4977*404b540aSrobert* fdollars-in-identifiers: Invocation. (line 424) 4978*404b540aSrobert* fexec-charset: Invocation. (line 451) 4979*404b540aSrobert* fextended-identifiers: Invocation. (line 427) 4980*404b540aSrobert* finput-charset: Invocation. (line 464) 4981*404b540aSrobert* fno-show-column: Invocation. (line 489) 4982*404b540aSrobert* fno-working-directory: Invocation. (line 474) 4983*404b540aSrobert* fpreprocessed: Invocation. (line 432) 4984*404b540aSrobert* ftabstop: Invocation. (line 445) 4985*404b540aSrobert* fwide-exec-charset: Invocation. (line 456) 4986*404b540aSrobert* fworking-directory: Invocation. (line 474) 4987*404b540aSrobert* H: Invocation. (line 587) 4988*404b540aSrobert* help: Invocation. (line 579) 4989*404b540aSrobert* I: Invocation. (line 71) 4990*404b540aSrobert* I-: Invocation. (line 344) 4991*404b540aSrobert* idirafter: Invocation. (line 386) 4992*404b540aSrobert* imacros: Invocation. (line 377) 4993*404b540aSrobert* imultilib: Invocation. (line 407) 4994*404b540aSrobert* include: Invocation. (line 366) 4995*404b540aSrobert* iprefix: Invocation. (line 391) 4996*404b540aSrobert* iquote: Invocation. (line 418) 4997*404b540aSrobert* isysroot: Invocation. (line 403) 4998*404b540aSrobert* isystem: Invocation. (line 411) 4999*404b540aSrobert* iwithprefix: Invocation. (line 397) 5000*404b540aSrobert* iwithprefixbefore: Invocation. (line 397) 5001*404b540aSrobert* M: Invocation. (line 181) 5002*404b540aSrobert* MD: Invocation. (line 269) 5003*404b540aSrobert* MF: Invocation. (line 215) 5004*404b540aSrobert* MG: Invocation. (line 224) 5005*404b540aSrobert* MM: Invocation. (line 205) 5006*404b540aSrobert* MMD: Invocation. (line 284) 5007*404b540aSrobert* MP: Invocation. (line 234) 5008*404b540aSrobert* MQ: Invocation. (line 260) 5009*404b540aSrobert* MT: Invocation. (line 246) 5010*404b540aSrobert* nostdinc: Invocation. (line 356) 5011*404b540aSrobert* nostdinc++: Invocation. (line 361) 5012*404b540aSrobert* o: Invocation. (line 80) 5013*404b540aSrobert* OBJC_INCLUDE_PATH: Environment Variables. 5014*404b540aSrobert (line 18) 5015*404b540aSrobert* P: Invocation. (line 535) 5016*404b540aSrobert* pedantic: Invocation. (line 171) 5017*404b540aSrobert* pedantic-errors: Invocation. (line 176) 5018*404b540aSrobert* remap: Invocation. (line 574) 5019*404b540aSrobert* std=: Invocation. (line 307) 5020*404b540aSrobert* SUNPRO_DEPENDENCIES: Environment Variables. 5021*404b540aSrobert (line 60) 5022*404b540aSrobert* target-help: Invocation. (line 579) 5023*404b540aSrobert* traditional-cpp: Invocation. (line 567) 5024*404b540aSrobert* trigraphs: Invocation. (line 571) 5025*404b540aSrobert* U: Invocation. (line 62) 5026*404b540aSrobert* undef: Invocation. (line 66) 5027*404b540aSrobert* v: Invocation. (line 583) 5028*404b540aSrobert* version: Invocation. (line 596) 5029*404b540aSrobert* w: Invocation. (line 167) 5030*404b540aSrobert* Wall: Invocation. (line 86) 5031*404b540aSrobert* Wcomment: Invocation. (line 94) 5032*404b540aSrobert* Wcomments: Invocation. (line 94) 5033*404b540aSrobert* Wendif-labels: Invocation. (line 144) 5034*404b540aSrobert* Werror: Invocation. (line 157) 5035*404b540aSrobert* Wimport: Invocation. (line 117) 5036*404b540aSrobert* Wsystem-headers: Invocation. (line 161) 5037*404b540aSrobert* Wtraditional: Invocation. (line 111) 5038*404b540aSrobert* Wtrigraphs: Invocation. (line 99) 5039*404b540aSrobert* Wundef: Invocation. (line 120) 5040*404b540aSrobert* Wunused-macros: Invocation. (line 125) 5041*404b540aSrobert* x: Invocation. (line 291) 5042*404b540aSrobert 5043*404b540aSrobert 5044*404b540aSrobertFile: cpp.info, Node: Concept Index, Prev: Option Index, Up: Top 5045*404b540aSrobert 5046*404b540aSrobertConcept Index 5047*404b540aSrobert************* 5048*404b540aSrobert 5049*404b540aSrobert[index] 5050*404b540aSrobert* Menu: 5051*404b540aSrobert 5052*404b540aSrobert* # operator: Stringification. (line 6) 5053*404b540aSrobert* ## operator: Concatenation. (line 6) 5054*404b540aSrobert* _Pragma: Pragmas. (line 25) 5055*404b540aSrobert* alternative tokens: Tokenization. (line 106) 5056*404b540aSrobert* arguments: Macro Arguments. (line 6) 5057*404b540aSrobert* arguments in macro definitions: Macro Arguments. (line 6) 5058*404b540aSrobert* assertions: Assertions. (line 6) 5059*404b540aSrobert* assertions, canceling: Assertions. (line 52) 5060*404b540aSrobert* backslash-newline: Initial processing. (line 61) 5061*404b540aSrobert* block comments: Initial processing. (line 77) 5062*404b540aSrobert* C++ named operators: C++ Named Operators. (line 6) 5063*404b540aSrobert* character constants: Tokenization. (line 85) 5064*404b540aSrobert* character set, execution: Invocation. (line 451) 5065*404b540aSrobert* character set, input: Invocation. (line 464) 5066*404b540aSrobert* character set, wide execution: Invocation. (line 456) 5067*404b540aSrobert* command line: Invocation. (line 6) 5068*404b540aSrobert* commenting out code: Deleted Code. (line 6) 5069*404b540aSrobert* comments: Initial processing. (line 77) 5070*404b540aSrobert* common predefined macros: Common Predefined Macros. 5071*404b540aSrobert (line 6) 5072*404b540aSrobert* computed includes: Computed Includes. (line 6) 5073*404b540aSrobert* concatenation: Concatenation. (line 6) 5074*404b540aSrobert* conditional group: Ifdef. (line 14) 5075*404b540aSrobert* conditionals: Conditionals. (line 6) 5076*404b540aSrobert* continued lines: Initial processing. (line 61) 5077*404b540aSrobert* controlling macro: Once-Only Headers. (line 35) 5078*404b540aSrobert* defined: Defined. (line 6) 5079*404b540aSrobert* dependencies for make as output: Environment Variables. 5080*404b540aSrobert (line 45) 5081*404b540aSrobert* dependencies, make: Invocation. (line 181) 5082*404b540aSrobert* diagnostic: Diagnostics. (line 6) 5083*404b540aSrobert* differences from previous versions: Differences from previous versions. 5084*404b540aSrobert (line 6) 5085*404b540aSrobert* digraphs: Tokenization. (line 106) 5086*404b540aSrobert* directive line: The preprocessing language. 5087*404b540aSrobert (line 6) 5088*404b540aSrobert* directive name: The preprocessing language. 5089*404b540aSrobert (line 6) 5090*404b540aSrobert* directives: The preprocessing language. 5091*404b540aSrobert (line 6) 5092*404b540aSrobert* empty macro arguments: Macro Arguments. (line 66) 5093*404b540aSrobert* environment variables: Environment Variables. 5094*404b540aSrobert (line 6) 5095*404b540aSrobert* expansion of arguments: Argument Prescan. (line 6) 5096*404b540aSrobert* FDL, GNU Free Documentation License: GNU Free Documentation License. 5097*404b540aSrobert (line 6) 5098*404b540aSrobert* function-like macros: Function-like Macros. 5099*404b540aSrobert (line 6) 5100*404b540aSrobert* grouping options: Invocation. (line 34) 5101*404b540aSrobert* guard macro: Once-Only Headers. (line 35) 5102*404b540aSrobert* header file: Header Files. (line 6) 5103*404b540aSrobert* header file names: Tokenization. (line 85) 5104*404b540aSrobert* identifiers: Tokenization. (line 34) 5105*404b540aSrobert* implementation limits: Implementation limits. 5106*404b540aSrobert (line 6) 5107*404b540aSrobert* implementation-defined behavior: Implementation-defined behavior. 5108*404b540aSrobert (line 6) 5109*404b540aSrobert* including just once: Once-Only Headers. (line 6) 5110*404b540aSrobert* invocation: Invocation. (line 6) 5111*404b540aSrobert* iso646.h: C++ Named Operators. (line 6) 5112*404b540aSrobert* line comments: Initial processing. (line 77) 5113*404b540aSrobert* line control: Line Control. (line 6) 5114*404b540aSrobert* line endings: Initial processing. (line 14) 5115*404b540aSrobert* linemarkers: Preprocessor Output. (line 28) 5116*404b540aSrobert* macro argument expansion: Argument Prescan. (line 6) 5117*404b540aSrobert* macro arguments and directives: Directives Within Macro Arguments. 5118*404b540aSrobert (line 6) 5119*404b540aSrobert* macros in include: Computed Includes. (line 6) 5120*404b540aSrobert* macros with arguments: Macro Arguments. (line 6) 5121*404b540aSrobert* macros with variable arguments: Variadic Macros. (line 6) 5122*404b540aSrobert* make: Invocation. (line 181) 5123*404b540aSrobert* manifest constants: Object-like Macros. (line 6) 5124*404b540aSrobert* named operators: C++ Named Operators. (line 6) 5125*404b540aSrobert* newlines in macro arguments: Newlines in Arguments. 5126*404b540aSrobert (line 6) 5127*404b540aSrobert* null directive: Other Directives. (line 15) 5128*404b540aSrobert* numbers: Tokenization. (line 61) 5129*404b540aSrobert* object-like macro: Object-like Macros. (line 6) 5130*404b540aSrobert* options: Invocation. (line 38) 5131*404b540aSrobert* options, grouping: Invocation. (line 34) 5132*404b540aSrobert* other tokens: Tokenization. (line 120) 5133*404b540aSrobert* output format: Preprocessor Output. (line 12) 5134*404b540aSrobert* overriding a header file: Wrapper Headers. (line 6) 5135*404b540aSrobert* parentheses in macro bodies: Operator Precedence Problems. 5136*404b540aSrobert (line 6) 5137*404b540aSrobert* pitfalls of macros: Macro Pitfalls. (line 6) 5138*404b540aSrobert* predefined macros: Predefined Macros. (line 6) 5139*404b540aSrobert* predefined macros, system-specific: System-specific Predefined Macros. 5140*404b540aSrobert (line 6) 5141*404b540aSrobert* predicates: Assertions. (line 19) 5142*404b540aSrobert* preprocessing directives: The preprocessing language. 5143*404b540aSrobert (line 6) 5144*404b540aSrobert* preprocessing numbers: Tokenization. (line 61) 5145*404b540aSrobert* preprocessing tokens: Tokenization. (line 6) 5146*404b540aSrobert* prescan of macro arguments: Argument Prescan. (line 6) 5147*404b540aSrobert* problems with macros: Macro Pitfalls. (line 6) 5148*404b540aSrobert* punctuators: Tokenization. (line 106) 5149*404b540aSrobert* redefining macros: Undefining and Redefining Macros. 5150*404b540aSrobert (line 6) 5151*404b540aSrobert* repeated inclusion: Once-Only Headers. (line 6) 5152*404b540aSrobert* reporting errors: Diagnostics. (line 6) 5153*404b540aSrobert* reporting warnings: Diagnostics. (line 6) 5154*404b540aSrobert* reserved namespace: System-specific Predefined Macros. 5155*404b540aSrobert (line 6) 5156*404b540aSrobert* self-reference: Self-Referential Macros. 5157*404b540aSrobert (line 6) 5158*404b540aSrobert* semicolons (after macro calls): Swallowing the Semicolon. 5159*404b540aSrobert (line 6) 5160*404b540aSrobert* side effects (in macro arguments): Duplication of Side Effects. 5161*404b540aSrobert (line 6) 5162*404b540aSrobert* standard predefined macros.: Standard Predefined Macros. 5163*404b540aSrobert (line 6) 5164*404b540aSrobert* string constants: Tokenization. (line 85) 5165*404b540aSrobert* string literals: Tokenization. (line 85) 5166*404b540aSrobert* stringification: Stringification. (line 6) 5167*404b540aSrobert* symbolic constants: Object-like Macros. (line 6) 5168*404b540aSrobert* system header files <1>: System Headers. (line 6) 5169*404b540aSrobert* system header files: Header Files. (line 13) 5170*404b540aSrobert* system-specific predefined macros: System-specific Predefined Macros. 5171*404b540aSrobert (line 6) 5172*404b540aSrobert* testing predicates: Assertions. (line 30) 5173*404b540aSrobert* token concatenation: Concatenation. (line 6) 5174*404b540aSrobert* token pasting: Concatenation. (line 6) 5175*404b540aSrobert* tokens: Tokenization. (line 6) 5176*404b540aSrobert* trigraphs: Initial processing. (line 32) 5177*404b540aSrobert* undefining macros: Undefining and Redefining Macros. 5178*404b540aSrobert (line 6) 5179*404b540aSrobert* unsafe macros: Duplication of Side Effects. 5180*404b540aSrobert (line 6) 5181*404b540aSrobert* variable number of arguments: Variadic Macros. (line 6) 5182*404b540aSrobert* variadic macros: Variadic Macros. (line 6) 5183*404b540aSrobert* wrapper #ifndef: Once-Only Headers. (line 6) 5184*404b540aSrobert* wrapper headers: Wrapper Headers. (line 6) 5185*404b540aSrobert 5186*404b540aSrobert 5187*404b540aSrobert 5188*404b540aSrobertTag Table: 5189*404b540aSrobertNode: Top1094 5190*404b540aSrobertNode: Overview3778 5191*404b540aSrobertNode: Character sets6599 5192*404b540aSrobertRef: Character sets-Footnote-18782 5193*404b540aSrobertNode: Initial processing8963 5194*404b540aSrobertRef: trigraphs10522 5195*404b540aSrobertNode: Tokenization14724 5196*404b540aSrobertRef: Tokenization-Footnote-121860 5197*404b540aSrobertNode: The preprocessing language21971 5198*404b540aSrobertNode: Header Files24849 5199*404b540aSrobertNode: Include Syntax26729 5200*404b540aSrobertNode: Include Operation28366 5201*404b540aSrobertNode: Search Path30214 5202*404b540aSrobertNode: Once-Only Headers33404 5203*404b540aSrobertNode: Computed Includes35049 5204*404b540aSrobertNode: Wrapper Headers38193 5205*404b540aSrobertNode: System Headers40619 5206*404b540aSrobertNode: Macros42669 5207*404b540aSrobertNode: Object-like Macros43810 5208*404b540aSrobertNode: Function-like Macros47400 5209*404b540aSrobertNode: Macro Arguments49016 5210*404b540aSrobertNode: Stringification53161 5211*404b540aSrobertNode: Concatenation56367 5212*404b540aSrobertNode: Variadic Macros59475 5213*404b540aSrobertNode: Predefined Macros64262 5214*404b540aSrobertNode: Standard Predefined Macros64850 5215*404b540aSrobertNode: Common Predefined Macros70786 5216*404b540aSrobertNode: System-specific Predefined Macros81678 5217*404b540aSrobertNode: C++ Named Operators83699 5218*404b540aSrobertNode: Undefining and Redefining Macros84663 5219*404b540aSrobertNode: Directives Within Macro Arguments86767 5220*404b540aSrobertNode: Macro Pitfalls88315 5221*404b540aSrobertNode: Misnesting88848 5222*404b540aSrobertNode: Operator Precedence Problems89960 5223*404b540aSrobertNode: Swallowing the Semicolon91826 5224*404b540aSrobertNode: Duplication of Side Effects93849 5225*404b540aSrobertNode: Self-Referential Macros96032 5226*404b540aSrobertNode: Argument Prescan98441 5227*404b540aSrobertNode: Newlines in Arguments102195 5228*404b540aSrobertNode: Conditionals103146 5229*404b540aSrobertNode: Conditional Uses104976 5230*404b540aSrobertNode: Conditional Syntax106334 5231*404b540aSrobertNode: Ifdef106654 5232*404b540aSrobertNode: If109815 5233*404b540aSrobertNode: Defined112119 5234*404b540aSrobertNode: Else113402 5235*404b540aSrobertNode: Elif113972 5236*404b540aSrobertNode: Deleted Code115261 5237*404b540aSrobertNode: Diagnostics116508 5238*404b540aSrobertNode: Line Control118125 5239*404b540aSrobertNode: Pragmas121929 5240*404b540aSrobertNode: Other Directives126199 5241*404b540aSrobertNode: Preprocessor Output127249 5242*404b540aSrobertNode: Traditional Mode130450 5243*404b540aSrobertNode: Traditional lexical analysis131508 5244*404b540aSrobertNode: Traditional macros134011 5245*404b540aSrobertNode: Traditional miscellany137813 5246*404b540aSrobertNode: Traditional warnings138810 5247*404b540aSrobertNode: Implementation Details141007 5248*404b540aSrobertNode: Implementation-defined behavior141628 5249*404b540aSrobertRef: Identifier characters142361 5250*404b540aSrobertNode: Implementation limits145446 5251*404b540aSrobertNode: Obsolete Features148120 5252*404b540aSrobertNode: Assertions148575 5253*404b540aSrobertNode: Obsolete once-only headers151116 5254*404b540aSrobertNode: Differences from previous versions152851 5255*404b540aSrobertNode: Invocation157059 5256*404b540aSrobertRef: Wtrigraphs161390 5257*404b540aSrobertRef: dashMF166174 5258*404b540aSrobertRef: fdollars-in-identifiers174196 5259*404b540aSrobertNode: Environment Variables181849 5260*404b540aSrobertNode: GNU Free Documentation License184815 5261*404b540aSrobertNode: Index of Directives207248 5262*404b540aSrobertNode: Option Index209177 5263*404b540aSrobertNode: Concept Index215288 5264*404b540aSrobert 5265*404b540aSrobertEnd Tag Table 5266