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