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