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