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