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, 76C++, and Objective-C programs before they are compiled. It can also be 77useful on its 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, C++, and 190Objective-C source code. In the past, it has been abused as a general 191text processor. It will choke on input which does not obey C's lexical 192rules. For example, apostrophes will be interpreted as the beginning of 193character constants, and cause errors. Also, you cannot rely on it 194preserving characteristics of the input which are not significant to 195C-family languages. If a Makefile is preprocessed, all the hard tabs 196will be removed, 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++ or Objective-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 __OBJC__ 1899This macro is defined, with value 1, when the Objective-C compiler is in 1900use. You can use @code{__OBJC__} to test whether a header is compiled 1901by a C compiler or a Objective-C compiler. 1902 1903@item __ASSEMBLER__ 1904This macro is defined with value 1 when preprocessing assembly 1905language. 1906 1907@end table 1908 1909@node Common Predefined Macros 1910@subsection Common Predefined Macros 1911@cindex common predefined macros 1912 1913The common predefined macros are GNU C extensions. They are available 1914with the same meanings regardless of the machine or operating system on 1915which you are using GNU C@. Their names all start with double 1916underscores. 1917 1918@table @code 1919 1920@item __GNUC__ 1921@itemx __GNUC_MINOR__ 1922@itemx __GNUC_PATCHLEVEL__ 1923These macros are defined by all GNU compilers that use the C 1924preprocessor: C, C++, and Objective-C@. Their values are the major 1925version, minor version, and patch level of the compiler, as integer 1926constants. For example, GCC 3.2.1 will define @code{__GNUC__} to 3, 1927@code{__GNUC_MINOR__} to 2, and @code{__GNUC_PATCHLEVEL__} to 1. These 1928macros are also defined if you invoke the preprocessor directly. 1929 1930@code{__GNUC_PATCHLEVEL__} is new to GCC 3.0; it is also present in the 1931widely-used development snapshots leading up to 3.0 (which identify 1932themselves as GCC 2.96 or 2.97, depending on which snapshot you have). 1933 1934If all you need to know is whether or not your program is being compiled 1935by GCC, or a non-GCC compiler that claims to accept the GNU C dialects, 1936you can simply test @code{__GNUC__}. If you need to write code 1937which depends on a specific version, you must be more careful. Each 1938time the minor version is increased, the patch level is reset to zero; 1939each time the major version is increased (which happens rarely), the 1940minor version and patch level are reset. If you wish to use the 1941predefined macros directly in the conditional, you will need to write it 1942like this: 1943 1944@smallexample 1945/* @r{Test for GCC > 3.2.0} */ 1946#if __GNUC__ > 3 || \ 1947 (__GNUC__ == 3 && (__GNUC_MINOR__ > 2 || \ 1948 (__GNUC_MINOR__ == 2 && \ 1949 __GNUC_PATCHLEVEL__ > 0)) 1950@end smallexample 1951 1952@noindent 1953Another approach is to use the predefined macros to 1954calculate a single number, then compare that against a threshold: 1955 1956@smallexample 1957#define GCC_VERSION (__GNUC__ * 10000 \ 1958 + __GNUC_MINOR__ * 100 \ 1959 + __GNUC_PATCHLEVEL__) 1960@dots{} 1961/* @r{Test for GCC > 3.2.0} */ 1962#if GCC_VERSION > 30200 1963@end smallexample 1964 1965@noindent 1966Many people find this form easier to understand. 1967 1968@item __GNUG__ 1969The GNU C++ compiler defines this. Testing it is equivalent to 1970testing @code{@w{(__GNUC__ && __cplusplus)}}. 1971 1972@item __STRICT_ANSI__ 1973GCC defines this macro if and only if the @option{-ansi} switch, or a 1974@option{-std} switch specifying strict conformance to some version of ISO C, 1975was specified when GCC was invoked. It is defined to @samp{1}. 1976This macro exists primarily to direct GNU libc's header files to 1977restrict their definitions to the minimal set found in the 1989 C 1978standard. 1979 1980@item __BASE_FILE__ 1981This macro expands to the name of the main input file, in the form 1982of a C string constant. This is the source file that was specified 1983on the command line of the preprocessor or C compiler. 1984 1985@item __INCLUDE_LEVEL__ 1986This macro expands to a decimal integer constant that represents the 1987depth of nesting in include files. The value of this macro is 1988incremented on every @samp{#include} directive and decremented at the 1989end of every included file. It starts out at 0, it's value within the 1990base file specified on the command line. 1991 1992@item __ELF__ 1993This macro is defined if the target uses the ELF object format. 1994 1995@item __VERSION__ 1996This macro expands to a string constant which describes the version of 1997the compiler in use. You should not rely on its contents having any 1998particular form, but it can be counted on to contain at least the 1999release number. 2000 2001@item __OPTIMIZE__ 2002@itemx __OPTIMIZE_SIZE__ 2003@itemx __NO_INLINE__ 2004These macros describe the compilation mode. @code{__OPTIMIZE__} is 2005defined in all optimizing compilations. @code{__OPTIMIZE_SIZE__} is 2006defined if the compiler is optimizing for size, not speed. 2007@code{__NO_INLINE__} is defined if no functions will be inlined into 2008their callers (when not optimizing, or when inlining has been 2009specifically disabled by @option{-fno-inline}). 2010 2011These macros cause certain GNU header files to provide optimized 2012definitions, using macros or inline functions, of system library 2013functions. You should not use these macros in any way unless you make 2014sure that programs will execute with the same effect whether or not they 2015are defined. If they are defined, their value is 1. 2016 2017@item __GNUC_GNU_INLINE__ 2018GCC defines this macro if functions declared @code{inline} will be 2019handled in GCC's traditional gnu89 mode. In this mode an @code{extern 2020inline} function will never be compiled as a standalone function, and 2021an @code{inline} function which is neither @code{extern} nor 2022@code{static} will always be compiled as a standalone function. 2023 2024@item __GNUC_STDC_INLINE__ 2025GCC defines this macro if functions declared @code{inline} will be 2026handled according to the ISO C99 standard. In this mode an 2027@code{extern inline} function will always be compiled as a standalone 2028externally visible function, and an @code{inline} function which is 2029neither @code{extern} nor @code{static} will never be compiled as a 2030standalone function. 2031 2032If this macro is defined, GCC supports the @code{gnu_inline} function 2033attribute as a way to always get the gnu89 behaviour. Support for 2034this and @code{__GNUC_GNU_INLINE__} was added in GCC 4.1.3. If 2035neither macro is defined, an older version of GCC is being used: 2036@code{inline} functions will be compiled in gnu89 mode, and the 2037@code{gnu_inline} function attribute will not be recognized. 2038 2039@item __CHAR_UNSIGNED__ 2040GCC defines this macro if and only if the data type @code{char} is 2041unsigned on the target machine. It exists to cause the standard header 2042file @file{limits.h} to work correctly. You should not use this macro 2043yourself; instead, refer to the standard macros defined in @file{limits.h}. 2044 2045@item __WCHAR_UNSIGNED__ 2046Like @code{__CHAR_UNSIGNED__}, this macro is defined if and only if the 2047data type @code{wchar_t} is unsigned and the front-end is in C++ mode. 2048 2049@item __REGISTER_PREFIX__ 2050This macro expands to a single token (not a string constant) which is 2051the prefix applied to CPU register names in assembly language for this 2052target. You can use it to write assembly that is usable in multiple 2053environments. For example, in the @code{m68k-aout} environment it 2054expands to nothing, but in the @code{m68k-coff} environment it expands 2055to a single @samp{%}. 2056 2057@item __USER_LABEL_PREFIX__ 2058This macro expands to a single token which is the prefix applied to 2059user labels (symbols visible to C code) in assembly. For example, in 2060the @code{m68k-aout} environment it expands to an @samp{_}, but in the 2061@code{m68k-coff} environment it expands to nothing. 2062 2063This macro will have the correct definition even if 2064@option{-f(no-)underscores} is in use, but it will not be correct if 2065target-specific options that adjust this prefix are used (e.g.@: the 2066OSF/rose @option{-mno-underscores} option). 2067 2068@item __SIZE_TYPE__ 2069@itemx __PTRDIFF_TYPE__ 2070@itemx __WCHAR_TYPE__ 2071@itemx __WINT_TYPE__ 2072@itemx __INTMAX_TYPE__ 2073@itemx __UINTMAX_TYPE__ 2074These macros are defined to the correct underlying types for the 2075@code{size_t}, @code{ptrdiff_t}, @code{wchar_t}, @code{wint_t}, 2076@code{intmax_t}, and @code{uintmax_t} 2077typedefs, respectively. They exist to make the standard header files 2078@file{stddef.h} and @file{wchar.h} work correctly. You should not use 2079these macros directly; instead, include the appropriate headers and use 2080the typedefs. 2081 2082@item __CHAR_BIT__ 2083Defined to the number of bits used in the representation of the 2084@code{char} data type. It exists to make the standard header given 2085numerical limits work correctly. You should not use 2086this macro directly; instead, include the appropriate headers. 2087 2088@item __SCHAR_MAX__ 2089@itemx __WCHAR_MAX__ 2090@itemx __SHRT_MAX__ 2091@itemx __INT_MAX__ 2092@itemx __LONG_MAX__ 2093@itemx __LONG_LONG_MAX__ 2094@itemx __INTMAX_MAX__ 2095Defined to the maximum value of the @code{signed char}, @code{wchar_t}, 2096@code{signed short}, 2097@code{signed int}, @code{signed long}, @code{signed long long}, and 2098@code{intmax_t} types 2099respectively. They exist to make the standard header given numerical limits 2100work correctly. You should not use these macros directly; instead, include 2101the appropriate headers. 2102 2103@item __DEPRECATED 2104This macro is defined, with value 1, when compiling a C++ source file 2105with warnings about deprecated constructs enabled. These warnings are 2106enabled by default, but can be disabled with @option{-Wno-deprecated}. 2107 2108@item __EXCEPTIONS 2109This macro is defined, with value 1, when compiling a C++ source file 2110with exceptions enabled. If @option{-fno-exceptions} was used when 2111compiling the file, then this macro will not be defined. 2112 2113@item __USING_SJLJ_EXCEPTIONS__ 2114This macro is defined, with value 1, if the compiler uses the old 2115mechanism based on @code{setjmp} and @code{longjmp} for exception 2116handling. 2117 2118@item __GXX_WEAK__ 2119This macro is defined when compiling a C++ source file. It has the 2120value 1 if the compiler will use weak symbols, COMDAT sections, or 2121other similar techniques to collapse symbols with ``vague linkage'' 2122that are defined in multiple translation units. If the compiler will 2123not collapse such symbols, this macro is defined with value 0. In 2124general, user code should not need to make use of this macro; the 2125purpose of this macro is to ease implementation of the C++ runtime 2126library provided with G++. 2127 2128@item __NEXT_RUNTIME__ 2129This macro is defined, with value 1, if (and only if) the NeXT runtime 2130(as in @option{-fnext-runtime}) is in use for Objective-C@. If the GNU 2131runtime is used, this macro is not defined, so that you can use this 2132macro to determine which runtime (NeXT or GNU) is being used. 2133 2134@item __LP64__ 2135@itemx _LP64 2136These macros are defined, with value 1, if (and only if) the compilation 2137is for a target where @code{long int} and pointer both use 64-bits and 2138@code{int} uses 32-bit. 2139 2140@item __SSP__ 2141This macro is defined, with value 1, when @option{-fstack-protector} is in 2142use. 2143 2144@item __SSP_ALL__ 2145This macro is defined, with value 2, when @option{-fstack-protector-all} is 2146in use. 2147 2148@item __TIMESTAMP__ 2149This macro expands to a string constant that describes the date and time 2150of the last modification of the current source file. The string constant 2151contains abbreviated day of the week, month, day of the month, time in 2152hh:mm:ss form, year and looks like @code{@w{"Sun Sep 16 01:03:52 1973"}}. 2153If the day of the month is less than 10, it is padded with a space on the left. 2154 2155If GCC cannot determine the current date, it will emit a warning message 2156(once per compilation) and @code{__TIMESTAMP__} will expand to 2157@code{@w{"??? ??? ?? ??:??:?? ????"}}. 2158 2159@end table 2160 2161@node System-specific Predefined Macros 2162@subsection System-specific Predefined Macros 2163 2164@cindex system-specific predefined macros 2165@cindex predefined macros, system-specific 2166@cindex reserved namespace 2167 2168The C preprocessor normally predefines several macros that indicate what 2169type of system and machine is in use. They are obviously different on 2170each target supported by GCC@. This manual, being for all systems and 2171machines, cannot tell you what their names are, but you can use 2172@command{cpp -dM} to see them all. @xref{Invocation}. All system-specific 2173predefined macros expand to the constant 1, so you can test them with 2174either @samp{#ifdef} or @samp{#if}. 2175 2176The C standard requires that all system-specific macros be part of the 2177@dfn{reserved namespace}. All names which begin with two underscores, 2178or an underscore and a capital letter, are reserved for the compiler and 2179library to use as they wish. However, historically system-specific 2180macros have had names with no special prefix; for instance, it is common 2181to find @code{unix} defined on Unix systems. For all such macros, GCC 2182provides a parallel macro with two underscores added at the beginning 2183and the end. If @code{unix} is defined, @code{__unix__} will be defined 2184too. There will never be more than two underscores; the parallel of 2185@code{_mips} is @code{__mips__}. 2186 2187When the @option{-ansi} option, or any @option{-std} option that 2188requests strict conformance, is given to the compiler, all the 2189system-specific predefined macros outside the reserved namespace are 2190suppressed. The parallel macros, inside the reserved namespace, remain 2191defined. 2192 2193We are slowly phasing out all predefined macros which are outside the 2194reserved namespace. You should never use them in new programs, and we 2195encourage you to correct older code to use the parallel macros whenever 2196you find it. We don't recommend you use the system-specific macros that 2197are in the reserved namespace, either. It is better in the long run to 2198check specifically for features you need, using a tool such as 2199@command{autoconf}. 2200 2201@node C++ Named Operators 2202@subsection C++ Named Operators 2203@cindex named operators 2204@cindex C++ named operators 2205@cindex iso646.h 2206 2207In C++, there are eleven keywords which are simply alternate spellings 2208of operators normally written with punctuation. These keywords are 2209treated as such even in the preprocessor. They function as operators in 2210@samp{#if}, and they cannot be defined as macros or poisoned. In C, you 2211can request that those keywords take their C++ meaning by including 2212@file{iso646.h}. That header defines each one as a normal object-like 2213macro expanding to the appropriate punctuator. 2214 2215These are the named operators and their corresponding punctuators: 2216 2217@multitable {Named Operator} {Punctuator} 2218@item Named Operator @tab Punctuator 2219@item @code{and} @tab @code{&&} 2220@item @code{and_eq} @tab @code{&=} 2221@item @code{bitand} @tab @code{&} 2222@item @code{bitor} @tab @code{|} 2223@item @code{compl} @tab @code{~} 2224@item @code{not} @tab @code{!} 2225@item @code{not_eq} @tab @code{!=} 2226@item @code{or} @tab @code{||} 2227@item @code{or_eq} @tab @code{|=} 2228@item @code{xor} @tab @code{^} 2229@item @code{xor_eq} @tab @code{^=} 2230@end multitable 2231 2232@node Undefining and Redefining Macros 2233@section Undefining and Redefining Macros 2234@cindex undefining macros 2235@cindex redefining macros 2236@findex #undef 2237 2238If a macro ceases to be useful, it may be @dfn{undefined} with the 2239@samp{#undef} directive. @samp{#undef} takes a single argument, the 2240name of the macro to undefine. You use the bare macro name, even if the 2241macro is function-like. It is an error if anything appears on the line 2242after the macro name. @samp{#undef} has no effect if the name is not a 2243macro. 2244 2245@smallexample 2246#define FOO 4 2247x = FOO; @expansion{} x = 4; 2248#undef FOO 2249x = FOO; @expansion{} x = FOO; 2250@end smallexample 2251 2252Once a macro has been undefined, that identifier may be @dfn{redefined} 2253as a macro by a subsequent @samp{#define} directive. The new definition 2254need not have any resemblance to the old definition. 2255 2256However, if an identifier which is currently a macro is redefined, then 2257the new definition must be @dfn{effectively the same} as the old one. 2258Two macro definitions are effectively the same if: 2259@itemize @bullet 2260@item Both are the same type of macro (object- or function-like). 2261@item All the tokens of the replacement list are the same. 2262@item If there are any parameters, they are the same. 2263@item Whitespace appears in the same places in both. It need not be 2264exactly the same amount of whitespace, though. Remember that comments 2265count as whitespace. 2266@end itemize 2267 2268@noindent 2269These definitions are effectively the same: 2270@smallexample 2271#define FOUR (2 + 2) 2272#define FOUR (2 + 2) 2273#define FOUR (2 /* @r{two} */ + 2) 2274@end smallexample 2275@noindent 2276but these are not: 2277@smallexample 2278#define FOUR (2 + 2) 2279#define FOUR ( 2+2 ) 2280#define FOUR (2 * 2) 2281#define FOUR(score,and,seven,years,ago) (2 + 2) 2282@end smallexample 2283 2284If a macro is redefined with a definition that is not effectively the 2285same as the old one, the preprocessor issues a warning and changes the 2286macro to use the new definition. If the new definition is effectively 2287the same, the redefinition is silently ignored. This allows, for 2288instance, two different headers to define a common macro. The 2289preprocessor will only complain if the definitions do not match. 2290 2291@node Directives Within Macro Arguments 2292@section Directives Within Macro Arguments 2293@cindex macro arguments and directives 2294 2295Occasionally it is convenient to use preprocessor directives within 2296the arguments of a macro. The C and C++ standards declare that 2297behavior in these cases is undefined. 2298 2299Versions of CPP prior to 3.2 would reject such constructs with an 2300error message. This was the only syntactic difference between normal 2301functions and function-like macros, so it seemed attractive to remove 2302this limitation, and people would often be surprised that they could 2303not use macros in this way. Moreover, sometimes people would use 2304conditional compilation in the argument list to a normal library 2305function like @samp{printf}, only to find that after a library upgrade 2306@samp{printf} had changed to be a function-like macro, and their code 2307would no longer compile. So from version 3.2 we changed CPP to 2308successfully process arbitrary directives within macro arguments in 2309exactly the same way as it would have processed the directive were the 2310function-like macro invocation not present. 2311 2312If, within a macro invocation, that macro is redefined, then the new 2313definition takes effect in time for argument pre-expansion, but the 2314original definition is still used for argument replacement. Here is a 2315pathological example: 2316 2317@smallexample 2318#define f(x) x x 2319f (1 2320#undef f 2321#define f 2 2322f) 2323@end smallexample 2324 2325@noindent 2326which expands to 2327 2328@smallexample 23291 2 1 2 2330@end smallexample 2331 2332@noindent 2333with the semantics described above. 2334 2335@node Macro Pitfalls 2336@section Macro Pitfalls 2337@cindex problems with macros 2338@cindex pitfalls of macros 2339 2340In this section we describe some special rules that apply to macros and 2341macro expansion, and point out certain cases in which the rules have 2342counter-intuitive consequences that you must watch out for. 2343 2344@menu 2345* Misnesting:: 2346* Operator Precedence Problems:: 2347* Swallowing the Semicolon:: 2348* Duplication of Side Effects:: 2349* Self-Referential Macros:: 2350* Argument Prescan:: 2351* Newlines in Arguments:: 2352@end menu 2353 2354@node Misnesting 2355@subsection Misnesting 2356 2357When a macro is called with arguments, the arguments are substituted 2358into the macro body and the result is checked, together with the rest of 2359the input file, for more macro calls. It is possible to piece together 2360a macro call coming partially from the macro body and partially from the 2361arguments. For example, 2362 2363@smallexample 2364#define twice(x) (2*(x)) 2365#define call_with_1(x) x(1) 2366call_with_1 (twice) 2367 @expansion{} twice(1) 2368 @expansion{} (2*(1)) 2369@end smallexample 2370 2371Macro definitions do not have to have balanced parentheses. By writing 2372an unbalanced open parenthesis in a macro body, it is possible to create 2373a macro call that begins inside the macro body but ends outside of it. 2374For example, 2375 2376@smallexample 2377#define strange(file) fprintf (file, "%s %d", 2378@dots{} 2379strange(stderr) p, 35) 2380 @expansion{} fprintf (stderr, "%s %d", p, 35) 2381@end smallexample 2382 2383The ability to piece together a macro call can be useful, but the use of 2384unbalanced open parentheses in a macro body is just confusing, and 2385should be avoided. 2386 2387@node Operator Precedence Problems 2388@subsection Operator Precedence Problems 2389@cindex parentheses in macro bodies 2390 2391You may have noticed that in most of the macro definition examples shown 2392above, each occurrence of a macro argument name had parentheses around 2393it. In addition, another pair of parentheses usually surround the 2394entire macro definition. Here is why it is best to write macros that 2395way. 2396 2397Suppose you define a macro as follows, 2398 2399@smallexample 2400#define ceil_div(x, y) (x + y - 1) / y 2401@end smallexample 2402 2403@noindent 2404whose purpose is to divide, rounding up. (One use for this operation is 2405to compute how many @code{int} objects are needed to hold a certain 2406number of @code{char} objects.) Then suppose it is used as follows: 2407 2408@smallexample 2409a = ceil_div (b & c, sizeof (int)); 2410 @expansion{} a = (b & c + sizeof (int) - 1) / sizeof (int); 2411@end smallexample 2412 2413@noindent 2414This does not do what is intended. The operator-precedence rules of 2415C make it equivalent to this: 2416 2417@smallexample 2418a = (b & (c + sizeof (int) - 1)) / sizeof (int); 2419@end smallexample 2420 2421@noindent 2422What we want is this: 2423 2424@smallexample 2425a = ((b & c) + sizeof (int) - 1)) / sizeof (int); 2426@end smallexample 2427 2428@noindent 2429Defining the macro as 2430 2431@smallexample 2432#define ceil_div(x, y) ((x) + (y) - 1) / (y) 2433@end smallexample 2434 2435@noindent 2436provides the desired result. 2437 2438Unintended grouping can result in another way. Consider @code{sizeof 2439ceil_div(1, 2)}. That has the appearance of a C expression that would 2440compute the size of the type of @code{ceil_div (1, 2)}, but in fact it 2441means something very different. Here is what it expands to: 2442 2443@smallexample 2444sizeof ((1) + (2) - 1) / (2) 2445@end smallexample 2446 2447@noindent 2448This would take the size of an integer and divide it by two. The 2449precedence rules have put the division outside the @code{sizeof} when it 2450was intended to be inside. 2451 2452Parentheses around the entire macro definition prevent such problems. 2453Here, then, is the recommended way to define @code{ceil_div}: 2454 2455@smallexample 2456#define ceil_div(x, y) (((x) + (y) - 1) / (y)) 2457@end smallexample 2458 2459@node Swallowing the Semicolon 2460@subsection Swallowing the Semicolon 2461@cindex semicolons (after macro calls) 2462 2463Often it is desirable to define a macro that expands into a compound 2464statement. Consider, for example, the following macro, that advances a 2465pointer (the argument @code{p} says where to find it) across whitespace 2466characters: 2467 2468@smallexample 2469#define SKIP_SPACES(p, limit) \ 2470@{ char *lim = (limit); \ 2471 while (p < lim) @{ \ 2472 if (*p++ != ' ') @{ \ 2473 p--; break; @}@}@} 2474@end smallexample 2475 2476@noindent 2477Here backslash-newline is used to split the macro definition, which must 2478be a single logical line, so that it resembles the way such code would 2479be laid out if not part of a macro definition. 2480 2481A call to this macro might be @code{SKIP_SPACES (p, lim)}. Strictly 2482speaking, the call expands to a compound statement, which is a complete 2483statement with no need for a semicolon to end it. However, since it 2484looks like a function call, it minimizes confusion if you can use it 2485like a function call, writing a semicolon afterward, as in 2486@code{SKIP_SPACES (p, lim);} 2487 2488This can cause trouble before @code{else} statements, because the 2489semicolon is actually a null statement. Suppose you write 2490 2491@smallexample 2492if (*p != 0) 2493 SKIP_SPACES (p, lim); 2494else @dots{} 2495@end smallexample 2496 2497@noindent 2498The presence of two statements---the compound statement and a null 2499statement---in between the @code{if} condition and the @code{else} 2500makes invalid C code. 2501 2502The definition of the macro @code{SKIP_SPACES} can be altered to solve 2503this problem, using a @code{do @dots{} while} statement. Here is how: 2504 2505@smallexample 2506#define SKIP_SPACES(p, limit) \ 2507do @{ char *lim = (limit); \ 2508 while (p < lim) @{ \ 2509 if (*p++ != ' ') @{ \ 2510 p--; break; @}@}@} \ 2511while (0) 2512@end smallexample 2513 2514Now @code{SKIP_SPACES (p, lim);} expands into 2515 2516@smallexample 2517do @{@dots{}@} while (0); 2518@end smallexample 2519 2520@noindent 2521which is one statement. The loop executes exactly once; most compilers 2522generate no extra code for it. 2523 2524@node Duplication of Side Effects 2525@subsection Duplication of Side Effects 2526 2527@cindex side effects (in macro arguments) 2528@cindex unsafe macros 2529Many C programs define a macro @code{min}, for ``minimum'', like this: 2530 2531@smallexample 2532#define min(X, Y) ((X) < (Y) ? (X) : (Y)) 2533@end smallexample 2534 2535When you use this macro with an argument containing a side effect, 2536as shown here, 2537 2538@smallexample 2539next = min (x + y, foo (z)); 2540@end smallexample 2541 2542@noindent 2543it expands as follows: 2544 2545@smallexample 2546next = ((x + y) < (foo (z)) ? (x + y) : (foo (z))); 2547@end smallexample 2548 2549@noindent 2550where @code{x + y} has been substituted for @code{X} and @code{foo (z)} 2551for @code{Y}. 2552 2553The function @code{foo} is used only once in the statement as it appears 2554in the program, but the expression @code{foo (z)} has been substituted 2555twice into the macro expansion. As a result, @code{foo} might be called 2556two times when the statement is executed. If it has side effects or if 2557it takes a long time to compute, the results might not be what you 2558intended. We say that @code{min} is an @dfn{unsafe} macro. 2559 2560The best solution to this problem is to define @code{min} in a way that 2561computes the value of @code{foo (z)} only once. The C language offers 2562no standard way to do this, but it can be done with GNU extensions as 2563follows: 2564 2565@smallexample 2566#define min(X, Y) \ 2567(@{ typeof (X) x_ = (X); \ 2568 typeof (Y) y_ = (Y); \ 2569 (x_ < y_) ? x_ : y_; @}) 2570@end smallexample 2571 2572The @samp{(@{ @dots{} @})} notation produces a compound statement that 2573acts as an expression. Its value is the value of its last statement. 2574This permits us to define local variables and assign each argument to 2575one. The local variables have underscores after their names to reduce 2576the risk of conflict with an identifier of wider scope (it is impossible 2577to avoid this entirely). Now each argument is evaluated exactly once. 2578 2579If you do not wish to use GNU C extensions, the only solution is to be 2580careful when @emph{using} the macro @code{min}. For example, you can 2581calculate the value of @code{foo (z)}, save it in a variable, and use 2582that variable in @code{min}: 2583 2584@smallexample 2585@group 2586#define min(X, Y) ((X) < (Y) ? (X) : (Y)) 2587@dots{} 2588@{ 2589 int tem = foo (z); 2590 next = min (x + y, tem); 2591@} 2592@end group 2593@end smallexample 2594 2595@noindent 2596(where we assume that @code{foo} returns type @code{int}). 2597 2598@node Self-Referential Macros 2599@subsection Self-Referential Macros 2600@cindex self-reference 2601 2602A @dfn{self-referential} macro is one whose name appears in its 2603definition. Recall that all macro definitions are rescanned for more 2604macros to replace. If the self-reference were considered a use of the 2605macro, it would produce an infinitely large expansion. To prevent this, 2606the self-reference is not considered a macro call. It is passed into 2607the preprocessor output unchanged. Consider an example: 2608 2609@smallexample 2610#define foo (4 + foo) 2611@end smallexample 2612 2613@noindent 2614where @code{foo} is also a variable in your program. 2615 2616Following the ordinary rules, each reference to @code{foo} will expand 2617into @code{(4 + foo)}; then this will be rescanned and will expand into 2618@code{(4 + (4 + foo))}; and so on until the computer runs out of memory. 2619 2620The self-reference rule cuts this process short after one step, at 2621@code{(4 + foo)}. Therefore, this macro definition has the possibly 2622useful effect of causing the program to add 4 to the value of @code{foo} 2623wherever @code{foo} is referred to. 2624 2625In most cases, it is a bad idea to take advantage of this feature. A 2626person reading the program who sees that @code{foo} is a variable will 2627not expect that it is a macro as well. The reader will come across the 2628identifier @code{foo} in the program and think its value should be that 2629of the variable @code{foo}, whereas in fact the value is four greater. 2630 2631One common, useful use of self-reference is to create a macro which 2632expands to itself. If you write 2633 2634@smallexample 2635#define EPERM EPERM 2636@end smallexample 2637 2638@noindent 2639then the macro @code{EPERM} expands to @code{EPERM}. Effectively, it is 2640left alone by the preprocessor whenever it's used in running text. You 2641can tell that it's a macro with @samp{#ifdef}. You might do this if you 2642want to define numeric constants with an @code{enum}, but have 2643@samp{#ifdef} be true for each constant. 2644 2645If a macro @code{x} expands to use a macro @code{y}, and the expansion of 2646@code{y} refers to the macro @code{x}, that is an @dfn{indirect 2647self-reference} of @code{x}. @code{x} is not expanded in this case 2648either. Thus, if we have 2649 2650@smallexample 2651#define x (4 + y) 2652#define y (2 * x) 2653@end smallexample 2654 2655@noindent 2656then @code{x} and @code{y} expand as follows: 2657 2658@smallexample 2659@group 2660x @expansion{} (4 + y) 2661 @expansion{} (4 + (2 * x)) 2662 2663y @expansion{} (2 * x) 2664 @expansion{} (2 * (4 + y)) 2665@end group 2666@end smallexample 2667 2668@noindent 2669Each macro is expanded when it appears in the definition of the other 2670macro, but not when it indirectly appears in its own definition. 2671 2672@node Argument Prescan 2673@subsection Argument Prescan 2674@cindex expansion of arguments 2675@cindex macro argument expansion 2676@cindex prescan of macro arguments 2677 2678Macro arguments are completely macro-expanded before they are 2679substituted into a macro body, unless they are stringified or pasted 2680with other tokens. After substitution, the entire macro body, including 2681the substituted arguments, is scanned again for macros to be expanded. 2682The result is that the arguments are scanned @emph{twice} to expand 2683macro calls in them. 2684 2685Most of the time, this has no effect. If the argument contained any 2686macro calls, they are expanded during the first scan. The result 2687therefore contains no macro calls, so the second scan does not change 2688it. If the argument were substituted as given, with no prescan, the 2689single remaining scan would find the same macro calls and produce the 2690same results. 2691 2692You might expect the double scan to change the results when a 2693self-referential macro is used in an argument of another macro 2694(@pxref{Self-Referential Macros}): the self-referential macro would be 2695expanded once in the first scan, and a second time in the second scan. 2696However, this is not what happens. The self-references that do not 2697expand in the first scan are marked so that they will not expand in the 2698second scan either. 2699 2700You might wonder, ``Why mention the prescan, if it makes no difference? 2701And why not skip it and make the preprocessor faster?'' The answer is 2702that the prescan does make a difference in three special cases: 2703 2704@itemize @bullet 2705@item 2706Nested calls to a macro. 2707 2708We say that @dfn{nested} calls to a macro occur when a macro's argument 2709contains a call to that very macro. For example, if @code{f} is a macro 2710that expects one argument, @code{f (f (1))} is a nested pair of calls to 2711@code{f}. The desired expansion is made by expanding @code{f (1)} and 2712substituting that into the definition of @code{f}. The prescan causes 2713the expected result to happen. Without the prescan, @code{f (1)} itself 2714would be substituted as an argument, and the inner use of @code{f} would 2715appear during the main scan as an indirect self-reference and would not 2716be expanded. 2717 2718@item 2719Macros that call other macros that stringify or concatenate. 2720 2721If an argument is stringified or concatenated, the prescan does not 2722occur. If you @emph{want} to expand a macro, then stringify or 2723concatenate its expansion, you can do that by causing one macro to call 2724another macro that does the stringification or concatenation. For 2725instance, if you have 2726 2727@smallexample 2728#define AFTERX(x) X_ ## x 2729#define XAFTERX(x) AFTERX(x) 2730#define TABLESIZE 1024 2731#define BUFSIZE TABLESIZE 2732@end smallexample 2733 2734then @code{AFTERX(BUFSIZE)} expands to @code{X_BUFSIZE}, and 2735@code{XAFTERX(BUFSIZE)} expands to @code{X_1024}. (Not to 2736@code{X_TABLESIZE}. Prescan always does a complete expansion.) 2737 2738@item 2739Macros used in arguments, whose expansions contain unshielded commas. 2740 2741This can cause a macro expanded on the second scan to be called with the 2742wrong number of arguments. Here is an example: 2743 2744@smallexample 2745#define foo a,b 2746#define bar(x) lose(x) 2747#define lose(x) (1 + (x)) 2748@end smallexample 2749 2750We would like @code{bar(foo)} to turn into @code{(1 + (foo))}, which 2751would then turn into @code{(1 + (a,b))}. Instead, @code{bar(foo)} 2752expands into @code{lose(a,b)}, and you get an error because @code{lose} 2753requires a single argument. In this case, the problem is easily solved 2754by the same parentheses that ought to be used to prevent misnesting of 2755arithmetic operations: 2756 2757@smallexample 2758#define foo (a,b) 2759@exdent or 2760#define bar(x) lose((x)) 2761@end smallexample 2762 2763The extra pair of parentheses prevents the comma in @code{foo}'s 2764definition from being interpreted as an argument separator. 2765 2766@end itemize 2767 2768@node Newlines in Arguments 2769@subsection Newlines in Arguments 2770@cindex newlines in macro arguments 2771 2772The invocation of a function-like macro can extend over many logical 2773lines. However, in the present implementation, the entire expansion 2774comes out on one line. Thus line numbers emitted by the compiler or 2775debugger refer to the line the invocation started on, which might be 2776different to the line containing the argument causing the problem. 2777 2778Here is an example illustrating this: 2779 2780@smallexample 2781#define ignore_second_arg(a,b,c) a; c 2782 2783ignore_second_arg (foo (), 2784 ignored (), 2785 syntax error); 2786@end smallexample 2787 2788@noindent 2789The syntax error triggered by the tokens @code{syntax error} results in 2790an error message citing line three---the line of ignore_second_arg--- 2791even though the problematic code comes from line five. 2792 2793We consider this a bug, and intend to fix it in the near future. 2794 2795@node Conditionals 2796@chapter Conditionals 2797@cindex conditionals 2798 2799A @dfn{conditional} is a directive that instructs the preprocessor to 2800select whether or not to include a chunk of code in the final token 2801stream passed to the compiler. Preprocessor conditionals can test 2802arithmetic expressions, or whether a name is defined as a macro, or both 2803simultaneously using the special @code{defined} operator. 2804 2805A conditional in the C preprocessor resembles in some ways an @code{if} 2806statement in C, but it is important to understand the difference between 2807them. The condition in an @code{if} statement is tested during the 2808execution of your program. Its purpose is to allow your program to 2809behave differently from run to run, depending on the data it is 2810operating on. The condition in a preprocessing conditional directive is 2811tested when your program is compiled. Its purpose is to allow different 2812code to be included in the program depending on the situation at the 2813time of compilation. 2814 2815However, the distinction is becoming less clear. Modern compilers often 2816do test @code{if} statements when a program is compiled, if their 2817conditions are known not to vary at run time, and eliminate code which 2818can never be executed. If you can count on your compiler to do this, 2819you may find that your program is more readable if you use @code{if} 2820statements with constant conditions (perhaps determined by macros). Of 2821course, you can only use this to exclude code, not type definitions or 2822other preprocessing directives, and you can only do it if the code 2823remains syntactically valid when it is not to be used. 2824 2825GCC version 3 eliminates this kind of never-executed code even when 2826not optimizing. Older versions did it only when optimizing. 2827 2828@menu 2829* Conditional Uses:: 2830* Conditional Syntax:: 2831* Deleted Code:: 2832@end menu 2833 2834@node Conditional Uses 2835@section Conditional Uses 2836 2837There are three general reasons to use a conditional. 2838 2839@itemize @bullet 2840@item 2841A program may need to use different code depending on the machine or 2842operating system it is to run on. In some cases the code for one 2843operating system may be erroneous on another operating system; for 2844example, it might refer to data types or constants that do not exist on 2845the other system. When this happens, it is not enough to avoid 2846executing the invalid code. Its mere presence will cause the compiler 2847to reject the program. With a preprocessing conditional, the offending 2848code can be effectively excised from the program when it is not valid. 2849 2850@item 2851You may want to be able to compile the same source file into two 2852different programs. One version might make frequent time-consuming 2853consistency checks on its intermediate data, or print the values of 2854those data for debugging, and the other not. 2855 2856@item 2857A conditional whose condition is always false is one way to exclude code 2858from the program but keep it as a sort of comment for future reference. 2859@end itemize 2860 2861Simple programs that do not need system-specific logic or complex 2862debugging hooks generally will not need to use preprocessing 2863conditionals. 2864 2865@node Conditional Syntax 2866@section Conditional Syntax 2867 2868@findex #if 2869A conditional in the C preprocessor begins with a @dfn{conditional 2870directive}: @samp{#if}, @samp{#ifdef} or @samp{#ifndef}. 2871 2872@menu 2873* Ifdef:: 2874* If:: 2875* Defined:: 2876* Else:: 2877* Elif:: 2878@end menu 2879 2880@node Ifdef 2881@subsection Ifdef 2882@findex #ifdef 2883@findex #endif 2884 2885The simplest sort of conditional is 2886 2887@smallexample 2888@group 2889#ifdef @var{MACRO} 2890 2891@var{controlled text} 2892 2893#endif /* @var{MACRO} */ 2894@end group 2895@end smallexample 2896 2897@cindex conditional group 2898This block is called a @dfn{conditional group}. @var{controlled text} 2899will be included in the output of the preprocessor if and only if 2900@var{MACRO} is defined. We say that the conditional @dfn{succeeds} if 2901@var{MACRO} is defined, @dfn{fails} if it is not. 2902 2903The @var{controlled text} inside of a conditional can include 2904preprocessing directives. They are executed only if the conditional 2905succeeds. You can nest conditional groups inside other conditional 2906groups, but they must be completely nested. In other words, 2907@samp{#endif} always matches the nearest @samp{#ifdef} (or 2908@samp{#ifndef}, or @samp{#if}). Also, you cannot start a conditional 2909group in one file and end it in another. 2910 2911Even if a conditional fails, the @var{controlled text} inside it is 2912still run through initial transformations and tokenization. Therefore, 2913it must all be lexically valid C@. Normally the only way this matters is 2914that all comments and string literals inside a failing conditional group 2915must still be properly ended. 2916 2917The comment following the @samp{#endif} is not required, but it is a 2918good practice if there is a lot of @var{controlled text}, because it 2919helps people match the @samp{#endif} to the corresponding @samp{#ifdef}. 2920Older programs sometimes put @var{MACRO} directly after the 2921@samp{#endif} without enclosing it in a comment. This is invalid code 2922according to the C standard. CPP accepts it with a warning. It 2923never affects which @samp{#ifndef} the @samp{#endif} matches. 2924 2925@findex #ifndef 2926Sometimes you wish to use some code if a macro is @emph{not} defined. 2927You can do this by writing @samp{#ifndef} instead of @samp{#ifdef}. 2928One common use of @samp{#ifndef} is to include code only the first 2929time a header file is included. @xref{Once-Only Headers}. 2930 2931Macro definitions can vary between compilations for several reasons. 2932Here are some samples. 2933 2934@itemize @bullet 2935@item 2936Some macros are predefined on each kind of machine 2937(@pxref{System-specific Predefined Macros}). This allows you to provide 2938code specially tuned for a particular machine. 2939 2940@item 2941System header files define more macros, associated with the features 2942they implement. You can test these macros with conditionals to avoid 2943using a system feature on a machine where it is not implemented. 2944 2945@item 2946Macros can be defined or undefined with the @option{-D} and @option{-U} 2947command line options when you compile the program. You can arrange to 2948compile the same source file into two different programs by choosing a 2949macro name to specify which program you want, writing conditionals to 2950test whether or how this macro is defined, and then controlling the 2951state of the macro with command line options, perhaps set in the 2952Makefile. @xref{Invocation}. 2953 2954@item 2955Your program might have a special header file (often called 2956@file{config.h}) that is adjusted when the program is compiled. It can 2957define or not define macros depending on the features of the system and 2958the desired capabilities of the program. The adjustment can be 2959automated by a tool such as @command{autoconf}, or done by hand. 2960@end itemize 2961 2962@node If 2963@subsection If 2964 2965The @samp{#if} directive allows you to test the value of an arithmetic 2966expression, rather than the mere existence of one macro. Its syntax is 2967 2968@smallexample 2969@group 2970#if @var{expression} 2971 2972@var{controlled text} 2973 2974#endif /* @var{expression} */ 2975@end group 2976@end smallexample 2977 2978@var{expression} is a C expression of integer type, subject to stringent 2979restrictions. It may contain 2980 2981@itemize @bullet 2982@item 2983Integer constants. 2984 2985@item 2986Character constants, which are interpreted as they would be in normal 2987code. 2988 2989@item 2990Arithmetic operators for addition, subtraction, multiplication, 2991division, bitwise operations, shifts, comparisons, and logical 2992operations (@code{&&} and @code{||}). The latter two obey the usual 2993short-circuiting rules of standard C@. 2994 2995@item 2996Macros. All macros in the expression are expanded before actual 2997computation of the expression's value begins. 2998 2999@item 3000Uses of the @code{defined} operator, which lets you check whether macros 3001are defined in the middle of an @samp{#if}. 3002 3003@item 3004Identifiers that are not macros, which are all considered to be the 3005number zero. This allows you to write @code{@w{#if MACRO}} instead of 3006@code{@w{#ifdef MACRO}}, if you know that MACRO, when defined, will 3007always have a nonzero value. Function-like macros used without their 3008function call parentheses are also treated as zero. 3009 3010In some contexts this shortcut is undesirable. The @option{-Wundef} 3011option causes GCC to warn whenever it encounters an identifier which is 3012not a macro in an @samp{#if}. 3013@end itemize 3014 3015The preprocessor does not know anything about types in the language. 3016Therefore, @code{sizeof} operators are not recognized in @samp{#if}, and 3017neither are @code{enum} constants. They will be taken as identifiers 3018which are not macros, and replaced by zero. In the case of 3019@code{sizeof}, this is likely to cause the expression to be invalid. 3020 3021The preprocessor calculates the value of @var{expression}. It carries 3022out all calculations in the widest integer type known to the compiler; 3023on most machines supported by GCC this is 64 bits. This is not the same 3024rule as the compiler uses to calculate the value of a constant 3025expression, and may give different results in some cases. If the value 3026comes out to be nonzero, the @samp{#if} succeeds and the @var{controlled 3027text} is included; otherwise it is skipped. 3028 3029@node Defined 3030@subsection Defined 3031 3032@cindex @code{defined} 3033The special operator @code{defined} is used in @samp{#if} and 3034@samp{#elif} expressions to test whether a certain name is defined as a 3035macro. @code{defined @var{name}} and @code{defined (@var{name})} are 3036both expressions whose value is 1 if @var{name} is defined as a macro at 3037the current point in the program, and 0 otherwise. Thus, @code{@w{#if 3038defined MACRO}} is precisely equivalent to @code{@w{#ifdef MACRO}}. 3039 3040@code{defined} is useful when you wish to test more than one macro for 3041existence at once. For example, 3042 3043@smallexample 3044#if defined (__vax__) || defined (__ns16000__) 3045@end smallexample 3046 3047@noindent 3048would succeed if either of the names @code{__vax__} or 3049@code{__ns16000__} is defined as a macro. 3050 3051Conditionals written like this: 3052 3053@smallexample 3054#if defined BUFSIZE && BUFSIZE >= 1024 3055@end smallexample 3056 3057@noindent 3058can generally be simplified to just @code{@w{#if BUFSIZE >= 1024}}, 3059since if @code{BUFSIZE} is not defined, it will be interpreted as having 3060the value zero. 3061 3062If the @code{defined} operator appears as a result of a macro expansion, 3063the C standard says the behavior is undefined. GNU cpp treats it as a 3064genuine @code{defined} operator and evaluates it normally. It will warn 3065wherever your code uses this feature if you use the command-line option 3066@option{-pedantic}, since other compilers may handle it differently. 3067 3068@node Else 3069@subsection Else 3070 3071@findex #else 3072The @samp{#else} directive can be added to a conditional to provide 3073alternative text to be used if the condition fails. This is what it 3074looks like: 3075 3076@smallexample 3077@group 3078#if @var{expression} 3079@var{text-if-true} 3080#else /* Not @var{expression} */ 3081@var{text-if-false} 3082#endif /* Not @var{expression} */ 3083@end group 3084@end smallexample 3085 3086@noindent 3087If @var{expression} is nonzero, the @var{text-if-true} is included and 3088the @var{text-if-false} is skipped. If @var{expression} is zero, the 3089opposite happens. 3090 3091You can use @samp{#else} with @samp{#ifdef} and @samp{#ifndef}, too. 3092 3093@node Elif 3094@subsection Elif 3095 3096@findex #elif 3097One common case of nested conditionals is used to check for more than two 3098possible alternatives. For example, you might have 3099 3100@smallexample 3101#if X == 1 3102@dots{} 3103#else /* X != 1 */ 3104#if X == 2 3105@dots{} 3106#else /* X != 2 */ 3107@dots{} 3108#endif /* X != 2 */ 3109#endif /* X != 1 */ 3110@end smallexample 3111 3112Another conditional directive, @samp{#elif}, allows this to be 3113abbreviated as follows: 3114 3115@smallexample 3116#if X == 1 3117@dots{} 3118#elif X == 2 3119@dots{} 3120#else /* X != 2 and X != 1*/ 3121@dots{} 3122#endif /* X != 2 and X != 1*/ 3123@end smallexample 3124 3125@samp{#elif} stands for ``else if''. Like @samp{#else}, it goes in the 3126middle of a conditional group and subdivides it; it does not require a 3127matching @samp{#endif} of its own. Like @samp{#if}, the @samp{#elif} 3128directive includes an expression to be tested. The text following the 3129@samp{#elif} is processed only if the original @samp{#if}-condition 3130failed and the @samp{#elif} condition succeeds. 3131 3132More than one @samp{#elif} can go in the same conditional group. Then 3133the text after each @samp{#elif} is processed only if the @samp{#elif} 3134condition succeeds after the original @samp{#if} and all previous 3135@samp{#elif} directives within it have failed. 3136 3137@samp{#else} is allowed after any number of @samp{#elif} directives, but 3138@samp{#elif} may not follow @samp{#else}. 3139 3140@node Deleted Code 3141@section Deleted Code 3142@cindex commenting out code 3143 3144If you replace or delete a part of the program but want to keep the old 3145code around for future reference, you often cannot simply comment it 3146out. Block comments do not nest, so the first comment inside the old 3147code will end the commenting-out. The probable result is a flood of 3148syntax errors. 3149 3150One way to avoid this problem is to use an always-false conditional 3151instead. For instance, put @code{#if 0} before the deleted code and 3152@code{#endif} after it. This works even if the code being turned 3153off contains conditionals, but they must be entire conditionals 3154(balanced @samp{#if} and @samp{#endif}). 3155 3156Some people use @code{#ifdef notdef} instead. This is risky, because 3157@code{notdef} might be accidentally defined as a macro, and then the 3158conditional would succeed. @code{#if 0} can be counted on to fail. 3159 3160Do not use @code{#if 0} for comments which are not C code. Use a real 3161comment, instead. The interior of @code{#if 0} must consist of complete 3162tokens; in particular, single-quote characters must balance. Comments 3163often contain unbalanced single-quote characters (known in English as 3164apostrophes). These confuse @code{#if 0}. They don't confuse 3165@samp{/*}. 3166 3167@node Diagnostics 3168@chapter Diagnostics 3169@cindex diagnostic 3170@cindex reporting errors 3171@cindex reporting warnings 3172 3173@findex #error 3174The directive @samp{#error} causes the preprocessor to report a fatal 3175error. The tokens forming the rest of the line following @samp{#error} 3176are used as the error message. 3177 3178You would use @samp{#error} inside of a conditional that detects a 3179combination of parameters which you know the program does not properly 3180support. For example, if you know that the program will not run 3181properly on a VAX, you might write 3182 3183@smallexample 3184@group 3185#ifdef __vax__ 3186#error "Won't work on VAXen. See comments at get_last_object." 3187#endif 3188@end group 3189@end smallexample 3190 3191If you have several configuration parameters that must be set up by 3192the installation in a consistent way, you can use conditionals to detect 3193an inconsistency and report it with @samp{#error}. For example, 3194 3195@smallexample 3196#if !defined(UNALIGNED_INT_ASM_OP) && defined(DWARF2_DEBUGGING_INFO) 3197#error "DWARF2_DEBUGGING_INFO requires UNALIGNED_INT_ASM_OP." 3198#endif 3199@end smallexample 3200 3201@findex #warning 3202The directive @samp{#warning} is like @samp{#error}, but causes the 3203preprocessor to issue a warning and continue preprocessing. The tokens 3204following @samp{#warning} are used as the warning message. 3205 3206You might use @samp{#warning} in obsolete header files, with a message 3207directing the user to the header file which should be used instead. 3208 3209Neither @samp{#error} nor @samp{#warning} macro-expands its argument. 3210Internal whitespace sequences are each replaced with a single space. 3211The line must consist of complete tokens. It is wisest to make the 3212argument of these directives be a single string constant; this avoids 3213problems with apostrophes and the like. 3214 3215@node Line Control 3216@chapter Line Control 3217@cindex line control 3218 3219The C preprocessor informs the C compiler of the location in your source 3220code where each token came from. Presently, this is just the file name 3221and line number. All the tokens resulting from macro expansion are 3222reported as having appeared on the line of the source file where the 3223outermost macro was used. We intend to be more accurate in the future. 3224 3225If you write a program which generates source code, such as the 3226@command{bison} parser generator, you may want to adjust the preprocessor's 3227notion of the current file name and line number by hand. Parts of the 3228output from @command{bison} are generated from scratch, other parts come 3229from a standard parser file. The rest are copied verbatim from 3230@command{bison}'s input. You would like compiler error messages and 3231symbolic debuggers to be able to refer to @code{bison}'s input file. 3232 3233@findex #line 3234@command{bison} or any such program can arrange this by writing 3235@samp{#line} directives into the output file. @samp{#line} is a 3236directive that specifies the original line number and source file name 3237for subsequent input in the current preprocessor input file. 3238@samp{#line} has three variants: 3239 3240@table @code 3241@item #line @var{linenum} 3242@var{linenum} is a non-negative decimal integer constant. It specifies 3243the line number which should be reported for the following line of 3244input. Subsequent lines are counted from @var{linenum}. 3245 3246@item #line @var{linenum} @var{filename} 3247@var{linenum} is the same as for the first form, and has the same 3248effect. In addition, @var{filename} is a string constant. The 3249following line and all subsequent lines are reported to come from the 3250file it specifies, until something else happens to change that. 3251@var{filename} is interpreted according to the normal rules for a string 3252constant: backslash escapes are interpreted. This is different from 3253@samp{#include}. 3254 3255Previous versions of CPP did not interpret escapes in @samp{#line}; 3256we have changed it because the standard requires they be interpreted, 3257and most other compilers do. 3258 3259@item #line @var{anything else} 3260@var{anything else} is checked for macro calls, which are expanded. 3261The result should match one of the above two forms. 3262@end table 3263 3264@samp{#line} directives alter the results of the @code{__FILE__} and 3265@code{__LINE__} predefined macros from that point on. @xref{Standard 3266Predefined Macros}. They do not have any effect on @samp{#include}'s 3267idea of the directory containing the current file. This is a change 3268from GCC 2.95. Previously, a file reading 3269 3270@smallexample 3271#line 1 "../src/gram.y" 3272#include "gram.h" 3273@end smallexample 3274 3275would search for @file{gram.h} in @file{../src}, then the @option{-I} 3276chain; the directory containing the physical source file would not be 3277searched. In GCC 3.0 and later, the @samp{#include} is not affected by 3278the presence of a @samp{#line} referring to a different directory. 3279 3280We made this change because the old behavior caused problems when 3281generated source files were transported between machines. For instance, 3282it is common practice to ship generated parsers with a source release, 3283so that people building the distribution do not need to have yacc or 3284Bison installed. These files frequently have @samp{#line} directives 3285referring to the directory tree of the system where the distribution was 3286created. If GCC tries to search for headers in those directories, the 3287build is likely to fail. 3288 3289The new behavior can cause failures too, if the generated file is not 3290in the same directory as its source and it attempts to include a header 3291which would be visible searching from the directory containing the 3292source file. However, this problem is easily solved with an additional 3293@option{-I} switch on the command line. The failures caused by the old 3294semantics could sometimes be corrected only by editing the generated 3295files, which is difficult and error-prone. 3296 3297@node Pragmas 3298@chapter Pragmas 3299 3300The @samp{#pragma} directive is the method specified by the C standard 3301for providing additional information to the compiler, beyond what is 3302conveyed in the language itself. Three forms of this directive 3303(commonly known as @dfn{pragmas}) are specified by the 1999 C standard. 3304A C compiler is free to attach any meaning it likes to other pragmas. 3305 3306GCC has historically preferred to use extensions to the syntax of the 3307language, such as @code{__attribute__}, for this purpose. However, GCC 3308does define a few pragmas of its own. These mostly have effects on the 3309entire translation unit or source file. 3310 3311In GCC version 3, all GNU-defined, supported pragmas have been given a 3312@code{GCC} prefix. This is in line with the @code{STDC} prefix on all 3313pragmas defined by C99. For backward compatibility, pragmas which were 3314recognized by previous versions are still recognized without the 3315@code{GCC} prefix, but that usage is deprecated. Some older pragmas are 3316deprecated in their entirety. They are not recognized with the 3317@code{GCC} prefix. @xref{Obsolete Features}. 3318 3319@cindex @code{_Pragma} 3320C99 introduces the @code{@w{_Pragma}} operator. This feature addresses a 3321major problem with @samp{#pragma}: being a directive, it cannot be 3322produced as the result of macro expansion. @code{@w{_Pragma}} is an 3323operator, much like @code{sizeof} or @code{defined}, and can be embedded 3324in a macro. 3325 3326Its syntax is @code{@w{_Pragma (@var{string-literal})}}, where 3327@var{string-literal} can be either a normal or wide-character string 3328literal. It is destringized, by replacing all @samp{\\} with a single 3329@samp{\} and all @samp{\"} with a @samp{"}. The result is then 3330processed as if it had appeared as the right hand side of a 3331@samp{#pragma} directive. For example, 3332 3333@smallexample 3334_Pragma ("GCC dependency \"parse.y\"") 3335@end smallexample 3336 3337@noindent 3338has the same effect as @code{#pragma GCC dependency "parse.y"}. The 3339same effect could be achieved using macros, for example 3340 3341@smallexample 3342#define DO_PRAGMA(x) _Pragma (#x) 3343DO_PRAGMA (GCC dependency "parse.y") 3344@end smallexample 3345 3346The standard is unclear on where a @code{_Pragma} operator can appear. 3347The preprocessor does not accept it within a preprocessing conditional 3348directive like @samp{#if}. To be safe, you are probably best keeping it 3349out of directives other than @samp{#define}, and putting it on a line of 3350its own. 3351 3352This manual documents the pragmas which are meaningful to the 3353preprocessor itself. Other pragmas are meaningful to the C or C++ 3354compilers. They are documented in the GCC manual. 3355 3356@ftable @code 3357@item #pragma GCC dependency 3358@code{#pragma GCC dependency} allows you to check the relative dates of 3359the current file and another file. If the other file is more recent than 3360the current file, a warning is issued. This is useful if the current 3361file is derived from the other file, and should be regenerated. The 3362other file is searched for using the normal include search path. 3363Optional trailing text can be used to give more information in the 3364warning message. 3365 3366@smallexample 3367#pragma GCC dependency "parse.y" 3368#pragma GCC dependency "/usr/include/time.h" rerun fixincludes 3369@end smallexample 3370 3371@item #pragma GCC poison 3372Sometimes, there is an identifier that you want to remove completely 3373from your program, and make sure that it never creeps back in. To 3374enforce this, you can @dfn{poison} the identifier with this pragma. 3375@code{#pragma GCC poison} is followed by a list of identifiers to 3376poison. If any of those identifiers appears anywhere in the source 3377after the directive, it is a hard error. For example, 3378 3379@smallexample 3380#pragma GCC poison printf sprintf fprintf 3381sprintf(some_string, "hello"); 3382@end smallexample 3383 3384@noindent 3385will produce an error. 3386 3387If a poisoned identifier appears as part of the expansion of a macro 3388which was defined before the identifier was poisoned, it will @emph{not} 3389cause an error. This lets you poison an identifier without worrying 3390about system headers defining macros that use it. 3391 3392For example, 3393 3394@smallexample 3395#define strrchr rindex 3396#pragma GCC poison rindex 3397strrchr(some_string, 'h'); 3398@end smallexample 3399 3400@noindent 3401will not produce an error. 3402 3403@item #pragma GCC system_header 3404This pragma takes no arguments. It causes the rest of the code in the 3405current file to be treated as if it came from a system header. 3406@xref{System Headers}. 3407 3408@end ftable 3409 3410@node Other Directives 3411@chapter Other Directives 3412 3413@findex #ident 3414@findex #sccs 3415The @samp{#ident} directive takes one argument, a string constant. On 3416some systems, that string constant is copied into a special segment of 3417the object file. On other systems, the directive is ignored. The 3418@samp{#sccs} directive is a synonym for @samp{#ident}. 3419 3420These directives are not part of the C standard, but they are not 3421official GNU extensions either. What historical information we have 3422been able to find, suggests they originated with System V@. 3423 3424@cindex null directive 3425The @dfn{null directive} consists of a @samp{#} followed by a newline, 3426with only whitespace (including comments) in between. A null directive 3427is understood as a preprocessing directive but has no effect on the 3428preprocessor output. The primary significance of the existence of the 3429null directive is that an input line consisting of just a @samp{#} will 3430produce no output, rather than a line of output containing just a 3431@samp{#}. Supposedly some old C programs contain such lines. 3432 3433@node Preprocessor Output 3434@chapter Preprocessor Output 3435 3436When the C preprocessor is used with the C, C++, or Objective-C 3437compilers, it is integrated into the compiler and communicates a stream 3438of binary tokens directly to the compiler's parser. However, it can 3439also be used in the more conventional standalone mode, where it produces 3440textual output. 3441@c FIXME: Document the library interface. 3442 3443@cindex output format 3444The output from the C preprocessor looks much like the input, except 3445that all preprocessing directive lines have been replaced with blank 3446lines and all comments with spaces. Long runs of blank lines are 3447discarded. 3448 3449The ISO standard specifies that it is implementation defined whether a 3450preprocessor preserves whitespace between tokens, or replaces it with 3451e.g.@: a single space. In GNU CPP, whitespace between tokens is collapsed 3452to become a single space, with the exception that the first token on a 3453non-directive line is preceded with sufficient spaces that it appears in 3454the same column in the preprocessed output that it appeared in the 3455original source file. This is so the output is easy to read. 3456@xref{Differences from previous versions}. CPP does not insert any 3457whitespace where there was none in the original source, except where 3458necessary to prevent an accidental token paste. 3459 3460@cindex linemarkers 3461Source file name and line number information is conveyed by lines 3462of the form 3463 3464@smallexample 3465# @var{linenum} @var{filename} @var{flags} 3466@end smallexample 3467 3468@noindent 3469These are called @dfn{linemarkers}. They are inserted as needed into 3470the output (but never within a string or character constant). They mean 3471that the following line originated in file @var{filename} at line 3472@var{linenum}. @var{filename} will never contain any non-printing 3473characters; they are replaced with octal escape sequences. 3474 3475After the file name comes zero or more flags, which are @samp{1}, 3476@samp{2}, @samp{3}, or @samp{4}. If there are multiple flags, spaces 3477separate them. Here is what the flags mean: 3478 3479@table @samp 3480@item 1 3481This indicates the start of a new file. 3482@item 2 3483This indicates returning to a file (after having included another file). 3484@item 3 3485This indicates that the following text comes from a system header file, 3486so certain warnings should be suppressed. 3487@item 4 3488This indicates that the following text should be treated as being 3489wrapped in an implicit @code{extern "C"} block. 3490@c maybe cross reference NO_IMPLICIT_EXTERN_C 3491@end table 3492 3493As an extension, the preprocessor accepts linemarkers in non-assembler 3494input files. They are treated like the corresponding @samp{#line} 3495directive, (@pxref{Line Control}), except that trailing flags are 3496permitted, and are interpreted with the meanings described above. If 3497multiple flags are given, they must be in ascending order. 3498 3499Some directives may be duplicated in the output of the preprocessor. 3500These are @samp{#ident} (always), @samp{#pragma} (only if the 3501preprocessor does not handle the pragma itself), and @samp{#define} and 3502@samp{#undef} (with certain debugging options). If this happens, the 3503@samp{#} of the directive will always be in the first column, and there 3504will be no space between the @samp{#} and the directive name. If macro 3505expansion happens to generate tokens which might be mistaken for a 3506duplicated directive, a space will be inserted between the @samp{#} and 3507the directive name. 3508 3509@node Traditional Mode 3510@chapter Traditional Mode 3511 3512Traditional (pre-standard) C preprocessing is rather different from 3513the preprocessing specified by the standard. When GCC is given the 3514@option{-traditional-cpp} option, it attempts to emulate a traditional 3515preprocessor. 3516 3517GCC versions 3.2 and later only support traditional mode semantics in 3518the preprocessor, and not in the compiler front ends. This chapter 3519outlines the traditional preprocessor semantics we implemented. 3520 3521The implementation does not correspond precisely to the behavior of 3522earlier versions of GCC, nor to any true traditional preprocessor. 3523After all, inconsistencies among traditional implementations were a 3524major motivation for C standardization. However, we intend that it 3525should be compatible with true traditional preprocessors in all ways 3526that actually matter. 3527 3528@menu 3529* Traditional lexical analysis:: 3530* Traditional macros:: 3531* Traditional miscellany:: 3532* Traditional warnings:: 3533@end menu 3534 3535@node Traditional lexical analysis 3536@section Traditional lexical analysis 3537 3538The traditional preprocessor does not decompose its input into tokens 3539the same way a standards-conforming preprocessor does. The input is 3540simply treated as a stream of text with minimal internal form. 3541 3542This implementation does not treat trigraphs (@pxref{trigraphs}) 3543specially since they were an invention of the standards committee. It 3544handles arbitrarily-positioned escaped newlines properly and splices 3545the lines as you would expect; many traditional preprocessors did not 3546do this. 3547 3548The form of horizontal whitespace in the input file is preserved in 3549the output. In particular, hard tabs remain hard tabs. This can be 3550useful if, for example, you are preprocessing a Makefile. 3551 3552Traditional CPP only recognizes C-style block comments, and treats the 3553@samp{/*} sequence as introducing a comment only if it lies outside 3554quoted text. Quoted text is introduced by the usual single and double 3555quotes, and also by an initial @samp{<} in a @code{#include} 3556directive. 3557 3558Traditionally, comments are completely removed and are not replaced 3559with a space. Since a traditional compiler does its own tokenization 3560of the output of the preprocessor, this means that comments can 3561effectively be used as token paste operators. However, comments 3562behave like separators for text handled by the preprocessor itself, 3563since it doesn't re-lex its input. For example, in 3564 3565@smallexample 3566#if foo/**/bar 3567@end smallexample 3568 3569@noindent 3570@samp{foo} and @samp{bar} are distinct identifiers and expanded 3571separately if they happen to be macros. In other words, this 3572directive is equivalent to 3573 3574@smallexample 3575#if foo bar 3576@end smallexample 3577 3578@noindent 3579rather than 3580 3581@smallexample 3582#if foobar 3583@end smallexample 3584 3585Generally speaking, in traditional mode an opening quote need not have 3586a matching closing quote. In particular, a macro may be defined with 3587replacement text that contains an unmatched quote. Of course, if you 3588attempt to compile preprocessed output containing an unmatched quote 3589you will get a syntax error. 3590 3591However, all preprocessing directives other than @code{#define} 3592require matching quotes. For example: 3593 3594@smallexample 3595#define m This macro's fine and has an unmatched quote 3596"/* This is not a comment. */ 3597/* @r{This is a comment. The following #include directive 3598 is ill-formed.} */ 3599#include <stdio.h 3600@end smallexample 3601 3602Just as for the ISO preprocessor, what would be a closing quote can be 3603escaped with a backslash to prevent the quoted text from closing. 3604 3605@node Traditional macros 3606@section Traditional macros 3607 3608The major difference between traditional and ISO macros is that the 3609former expand to text rather than to a token sequence. CPP removes 3610all leading and trailing horizontal whitespace from a macro's 3611replacement text before storing it, but preserves the form of internal 3612whitespace. 3613 3614One consequence is that it is legitimate for the replacement text to 3615contain an unmatched quote (@pxref{Traditional lexical analysis}). An 3616unclosed string or character constant continues into the text 3617following the macro call. Similarly, the text at the end of a macro's 3618expansion can run together with the text after the macro invocation to 3619produce a single token. 3620 3621Normally comments are removed from the replacement text after the 3622macro is expanded, but if the @option{-CC} option is passed on the 3623command line comments are preserved. (In fact, the current 3624implementation removes comments even before saving the macro 3625replacement text, but it careful to do it in such a way that the 3626observed effect is identical even in the function-like macro case.) 3627 3628The ISO stringification operator @samp{#} and token paste operator 3629@samp{##} have no special meaning. As explained later, an effect 3630similar to these operators can be obtained in a different way. Macro 3631names that are embedded in quotes, either from the main file or after 3632macro replacement, do not expand. 3633 3634CPP replaces an unquoted object-like macro name with its replacement 3635text, and then rescans it for further macros to replace. Unlike 3636standard macro expansion, traditional macro expansion has no provision 3637to prevent recursion. If an object-like macro appears unquoted in its 3638replacement text, it will be replaced again during the rescan pass, 3639and so on @emph{ad infinitum}. GCC detects when it is expanding 3640recursive macros, emits an error message, and continues after the 3641offending macro invocation. 3642 3643@smallexample 3644#define PLUS + 3645#define INC(x) PLUS+x 3646INC(foo); 3647 @expansion{} ++foo; 3648@end smallexample 3649 3650Function-like macros are similar in form but quite different in 3651behavior to their ISO counterparts. Their arguments are contained 3652within parentheses, are comma-separated, and can cross physical lines. 3653Commas within nested parentheses are not treated as argument 3654separators. Similarly, a quote in an argument cannot be left 3655unclosed; a following comma or parenthesis that comes before the 3656closing quote is treated like any other character. There is no 3657facility for handling variadic macros. 3658 3659This implementation removes all comments from macro arguments, unless 3660the @option{-C} option is given. The form of all other horizontal 3661whitespace in arguments is preserved, including leading and trailing 3662whitespace. In particular 3663 3664@smallexample 3665f( ) 3666@end smallexample 3667 3668@noindent 3669is treated as an invocation of the macro @samp{f} with a single 3670argument consisting of a single space. If you want to invoke a 3671function-like macro that takes no arguments, you must not leave any 3672whitespace between the parentheses. 3673 3674If a macro argument crosses a new line, the new line is replaced with 3675a space when forming the argument. If the previous line contained an 3676unterminated quote, the following line inherits the quoted state. 3677 3678Traditional preprocessors replace parameters in the replacement text 3679with their arguments regardless of whether the parameters are within 3680quotes or not. This provides a way to stringize arguments. For 3681example 3682 3683@smallexample 3684#define str(x) "x" 3685str(/* @r{A comment} */some text ) 3686 @expansion{} "some text " 3687@end smallexample 3688 3689@noindent 3690Note that the comment is removed, but that the trailing space is 3691preserved. Here is an example of using a comment to effect token 3692pasting. 3693 3694@smallexample 3695#define suffix(x) foo_/**/x 3696suffix(bar) 3697 @expansion{} foo_bar 3698@end smallexample 3699 3700@node Traditional miscellany 3701@section Traditional miscellany 3702 3703Here are some things to be aware of when using the traditional 3704preprocessor. 3705 3706@itemize @bullet 3707@item 3708Preprocessing directives are recognized only when their leading 3709@samp{#} appears in the first column. There can be no whitespace 3710between the beginning of the line and the @samp{#}, but whitespace can 3711follow the @samp{#}. 3712 3713@item 3714A true traditional C preprocessor does not recognize @samp{#error} or 3715@samp{#pragma}, and may not recognize @samp{#elif}. CPP supports all 3716the directives in traditional mode that it supports in ISO mode, 3717including extensions, with the exception that the effects of 3718@samp{#pragma GCC poison} are undefined. 3719 3720@item 3721__STDC__ is not defined. 3722 3723@item 3724If you use digraphs the behavior is undefined. 3725 3726@item 3727If a line that looks like a directive appears within macro arguments, 3728the behavior is undefined. 3729 3730@end itemize 3731 3732@node Traditional warnings 3733@section Traditional warnings 3734You can request warnings about features that did not exist, or worked 3735differently, in traditional C with the @option{-Wtraditional} option. 3736GCC does not warn about features of ISO C which you must use when you 3737are using a conforming compiler, such as the @samp{#} and @samp{##} 3738operators. 3739 3740Presently @option{-Wtraditional} warns about: 3741 3742@itemize @bullet 3743@item 3744Macro parameters that appear within string literals in the macro body. 3745In traditional C macro replacement takes place within string literals, 3746but does not in ISO C@. 3747 3748@item 3749In traditional C, some preprocessor directives did not exist. 3750Traditional preprocessors would only consider a line to be a directive 3751if the @samp{#} appeared in column 1 on the line. Therefore 3752@option{-Wtraditional} warns about directives that traditional C 3753understands but would ignore because the @samp{#} does not appear as the 3754first character on the line. It also suggests you hide directives like 3755@samp{#pragma} not understood by traditional C by indenting them. Some 3756traditional implementations would not recognize @samp{#elif}, so it 3757suggests avoiding it altogether. 3758 3759@item 3760A function-like macro that appears without an argument list. In some 3761traditional preprocessors this was an error. In ISO C it merely means 3762that the macro is not expanded. 3763 3764@item 3765The unary plus operator. This did not exist in traditional C@. 3766 3767@item 3768The @samp{U} and @samp{LL} integer constant suffixes, which were not 3769available in traditional C@. (Traditional C does support the @samp{L} 3770suffix for simple long integer constants.) You are not warned about 3771uses of these suffixes in macros defined in system headers. For 3772instance, @code{UINT_MAX} may well be defined as @code{4294967295U}, but 3773you will not be warned if you use @code{UINT_MAX}. 3774 3775You can usually avoid the warning, and the related warning about 3776constants which are so large that they are unsigned, by writing the 3777integer constant in question in hexadecimal, with no U suffix. Take 3778care, though, because this gives the wrong result in exotic cases. 3779@end itemize 3780 3781@node Implementation Details 3782@chapter Implementation Details 3783 3784Here we document details of how the preprocessor's implementation 3785affects its user-visible behavior. You should try to avoid undue 3786reliance on behavior described here, as it is possible that it will 3787change subtly in future implementations. 3788 3789Also documented here are obsolete features and changes from previous 3790versions of CPP@. 3791 3792@menu 3793* Implementation-defined behavior:: 3794* Implementation limits:: 3795* Obsolete Features:: 3796* Differences from previous versions:: 3797@end menu 3798 3799@node Implementation-defined behavior 3800@section Implementation-defined behavior 3801@cindex implementation-defined behavior 3802 3803This is how CPP behaves in all the cases which the C standard 3804describes as @dfn{implementation-defined}. This term means that the 3805implementation is free to do what it likes, but must document its choice 3806and stick to it. 3807@c FIXME: Check the C++ standard for more implementation-defined stuff. 3808 3809@itemize @bullet 3810@need 1000 3811@item The mapping of physical source file multi-byte characters to the 3812execution character set. 3813 3814Currently, CPP requires its input to be ASCII or UTF-8. The execution 3815character set may be controlled by the user, with the 3816@option{-fexec-charset} and @option{-fwide-exec-charset} options. 3817 3818@item Identifier characters. 3819@anchor{Identifier characters} 3820 3821The C and C++ standards allow identifiers to be composed of @samp{_} 3822and the alphanumeric characters. C++ and C99 also allow universal 3823character names, and C99 further permits implementation-defined 3824characters. GCC currently only permits universal character names if 3825@option{-fextended-identifiers} is used, because the implementation of 3826universal character names in identifiers is experimental. 3827 3828GCC allows the @samp{$} character in identifiers as an extension for 3829most targets. This is true regardless of the @option{std=} switch, 3830since this extension cannot conflict with standards-conforming 3831programs. When preprocessing assembler, however, dollars are not 3832identifier characters by default. 3833 3834Currently the targets that by default do not permit @samp{$} are AVR, 3835IP2K, MMIX, MIPS Irix 3, ARM aout, and PowerPC targets for the AIX and 3836BeOS operating systems. 3837 3838You can override the default with @option{-fdollars-in-identifiers} or 3839@option{fno-dollars-in-identifiers}. @xref{fdollars-in-identifiers}. 3840 3841@item Non-empty sequences of whitespace characters. 3842 3843In textual output, each whitespace sequence is collapsed to a single 3844space. For aesthetic reasons, the first token on each non-directive 3845line of output is preceded with sufficient spaces that it appears in the 3846same column as it did in the original source file. 3847 3848@item The numeric value of character constants in preprocessor expressions. 3849 3850The preprocessor and compiler interpret character constants in the 3851same way; i.e.@: escape sequences such as @samp{\a} are given the 3852values they would have on the target machine. 3853 3854The compiler values a multi-character character constant a character 3855at a time, shifting the previous value left by the number of bits per 3856target character, and then or-ing in the bit-pattern of the new 3857character truncated to the width of a target character. The final 3858bit-pattern is given type @code{int}, and is therefore signed, 3859regardless of whether single characters are signed or not (a slight 3860change from versions 3.1 and earlier of GCC)@. If there are more 3861characters in the constant than would fit in the target @code{int} the 3862compiler issues a warning, and the excess leading characters are 3863ignored. 3864 3865For example, @code{'ab'} for a target with an 8-bit @code{char} would be 3866interpreted as @w{@samp{(int) ((unsigned char) 'a' * 256 + (unsigned char) 3867'b')}}, and @code{'\234a'} as @w{@samp{(int) ((unsigned char) '\234' * 3868256 + (unsigned char) 'a')}}. 3869 3870@item Source file inclusion. 3871 3872For a discussion on how the preprocessor locates header files, 3873@ref{Include Operation}. 3874 3875@item Interpretation of the filename resulting from a macro-expanded 3876@samp{#include} directive. 3877 3878@xref{Computed Includes}. 3879 3880@item Treatment of a @samp{#pragma} directive that after macro-expansion 3881results in a standard pragma. 3882 3883No macro expansion occurs on any @samp{#pragma} directive line, so the 3884question does not arise. 3885 3886Note that GCC does not yet implement any of the standard 3887pragmas. 3888 3889@end itemize 3890 3891@node Implementation limits 3892@section Implementation limits 3893@cindex implementation limits 3894 3895CPP has a small number of internal limits. This section lists the 3896limits which the C standard requires to be no lower than some minimum, 3897and all the others known. It is intended that there should be as few limits 3898as possible. If you encounter an undocumented or inconvenient limit, 3899please report that as a bug. @xref{Bugs, , Reporting Bugs, gcc, Using 3900the GNU Compiler Collection (GCC)}. 3901 3902Where we say something is limited @dfn{only by available memory}, that 3903means that internal data structures impose no intrinsic limit, and space 3904is allocated with @code{malloc} or equivalent. The actual limit will 3905therefore depend on many things, such as the size of other things 3906allocated by the compiler at the same time, the amount of memory 3907consumed by other processes on the same computer, etc. 3908 3909@itemize @bullet 3910 3911@item Nesting levels of @samp{#include} files. 3912 3913We impose an arbitrary limit of 200 levels, to avoid runaway recursion. 3914The standard requires at least 15 levels. 3915 3916@item Nesting levels of conditional inclusion. 3917 3918The C standard mandates this be at least 63. CPP is limited only by 3919available memory. 3920 3921@item Levels of parenthesized expressions within a full expression. 3922 3923The C standard requires this to be at least 63. In preprocessor 3924conditional expressions, it is limited only by available memory. 3925 3926@item Significant initial characters in an identifier or macro name. 3927 3928The preprocessor treats all characters as significant. The C standard 3929requires only that the first 63 be significant. 3930 3931@item Number of macros simultaneously defined in a single translation unit. 3932 3933The standard requires at least 4095 be possible. CPP is limited only 3934by available memory. 3935 3936@item Number of parameters in a macro definition and arguments in a macro call. 3937 3938We allow @code{USHRT_MAX}, which is no smaller than 65,535. The minimum 3939required by the standard is 127. 3940 3941@item Number of characters on a logical source line. 3942 3943The C standard requires a minimum of 4096 be permitted. CPP places 3944no limits on this, but you may get incorrect column numbers reported in 3945diagnostics for lines longer than 65,535 characters. 3946 3947@item Maximum size of a source file. 3948 3949The standard does not specify any lower limit on the maximum size of a 3950source file. GNU cpp maps files into memory, so it is limited by the 3951available address space. This is generally at least two gigabytes. 3952Depending on the operating system, the size of physical memory may or 3953may not be a limitation. 3954 3955@end itemize 3956 3957@node Obsolete Features 3958@section Obsolete Features 3959 3960CPP has a number of features which are present mainly for 3961compatibility with older programs. We discourage their use in new code. 3962In some cases, we plan to remove the feature in a future version of GCC@. 3963 3964@menu 3965* Assertions:: 3966* Obsolete once-only headers:: 3967@end menu 3968 3969@node Assertions 3970@subsection Assertions 3971@cindex assertions 3972 3973@dfn{Assertions} are a deprecated alternative to macros in writing 3974conditionals to test what sort of computer or system the compiled 3975program will run on. Assertions are usually predefined, but you can 3976define them with preprocessing directives or command-line options. 3977 3978Assertions were intended to provide a more systematic way to describe 3979the compiler's target system. However, in practice they are just as 3980unpredictable as the system-specific predefined macros. In addition, they 3981are not part of any standard, and only a few compilers support them. 3982Therefore, the use of assertions is @strong{less} portable than the use 3983of system-specific predefined macros. We recommend you do not use them at 3984all. 3985 3986@cindex predicates 3987An assertion looks like this: 3988 3989@smallexample 3990#@var{predicate} (@var{answer}) 3991@end smallexample 3992 3993@noindent 3994@var{predicate} must be a single identifier. @var{answer} can be any 3995sequence of tokens; all characters are significant except for leading 3996and trailing whitespace, and differences in internal whitespace 3997sequences are ignored. (This is similar to the rules governing macro 3998redefinition.) Thus, @code{(x + y)} is different from @code{(x+y)} but 3999equivalent to @code{@w{( x + y )}}. Parentheses do not nest inside an 4000answer. 4001 4002@cindex testing predicates 4003To test an assertion, you write it in an @samp{#if}. For example, this 4004conditional succeeds if either @code{vax} or @code{ns16000} has been 4005asserted as an answer for @code{machine}. 4006 4007@smallexample 4008#if #machine (vax) || #machine (ns16000) 4009@end smallexample 4010 4011@noindent 4012You can test whether @emph{any} answer is asserted for a predicate by 4013omitting the answer in the conditional: 4014 4015@smallexample 4016#if #machine 4017@end smallexample 4018 4019@findex #assert 4020Assertions are made with the @samp{#assert} directive. Its sole 4021argument is the assertion to make, without the leading @samp{#} that 4022identifies assertions in conditionals. 4023 4024@smallexample 4025#assert @var{predicate} (@var{answer}) 4026@end smallexample 4027 4028@noindent 4029You may make several assertions with the same predicate and different 4030answers. Subsequent assertions do not override previous ones for the 4031same predicate. All the answers for any given predicate are 4032simultaneously true. 4033 4034@cindex assertions, canceling 4035@findex #unassert 4036Assertions can be canceled with the @samp{#unassert} directive. It 4037has the same syntax as @samp{#assert}. In that form it cancels only the 4038answer which was specified on the @samp{#unassert} line; other answers 4039for that predicate remain true. You can cancel an entire predicate by 4040leaving out the answer: 4041 4042@smallexample 4043#unassert @var{predicate} 4044@end smallexample 4045 4046@noindent 4047In either form, if no such assertion has been made, @samp{#unassert} has 4048no effect. 4049 4050You can also make or cancel assertions using command line options. 4051@xref{Invocation}. 4052 4053@node Obsolete once-only headers 4054@subsection Obsolete once-only headers 4055 4056CPP supports two more ways of indicating that a header file should be 4057read only once. Neither one is as portable as a wrapper @samp{#ifndef}, 4058and we recommend you do not use them in new programs. 4059 4060@findex #import 4061In the Objective-C language, there is a variant of @samp{#include} 4062called @samp{#import} which includes a file, but does so at most once. 4063If you use @samp{#import} instead of @samp{#include}, then you don't 4064need the conditionals inside the header file to prevent multiple 4065inclusion of the contents. GCC permits the use of @samp{#import} in C 4066and C++ as well as Objective-C@. However, it is not in standard C or C++ 4067and should therefore not be used by portable programs. 4068 4069@samp{#import} is not a well designed feature. It requires the users of 4070a header file to know that it should only be included once. It is much 4071better for the header file's implementor to write the file so that users 4072don't need to know this. Using a wrapper @samp{#ifndef} accomplishes 4073this goal. 4074 4075In the present implementation, a single use of @samp{#import} will 4076prevent the file from ever being read again, by either @samp{#import} or 4077@samp{#include}. You should not rely on this; do not use both 4078@samp{#import} and @samp{#include} to refer to the same header file. 4079 4080Another way to prevent a header file from being included more than once 4081is with the @samp{#pragma once} directive. If @samp{#pragma once} is 4082seen when scanning a header file, that file will never be read again, no 4083matter what. 4084 4085@samp{#pragma once} does not have the problems that @samp{#import} does, 4086but it is not recognized by all preprocessors, so you cannot rely on it 4087in a portable program. 4088 4089@node Differences from previous versions 4090@section Differences from previous versions 4091@cindex differences from previous versions 4092 4093This section details behavior which has changed from previous versions 4094of CPP@. We do not plan to change it again in the near future, but 4095we do not promise not to, either. 4096 4097The ``previous versions'' discussed here are 2.95 and before. The 4098behavior of GCC 3.0 is mostly the same as the behavior of the widely 4099used 2.96 and 2.97 development snapshots. Where there are differences, 4100they generally represent bugs in the snapshots. 4101 4102@itemize @bullet 4103 4104@item -I- deprecated 4105 4106This option has been deprecated in 4.0. @option{-iquote} is meant to 4107replace the need for this option. 4108 4109@item Order of evaluation of @samp{#} and @samp{##} operators 4110 4111The standard does not specify the order of evaluation of a chain of 4112@samp{##} operators, nor whether @samp{#} is evaluated before, after, or 4113at the same time as @samp{##}. You should therefore not write any code 4114which depends on any specific ordering. It is possible to guarantee an 4115ordering, if you need one, by suitable use of nested macros. 4116 4117An example of where this might matter is pasting the arguments @samp{1}, 4118@samp{e} and @samp{-2}. This would be fine for left-to-right pasting, 4119but right-to-left pasting would produce an invalid token @samp{e-2}. 4120 4121GCC 3.0 evaluates @samp{#} and @samp{##} at the same time and strictly 4122left to right. Older versions evaluated all @samp{#} operators first, 4123then all @samp{##} operators, in an unreliable order. 4124 4125@item The form of whitespace between tokens in preprocessor output 4126 4127@xref{Preprocessor Output}, for the current textual format. This is 4128also the format used by stringification. Normally, the preprocessor 4129communicates tokens directly to the compiler's parser, and whitespace 4130does not come up at all. 4131 4132Older versions of GCC preserved all whitespace provided by the user and 4133inserted lots more whitespace of their own, because they could not 4134accurately predict when extra spaces were needed to prevent accidental 4135token pasting. 4136 4137@item Optional argument when invoking rest argument macros 4138 4139As an extension, GCC permits you to omit the variable arguments entirely 4140when you use a variable argument macro. This is forbidden by the 1999 C 4141standard, and will provoke a pedantic warning with GCC 3.0. Previous 4142versions accepted it silently. 4143 4144@item @samp{##} swallowing preceding text in rest argument macros 4145 4146Formerly, in a macro expansion, if @samp{##} appeared before a variable 4147arguments parameter, and the set of tokens specified for that argument 4148in the macro invocation was empty, previous versions of CPP would 4149back up and remove the preceding sequence of non-whitespace characters 4150(@strong{not} the preceding token). This extension is in direct 4151conflict with the 1999 C standard and has been drastically pared back. 4152 4153In the current version of the preprocessor, if @samp{##} appears between 4154a comma and a variable arguments parameter, and the variable argument is 4155omitted entirely, the comma will be removed from the expansion. If the 4156variable argument is empty, or the token before @samp{##} is not a 4157comma, then @samp{##} behaves as a normal token paste. 4158 4159@item @samp{#line} and @samp{#include} 4160 4161The @samp{#line} directive used to change GCC's notion of the 4162``directory containing the current file'', used by @samp{#include} with 4163a double-quoted header file name. In 3.0 and later, it does not. 4164@xref{Line Control}, for further explanation. 4165 4166@item Syntax of @samp{#line} 4167 4168In GCC 2.95 and previous, the string constant argument to @samp{#line} 4169was treated the same way as the argument to @samp{#include}: backslash 4170escapes were not honored, and the string ended at the second @samp{"}. 4171This is not compliant with the C standard. In GCC 3.0, an attempt was 4172made to correct the behavior, so that the string was treated as a real 4173string constant, but it turned out to be buggy. In 3.1, the bugs have 4174been fixed. (We are not fixing the bugs in 3.0 because they affect 4175relatively few people and the fix is quite invasive.) 4176 4177@end itemize 4178 4179@node Invocation 4180@chapter Invocation 4181@cindex invocation 4182@cindex command line 4183 4184Most often when you use the C preprocessor you will not have to invoke it 4185explicitly: the C compiler will do so automatically. However, the 4186preprocessor is sometimes useful on its own. All the options listed 4187here are also acceptable to the C compiler and have the same meaning, 4188except that the C compiler has different rules for specifying the output 4189file. 4190 4191@emph{Note:} Whether you use the preprocessor by way of @command{gcc} 4192or @command{cpp}, the @dfn{compiler driver} is run first. This 4193program's purpose is to translate your command into invocations of the 4194programs that do the actual work. Their command line interfaces are 4195similar but not identical to the documented interface, and may change 4196without notice. 4197 4198@ignore 4199@c man begin SYNOPSIS 4200cpp [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}] 4201 [@option{-I}@var{dir}@dots{}] [@option{-iquote}@var{dir}@dots{}] 4202 [@option{-W}@var{warn}@dots{}] 4203 [@option{-M}|@option{-MM}] [@option{-MG}] [@option{-MF} @var{filename}] 4204 [@option{-MP}] [@option{-MQ} @var{target}@dots{}] 4205 [@option{-MT} @var{target}@dots{}] 4206 [@option{-P}] [@option{-fno-working-directory}] 4207 [@option{-x} @var{language}] [@option{-std=}@var{standard}] 4208 @var{infile} @var{outfile} 4209 4210Only the most useful options are listed here; see below for the remainder. 4211@c man end 4212@c man begin SEEALSO 4213gpl(7), gfdl(7), fsf-funding(7), 4214gcc(1), as(1), ld(1), and the Info entries for @file{cpp}, @file{gcc}, and 4215@file{binutils}. 4216@c man end 4217@end ignore 4218 4219@c man begin OPTIONS 4220The C preprocessor expects two file names as arguments, @var{infile} and 4221@var{outfile}. The preprocessor reads @var{infile} together with any 4222other files it specifies with @samp{#include}. All the output generated 4223by the combined input files is written in @var{outfile}. 4224 4225Either @var{infile} or @var{outfile} may be @option{-}, which as 4226@var{infile} means to read from standard input and as @var{outfile} 4227means to write to standard output. Also, if either file is omitted, it 4228means the same as if @option{-} had been specified for that file. 4229 4230Unless otherwise noted, or the option ends in @samp{=}, all options 4231which take an argument may have that argument appear either immediately 4232after the option, or with a space between option and argument: 4233@option{-Ifoo} and @option{-I foo} have the same effect. 4234 4235@cindex grouping options 4236@cindex options, grouping 4237Many options have multi-letter names; therefore multiple single-letter 4238options may @emph{not} be grouped: @option{-dM} is very different from 4239@w{@samp{-d -M}}. 4240 4241@cindex options 4242@include cppopts.texi 4243@c man end 4244 4245@node Environment Variables 4246@chapter Environment Variables 4247@cindex environment variables 4248@c man begin ENVIRONMENT 4249 4250This section describes the environment variables that affect how CPP 4251operates. You can use them to specify directories or prefixes to use 4252when searching for include files, or to control dependency output. 4253 4254Note that you can also specify places to search using options such as 4255@option{-I}, and control dependency output with options like 4256@option{-M} (@pxref{Invocation}). These take precedence over 4257environment variables, which in turn take precedence over the 4258configuration of GCC@. 4259 4260@include cppenv.texi 4261@c man end 4262 4263@page 4264@include fdl.texi 4265 4266@page 4267@node Index of Directives 4268@unnumbered Index of Directives 4269@printindex fn 4270 4271@node Option Index 4272@unnumbered Option Index 4273@noindent 4274CPP's command line options and environment variables are indexed here 4275without any initial @samp{-} or @samp{--}. 4276@printindex op 4277 4278@page 4279@node Concept Index 4280@unnumbered Concept Index 4281@printindex cp 4282 4283@bye 4284