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