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