1This is cpp.info, produced by makeinfo version 6.5 from cpp.texi. 2 3Copyright (C) 1987-2020 Free Software Foundation, Inc. 4 5 Permission is granted to copy, distribute and/or modify this document 6under the terms of the GNU Free Documentation License, Version 1.3 or 7any later version published by the Free Software Foundation. A copy of 8the license is included in the section entitled "GNU Free Documentation 9License". 10 11 This manual contains no Invariant Sections. The Front-Cover Texts 12are (a) (see below), and the Back-Cover Texts are (b) (see below). 13 14 (a) The FSF's Front-Cover Text is: 15 16 A GNU Manual 17 18 (b) The FSF's Back-Cover Text is: 19 20 You have freedom to copy and modify this GNU Manual, like GNU 21software. Copies published by the Free Software Foundation raise funds 22for GNU development. 23INFO-DIR-SECTION Software development 24START-INFO-DIR-ENTRY 25* Cpp: (cpp). The GNU C preprocessor. 26END-INFO-DIR-ENTRY 27 28 29File: cpp.info, Node: Top, Next: Overview, Up: (dir) 30 31The C Preprocessor 32****************** 33 34The C preprocessor implements the macro language used to transform C, 35C++, and Objective-C programs before they are compiled. It can also be 36useful on its own. 37 38* Menu: 39 40* Overview:: 41* Header Files:: 42* Macros:: 43* Conditionals:: 44* Diagnostics:: 45* Line Control:: 46* Pragmas:: 47* Other Directives:: 48* Preprocessor Output:: 49* Traditional Mode:: 50* Implementation Details:: 51* Invocation:: 52* Environment Variables:: 53* GNU Free Documentation License:: 54* Index of Directives:: 55* Option Index:: 56* Concept Index:: 57 58 -- The Detailed Node Listing -- 59 60Overview 61 62* Character sets:: 63* Initial processing:: 64* Tokenization:: 65* The preprocessing language:: 66 67Header Files 68 69* Include Syntax:: 70* Include Operation:: 71* Search Path:: 72* Once-Only Headers:: 73* Alternatives to Wrapper #ifndef:: 74* Computed Includes:: 75* Wrapper Headers:: 76* System Headers:: 77 78Macros 79 80* Object-like Macros:: 81* Function-like Macros:: 82* Macro Arguments:: 83* Stringizing:: 84* Concatenation:: 85* Variadic Macros:: 86* Predefined Macros:: 87* Undefining and Redefining Macros:: 88* Directives Within Macro Arguments:: 89* Macro Pitfalls:: 90 91Predefined Macros 92 93* Standard Predefined Macros:: 94* Common Predefined Macros:: 95* System-specific Predefined Macros:: 96* C++ Named Operators:: 97 98Macro Pitfalls 99 100* Misnesting:: 101* Operator Precedence Problems:: 102* Swallowing the Semicolon:: 103* Duplication of Side Effects:: 104* Self-Referential Macros:: 105* Argument Prescan:: 106* Newlines in Arguments:: 107 108Conditionals 109 110* Conditional Uses:: 111* Conditional Syntax:: 112* Deleted Code:: 113 114Conditional Syntax 115 116* Ifdef:: 117* If:: 118* Defined:: 119* Else:: 120* Elif:: 121 122Implementation Details 123 124* Implementation-defined behavior:: 125* Implementation limits:: 126* Obsolete Features:: 127 128Obsolete Features 129 130* Obsolete Features:: 131 132 133 Copyright (C) 1987-2020 Free Software Foundation, Inc. 134 135 Permission is granted to copy, distribute and/or modify this document 136under the terms of the GNU Free Documentation License, Version 1.3 or 137any later version published by the Free Software Foundation. A copy of 138the license is included in the section entitled "GNU Free Documentation 139License". 140 141 This manual contains no Invariant Sections. The Front-Cover Texts 142are (a) (see below), and the Back-Cover Texts are (b) (see below). 143 144 (a) The FSF's Front-Cover Text is: 145 146 A GNU Manual 147 148 (b) The FSF's Back-Cover Text is: 149 150 You have freedom to copy and modify this GNU Manual, like GNU 151software. Copies published by the Free Software Foundation raise funds 152for GNU development. 153 154 155File: cpp.info, Node: Overview, Next: Header Files, Prev: Top, Up: Top 156 1571 Overview 158********** 159 160The C preprocessor, often known as "cpp", is a "macro processor" that is 161used automatically by the C compiler to transform your program before 162compilation. It is called a macro processor because it allows you to 163define "macros", which are brief abbreviations for longer constructs. 164 165 The C preprocessor is intended to be used only with C, C++, and 166Objective-C source code. In the past, it has been abused as a general 167text processor. It will choke on input which does not obey C's lexical 168rules. For example, apostrophes will be interpreted as the beginning of 169character constants, and cause errors. Also, you cannot rely on it 170preserving characteristics of the input which are not significant to 171C-family languages. If a Makefile is preprocessed, all the hard tabs 172will be removed, and the Makefile will not work. 173 174 Having said that, you can often get away with using cpp on things 175which are not C. Other Algol-ish programming languages are often safe 176(Ada, etc.) So is assembly, with caution. '-traditional-cpp' mode 177preserves more white space, and is otherwise more permissive. Many of 178the problems can be avoided by writing C or C++ style comments instead 179of native language comments, and keeping macros simple. 180 181 Wherever possible, you should use a preprocessor geared to the 182language you are writing in. Modern versions of the GNU assembler have 183macro facilities. Most high level programming languages have their own 184conditional compilation and inclusion mechanism. If all else fails, try 185a true general text processor, such as GNU M4. 186 187 C preprocessors vary in some details. This manual discusses the GNU 188C preprocessor, which provides a small superset of the features of ISO 189Standard C. In its default mode, the GNU C preprocessor does not do a 190few things required by the standard. These are features which are 191rarely, if ever, used, and may cause surprising changes to the meaning 192of a program which does not expect them. To get strict ISO Standard C, 193you should use the '-std=c90', '-std=c99', '-std=c11' or '-std=c17' 194options, depending on which version of the standard you want. To get 195all the mandatory diagnostics, you must also use '-pedantic'. *Note 196Invocation::. 197 198 This manual describes the behavior of the ISO preprocessor. To 199minimize gratuitous differences, where the ISO preprocessor's behavior 200does not conflict with traditional semantics, the traditional 201preprocessor should behave the same way. The various differences that 202do exist are detailed in the section *note Traditional Mode::. 203 204 For clarity, unless noted otherwise, references to 'CPP' in this 205manual refer to GNU CPP. 206 207* Menu: 208 209* Character sets:: 210* Initial processing:: 211* Tokenization:: 212* The preprocessing language:: 213 214 215File: cpp.info, Node: Character sets, Next: Initial processing, Up: Overview 216 2171.1 Character sets 218================== 219 220Source code character set processing in C and related languages is 221rather complicated. The C standard discusses two character sets, but 222there are really at least four. 223 224 The files input to CPP might be in any character set at all. CPP's 225very first action, before it even looks for line boundaries, is to 226convert the file into the character set it uses for internal processing. 227That set is what the C standard calls the "source" character set. It 228must be isomorphic with ISO 10646, also known as Unicode. CPP uses the 229UTF-8 encoding of Unicode. 230 231 The character sets of the input files are specified using the 232'-finput-charset=' option. 233 234 All preprocessing work (the subject of the rest of this manual) is 235carried out in the source character set. If you request textual output 236from the preprocessor with the '-E' option, it will be in UTF-8. 237 238 After preprocessing is complete, string and character constants are 239converted again, into the "execution" character set. This character set 240is under control of the user; the default is UTF-8, matching the source 241character set. Wide string and character constants have their own 242character set, which is not called out specifically in the standard. 243Again, it is under control of the user. The default is UTF-16 or 244UTF-32, whichever fits in the target's 'wchar_t' type, in the target 245machine's byte order.(1) Octal and hexadecimal escape sequences do not 246undergo conversion; '\x12' has the value 0x12 regardless of the 247currently selected execution character set. All other escapes are 248replaced by the character in the source character set that they 249represent, then converted to the execution character set, just like 250unescaped characters. 251 252 In identifiers, characters outside the ASCII range can be specified 253with the '\u' and '\U' escapes or used directly in the input encoding. 254If strict ISO C90 conformance is specified with an option such as 255'-std=c90', or '-fno-extended-identifiers' is used, then those 256constructs are not permitted in identifiers. 257 258 ---------- Footnotes ---------- 259 260 (1) UTF-16 does not meet the requirements of the C standard for a 261wide character set, but the choice of 16-bit 'wchar_t' is enshrined in 262some system ABIs so we cannot fix this. 263 264 265File: cpp.info, Node: Initial processing, Next: Tokenization, Prev: Character sets, Up: Overview 266 2671.2 Initial processing 268====================== 269 270The preprocessor performs a series of textual transformations on its 271input. These happen before all other processing. Conceptually, they 272happen in a rigid order, and the entire file is run through each 273transformation before the next one begins. CPP actually does them all 274at once, for performance reasons. These transformations correspond 275roughly to the first three "phases of translation" described in the C 276standard. 277 278 1. The input file is read into memory and broken into lines. 279 280 Different systems use different conventions to indicate the end of 281 a line. GCC accepts the ASCII control sequences 'LF', 'CR LF' and 282 'CR' as end-of-line markers. These are the canonical sequences 283 used by Unix, DOS and VMS, and the classic Mac OS (before OSX) 284 respectively. You may therefore safely copy source code written on 285 any of those systems to a different one and use it without 286 conversion. (GCC may lose track of the current line number if a 287 file doesn't consistently use one convention, as sometimes happens 288 when it is edited on computers with different conventions that 289 share a network file system.) 290 291 If the last line of any input file lacks an end-of-line marker, the 292 end of the file is considered to implicitly supply one. The C 293 standard says that this condition provokes undefined behavior, so 294 GCC will emit a warning message. 295 296 2. If trigraphs are enabled, they are replaced by their corresponding 297 single characters. By default GCC ignores trigraphs, but if you 298 request a strictly conforming mode with the '-std' option, or you 299 specify the '-trigraphs' option, then it converts them. 300 301 These are nine three-character sequences, all starting with '??', 302 that are defined by ISO C to stand for single characters. They 303 permit obsolete systems that lack some of C's punctuation to use C. 304 For example, '??/' stands for '\', so '??/n' is a character 305 constant for a newline. 306 307 Trigraphs are not popular and many compilers implement them 308 incorrectly. Portable code should not rely on trigraphs being 309 either converted or ignored. With '-Wtrigraphs' GCC will warn you 310 when a trigraph may change the meaning of your program if it were 311 converted. *Note Wtrigraphs::. 312 313 In a string constant, you can prevent a sequence of question marks 314 from being confused with a trigraph by inserting a backslash 315 between the question marks, or by separating the string literal at 316 the trigraph and making use of string literal concatenation. 317 "(??\?)" is the string '(???)', not '(?]'. Traditional C compilers 318 do not recognize these idioms. 319 320 The nine trigraphs and their replacements are 321 322 Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??- 323 Replacement: [ ] { } # \ ^ | ~ 324 325 3. Continued lines are merged into one long line. 326 327 A continued line is a line which ends with a backslash, '\'. The 328 backslash is removed and the following line is joined with the 329 current one. No space is inserted, so you may split a line 330 anywhere, even in the middle of a word. (It is generally more 331 readable to split lines only at white space.) 332 333 The trailing backslash on a continued line is commonly referred to 334 as a "backslash-newline". 335 336 If there is white space between a backslash and the end of a line, 337 that is still a continued line. However, as this is usually the 338 result of an editing mistake, and many compilers will not accept it 339 as a continued line, GCC will warn you about it. 340 341 4. All comments are replaced with single spaces. 342 343 There are two kinds of comments. "Block comments" begin with '/*' 344 and continue until the next '*/'. Block comments do not nest: 345 346 /* this is /* one comment */ text outside comment 347 348 "Line comments" begin with '//' and continue to the end of the 349 current line. Line comments do not nest either, but it does not 350 matter, because they would end in the same place anyway. 351 352 // this is // one comment 353 text outside comment 354 355 It is safe to put line comments inside block comments, or vice versa. 356 357 /* block comment 358 // contains line comment 359 yet more comment 360 */ outside comment 361 362 // line comment /* contains block comment */ 363 364 But beware of commenting out one end of a block comment with a line 365comment. 366 367 // l.c. /* block comment begins 368 oops! this isn't a comment anymore */ 369 370 Comments are not recognized within string literals. "/* blah */" is 371the string constant '/* blah */', not an empty string. 372 373 Line comments are not in the 1989 edition of the C standard, but they 374are recognized by GCC as an extension. In C++ and in the 1999 edition 375of the C standard, they are an official part of the language. 376 377 Since these transformations happen before all other processing, you 378can split a line mechanically with backslash-newline anywhere. You can 379comment out the end of a line. You can continue a line comment onto the 380next line with backslash-newline. You can even split '/*', '*/', and 381'//' onto multiple lines with backslash-newline. For example: 382 383 /\ 384 * 385 */ # /* 386 */ defi\ 387 ne FO\ 388 O 10\ 389 20 390 391is equivalent to '#define FOO 1020'. All these tricks are extremely 392confusing and should not be used in code intended to be readable. 393 394 There is no way to prevent a backslash at the end of a line from 395being interpreted as a backslash-newline. This cannot affect any 396correct program, however. 397 398 399File: cpp.info, Node: Tokenization, Next: The preprocessing language, Prev: Initial processing, Up: Overview 400 4011.3 Tokenization 402================ 403 404After the textual transformations are finished, the input file is 405converted into a sequence of "preprocessing tokens". These mostly 406correspond to the syntactic tokens used by the C compiler, but there are 407a few differences. White space separates tokens; it is not itself a 408token of any kind. Tokens do not have to be separated by white space, 409but it is often necessary to avoid ambiguities. 410 411 When faced with a sequence of characters that has more than one 412possible tokenization, the preprocessor is greedy. It always makes each 413token, starting from the left, as big as possible before moving on to 414the next token. For instance, 'a+++++b' is interpreted as 415'a ++ ++ + b', not as 'a ++ + ++ b', even though the latter tokenization 416could be part of a valid C program and the former could not. 417 418 Once the input file is broken into tokens, the token boundaries never 419change, except when the '##' preprocessing operator is used to paste 420tokens together. *Note Concatenation::. For example, 421 422 #define foo() bar 423 foo()baz 424 ==> bar baz 425 _not_ 426 ==> barbaz 427 428 The compiler does not re-tokenize the preprocessor's output. Each 429preprocessing token becomes one compiler token. 430 431 Preprocessing tokens fall into five broad classes: identifiers, 432preprocessing numbers, string literals, punctuators, and other. An 433"identifier" is the same as an identifier in C: any sequence of letters, 434digits, or underscores, which begins with a letter or underscore. 435Keywords of C have no significance to the preprocessor; they are 436ordinary identifiers. You can define a macro whose name is a keyword, 437for instance. The only identifier which can be considered a 438preprocessing keyword is 'defined'. *Note Defined::. 439 440 This is mostly true of other languages which use the C preprocessor. 441However, a few of the keywords of C++ are significant even in the 442preprocessor. *Note C++ Named Operators::. 443 444 In the 1999 C standard, identifiers may contain letters which are not 445part of the "basic source character set", at the implementation's 446discretion (such as accented Latin letters, Greek letters, or Chinese 447ideograms). This may be done with an extended character set, or the 448'\u' and '\U' escape sequences. 449 450 As an extension, GCC treats '$' as a letter. This is for 451compatibility with some systems, such as VMS, where '$' is commonly used 452in system-defined function and object names. '$' is not a letter in 453strictly conforming mode, or if you specify the '-$' option. *Note 454Invocation::. 455 456 A "preprocessing number" has a rather bizarre definition. The 457category includes all the normal integer and floating point constants 458one expects of C, but also a number of other things one might not 459initially recognize as a number. Formally, preprocessing numbers begin 460with an optional period, a required decimal digit, and then continue 461with any sequence of letters, digits, underscores, periods, and 462exponents. Exponents are the two-character sequences 'e+', 'e-', 'E+', 463'E-', 'p+', 'p-', 'P+', and 'P-'. (The exponents that begin with 'p' or 464'P' are used for hexadecimal floating-point constants.) 465 466 The purpose of this unusual definition is to isolate the preprocessor 467from the full complexity of numeric constants. It does not have to 468distinguish between lexically valid and invalid floating-point numbers, 469which is complicated. The definition also permits you to split an 470identifier at any position and get exactly two tokens, which can then be 471pasted back together with the '##' operator. 472 473 It's possible for preprocessing numbers to cause programs to be 474misinterpreted. For example, '0xE+12' is a preprocessing number which 475does not translate to any valid numeric constant, therefore a syntax 476error. It does not mean '0xE + 12', which is what you might have 477intended. 478 479 "String literals" are string constants, character constants, and 480header file names (the argument of '#include').(1) String constants and 481character constants are straightforward: "..." or '...'. In either case 482embedded quotes should be escaped with a backslash: '\'' is the 483character constant for '''. There is no limit on the length of a 484character constant, but the value of a character constant that contains 485more than one character is implementation-defined. *Note Implementation 486Details::. 487 488 Header file names either look like string constants, "...", or are 489written with angle brackets instead, <...>. In either case, backslash 490is an ordinary character. There is no way to escape the closing quote 491or angle bracket. The preprocessor looks for the header file in 492different places depending on which form you use. *Note Include 493Operation::. 494 495 No string literal may extend past the end of a line. You may use 496continued lines instead, or string constant concatenation. 497 498 "Punctuators" are all the usual bits of punctuation which are 499meaningful to C and C++. All but three of the punctuation characters in 500ASCII are C punctuators. The exceptions are '@', '$', and '`'. In 501addition, all the two- and three-character operators are punctuators. 502There are also six "digraphs", which the C++ standard calls "alternative 503tokens", which are merely alternate ways to spell other punctuators. 504This is a second attempt to work around missing punctuation in obsolete 505systems. It has no negative side effects, unlike trigraphs, but does 506not cover as much ground. The digraphs and their corresponding normal 507punctuators are: 508 509 Digraph: <% %> <: :> %: %:%: 510 Punctuator: { } [ ] # ## 511 512 Any other single byte is considered "other" and passed on to the 513preprocessor's output unchanged. The C compiler will almost certainly 514reject source code containing "other" tokens. In ASCII, the only 515"other" characters are '@', '$', '`', and control characters other than 516NUL (all bits zero). (Note that '$' is normally considered a letter.) 517All bytes with the high bit set (numeric range 0x7F-0xFF) that were not 518succesfully interpreted as part of an extended character in the input 519encoding are also "other" in the present implementation. 520 521 NUL is a special case because of the high probability that its 522appearance is accidental, and because it may be invisible to the user 523(many terminals do not display NUL at all). Within comments, NULs are 524silently ignored, just as any other character would be. In running 525text, NUL is considered white space. For example, these two directives 526have the same meaning. 527 528 #define X^@1 529 #define X 1 530 531(where '^@' is ASCII NUL). Within string or character constants, NULs 532are preserved. In the latter two cases the preprocessor emits a warning 533message. 534 535 ---------- Footnotes ---------- 536 537 (1) The C standard uses the term "string literal" to refer only to 538what we are calling "string constants". 539 540 541File: cpp.info, Node: The preprocessing language, Prev: Tokenization, Up: Overview 542 5431.4 The preprocessing language 544============================== 545 546After tokenization, the stream of tokens may simply be passed straight 547to the compiler's parser. However, if it contains any operations in the 548"preprocessing language", it will be transformed first. This stage 549corresponds roughly to the standard's "translation phase 4" and is what 550most people think of as the preprocessor's job. 551 552 The preprocessing language consists of "directives" to be executed 553and "macros" to be expanded. Its primary capabilities are: 554 555 * Inclusion of header files. These are files of declarations that 556 can be substituted into your program. 557 558 * Macro expansion. You can define "macros", which are abbreviations 559 for arbitrary fragments of C code. The preprocessor will replace 560 the macros with their definitions throughout the program. Some 561 macros are automatically defined for you. 562 563 * Conditional compilation. You can include or exclude parts of the 564 program according to various conditions. 565 566 * Line control. If you use a program to combine or rearrange source 567 files into an intermediate file which is then compiled, you can use 568 line control to inform the compiler where each source line 569 originally came from. 570 571 * Diagnostics. You can detect problems at compile time and issue 572 errors or warnings. 573 574 There are a few more, less useful, features. 575 576 Except for expansion of predefined macros, all these operations are 577triggered with "preprocessing directives". Preprocessing directives are 578lines in your program that start with '#'. Whitespace is allowed before 579and after the '#'. The '#' is followed by an identifier, the "directive 580name". It specifies the operation to perform. Directives are commonly 581referred to as '#NAME' where NAME is the directive name. For example, 582'#define' is the directive that defines a macro. 583 584 The '#' which begins a directive cannot come from a macro expansion. 585Also, the directive name is not macro expanded. Thus, if 'foo' is 586defined as a macro expanding to 'define', that does not make '#foo' a 587valid preprocessing directive. 588 589 The set of valid directive names is fixed. Programs cannot define 590new preprocessing directives. 591 592 Some directives require arguments; these make up the rest of the 593directive line and must be separated from the directive name by 594whitespace. For example, '#define' must be followed by a macro name and 595the intended expansion of the macro. 596 597 A preprocessing directive cannot cover more than one line. The line 598may, however, be continued with backslash-newline, or by a block comment 599which extends past the end of the line. In either case, when the 600directive is processed, the continuations have already been merged with 601the first line to make one long line. 602 603 604File: cpp.info, Node: Header Files, Next: Macros, Prev: Overview, Up: Top 605 6062 Header Files 607************** 608 609A header file is a file containing C declarations and macro definitions 610(*note Macros::) to be shared between several source files. You request 611the use of a header file in your program by "including" it, with the C 612preprocessing directive '#include'. 613 614 Header files serve two purposes. 615 616 * System header files declare the interfaces to parts of the 617 operating system. You include them in your program to supply the 618 definitions and declarations you need to invoke system calls and 619 libraries. 620 621 * Your own header files contain declarations for interfaces between 622 the source files of your program. Each time you have a group of 623 related declarations and macro definitions all or most of which are 624 needed in several different source files, it is a good idea to 625 create a header file for them. 626 627 Including a header file produces the same results as copying the 628header file into each source file that needs it. Such copying would be 629time-consuming and error-prone. With a header file, the related 630declarations appear in only one place. If they need to be changed, they 631can be changed in one place, and programs that include the header file 632will automatically use the new version when next recompiled. The header 633file eliminates the labor of finding and changing all the copies as well 634as the risk that a failure to find one copy will result in 635inconsistencies within a program. 636 637 In C, the usual convention is to give header files names that end 638with '.h'. It is most portable to use only letters, digits, dashes, and 639underscores in header file names, and at most one dot. 640 641* Menu: 642 643* Include Syntax:: 644* Include Operation:: 645* Search Path:: 646* Once-Only Headers:: 647* Alternatives to Wrapper #ifndef:: 648* Computed Includes:: 649* Wrapper Headers:: 650* System Headers:: 651 652 653File: cpp.info, Node: Include Syntax, Next: Include Operation, Up: Header Files 654 6552.1 Include Syntax 656================== 657 658Both user and system header files are included using the preprocessing 659directive '#include'. It has two variants: 660 661'#include <FILE>' 662 This variant is used for system header files. It searches for a 663 file named FILE in a standard list of system directories. You can 664 prepend directories to this list with the '-I' option (*note 665 Invocation::). 666 667'#include "FILE"' 668 This variant is used for header files of your own program. It 669 searches for a file named FILE first in the directory containing 670 the current file, then in the quote directories and then the same 671 directories used for '<FILE>'. You can prepend directories to the 672 list of quote directories with the '-iquote' option. 673 674 The argument of '#include', whether delimited with quote marks or 675angle brackets, behaves like a string constant in that comments are not 676recognized, and macro names are not expanded. Thus, '#include <x/*y>' 677specifies inclusion of a system header file named 'x/*y'. 678 679 However, if backslashes occur within FILE, they are considered 680ordinary text characters, not escape characters. None of the character 681escape sequences appropriate to string constants in C are processed. 682Thus, '#include "x\n\\y"' specifies a filename containing three 683backslashes. (Some systems interpret '\' as a pathname separator. All 684of these also interpret '/' the same way. It is most portable to use 685only '/'.) 686 687 It is an error if there is anything (other than comments) on the line 688after the file name. 689 690 691File: cpp.info, Node: Include Operation, Next: Search Path, Prev: Include Syntax, Up: Header Files 692 6932.2 Include Operation 694===================== 695 696The '#include' directive works by directing the C preprocessor to scan 697the specified file as input before continuing with the rest of the 698current file. The output from the preprocessor contains the output 699already generated, followed by the output resulting from the included 700file, followed by the output that comes from the text after the 701'#include' directive. For example, if you have a header file 'header.h' 702as follows, 703 704 char *test (void); 705 706and a main program called 'program.c' that uses the header file, like 707this, 708 709 int x; 710 #include "header.h" 711 712 int 713 main (void) 714 { 715 puts (test ()); 716 } 717 718the compiler will see the same token stream as it would if 'program.c' 719read 720 721 int x; 722 char *test (void); 723 724 int 725 main (void) 726 { 727 puts (test ()); 728 } 729 730 Included files are not limited to declarations and macro definitions; 731those are merely the typical uses. Any fragment of a C program can be 732included from another file. The include file could even contain the 733beginning of a statement that is concluded in the containing file, or 734the end of a statement that was started in the including file. However, 735an included file must consist of complete tokens. Comments and string 736literals which have not been closed by the end of an included file are 737invalid. For error recovery, they are considered to end at the end of 738the file. 739 740 To avoid confusion, it is best if header files contain only complete 741syntactic units--function declarations or definitions, type 742declarations, etc. 743 744 The line following the '#include' directive is always treated as a 745separate line by the C preprocessor, even if the included file lacks a 746final newline. 747 748 749File: cpp.info, Node: Search Path, Next: Once-Only Headers, Prev: Include Operation, Up: Header Files 750 7512.3 Search Path 752=============== 753 754By default, the preprocessor looks for header files included by the 755quote form of the directive '#include "FILE"' first relative to the 756directory of the current file, and then in a preconfigured list of 757standard system directories. For example, if '/usr/include/sys/stat.h' 758contains '#include "types.h"', GCC looks for 'types.h' first in 759'/usr/include/sys', then in its usual search path. 760 761 For the angle-bracket form '#include <FILE>', the preprocessor's 762default behavior is to look only in the standard system directories. 763The exact search directory list depends on the target system, how GCC is 764configured, and where it is installed. You can find the default search 765directory list for your version of CPP by invoking it with the '-v' 766option. For example, 767 768 cpp -v /dev/null -o /dev/null 769 770 There are a number of command-line options you can use to add 771additional directories to the search path. The most commonly-used 772option is '-IDIR', which causes DIR to be searched after the current 773directory (for the quote form of the directive) and ahead of the 774standard system directories. You can specify multiple '-I' options on 775the command line, in which case the directories are searched in 776left-to-right order. 777 778 If you need separate control over the search paths for the quote and 779angle-bracket forms of the '#include' directive, you can use the 780'-iquote' and/or '-isystem' options instead of '-I'. *Note 781Invocation::, for a detailed description of these options, as well as 782others that are less generally useful. 783 784 If you specify other options on the command line, such as '-I', that 785affect where the preprocessor searches for header files, the directory 786list printed by the '-v' option reflects the actual search path used by 787the preprocessor. 788 789 Note that you can also prevent the preprocessor from searching any of 790the default system header directories with the '-nostdinc' option. This 791is useful when you are compiling an operating system kernel or some 792other program that does not use the standard C library facilities, or 793the standard C library itself. 794 795 796File: cpp.info, Node: Once-Only Headers, Next: Alternatives to Wrapper #ifndef, Prev: Search Path, Up: Header Files 797 7982.4 Once-Only Headers 799===================== 800 801If a header file happens to be included twice, the compiler will process 802its contents twice. This is very likely to cause an error, e.g. when 803the compiler sees the same structure definition twice. Even if it does 804not, it will certainly waste time. 805 806 The standard way to prevent this is to enclose the entire real 807contents of the file in a conditional, like this: 808 809 /* File foo. */ 810 #ifndef FILE_FOO_SEEN 811 #define FILE_FOO_SEEN 812 813 THE ENTIRE FILE 814 815 #endif /* !FILE_FOO_SEEN */ 816 817 This construct is commonly known as a "wrapper #ifndef". When the 818header is included again, the conditional will be false, because 819'FILE_FOO_SEEN' is defined. The preprocessor will skip over the entire 820contents of the file, and the compiler will not see it twice. 821 822 CPP optimizes even further. It remembers when a header file has a 823wrapper '#ifndef'. If a subsequent '#include' specifies that header, 824and the macro in the '#ifndef' is still defined, it does not bother to 825rescan the file at all. 826 827 You can put comments outside the wrapper. They will not interfere 828with this optimization. 829 830 The macro 'FILE_FOO_SEEN' is called the "controlling macro" or "guard 831macro". In a user header file, the macro name should not begin with 832'_'. In a system header file, it should begin with '__' to avoid 833conflicts with user programs. In any kind of header file, the macro 834name should contain the name of the file and some additional text, to 835avoid conflicts with other header files. 836 837 838File: cpp.info, Node: Alternatives to Wrapper #ifndef, Next: Computed Includes, Prev: Once-Only Headers, Up: Header Files 839 8402.5 Alternatives to Wrapper #ifndef 841=================================== 842 843CPP supports two more ways of indicating that a header file should be 844read only once. Neither one is as portable as a wrapper '#ifndef' and 845we recommend you do not use them in new programs, with the caveat that 846'#import' is standard practice in Objective-C. 847 848 CPP supports a variant of '#include' called '#import' which includes 849a file, but does so at most once. If you use '#import' instead of 850'#include', then you don't need the conditionals inside the header file 851to prevent multiple inclusion of the contents. '#import' is standard in 852Objective-C, but is considered a deprecated extension in C and C++. 853 854 '#import' is not a well designed feature. It requires the users of a 855header file to know that it should only be included once. It is much 856better for the header file's implementor to write the file so that users 857don't need to know this. Using a wrapper '#ifndef' accomplishes this 858goal. 859 860 In the present implementation, a single use of '#import' will prevent 861the file from ever being read again, by either '#import' or '#include'. 862You should not rely on this; do not use both '#import' and '#include' to 863refer to the same header file. 864 865 Another way to prevent a header file from being included more than 866once is with the '#pragma once' directive (*note Pragmas::). '#pragma 867once' does not have the problems that '#import' does, but it is not 868recognized by all preprocessors, so you cannot rely on it in a portable 869program. 870 871 872File: cpp.info, Node: Computed Includes, Next: Wrapper Headers, Prev: Alternatives to Wrapper #ifndef, Up: Header Files 873 8742.6 Computed Includes 875===================== 876 877Sometimes it is necessary to select one of several different header 878files to be included into your program. They might specify 879configuration parameters to be used on different sorts of operating 880systems, for instance. You could do this with a series of conditionals, 881 882 #if SYSTEM_1 883 # include "system_1.h" 884 #elif SYSTEM_2 885 # include "system_2.h" 886 #elif SYSTEM_3 887 ... 888 #endif 889 890 That rapidly becomes tedious. Instead, the preprocessor offers the 891ability to use a macro for the header name. This is called a "computed 892include". Instead of writing a header name as the direct argument of 893'#include', you simply put a macro name there instead: 894 895 #define SYSTEM_H "system_1.h" 896 ... 897 #include SYSTEM_H 898 899'SYSTEM_H' will be expanded, and the preprocessor will look for 900'system_1.h' as if the '#include' had been written that way originally. 901'SYSTEM_H' could be defined by your Makefile with a '-D' option. 902 903 You must be careful when you define the macro. '#define' saves 904tokens, not text. The preprocessor has no way of knowing that the macro 905will be used as the argument of '#include', so it generates ordinary 906tokens, not a header name. This is unlikely to cause problems if you 907use double-quote includes, which are close enough to string constants. 908If you use angle brackets, however, you may have trouble. 909 910 The syntax of a computed include is actually a bit more general than 911the above. If the first non-whitespace character after '#include' is 912not '"' or '<', then the entire line is macro-expanded like running text 913would be. 914 915 If the line expands to a single string constant, the contents of that 916string constant are the file to be included. CPP does not re-examine 917the string for embedded quotes, but neither does it process backslash 918escapes in the string. Therefore 919 920 #define HEADER "a\"b" 921 #include HEADER 922 923looks for a file named 'a\"b'. CPP searches for the file according to 924the rules for double-quoted includes. 925 926 If the line expands to a token stream beginning with a '<' token and 927including a '>' token, then the tokens between the '<' and the first '>' 928are combined to form the filename to be included. Any whitespace 929between tokens is reduced to a single space; then any space after the 930initial '<' is retained, but a trailing space before the closing '>' is 931ignored. CPP searches for the file according to the rules for 932angle-bracket includes. 933 934 In either case, if there are any tokens on the line after the file 935name, an error occurs and the directive is not processed. It is also an 936error if the result of expansion does not match either of the two 937expected forms. 938 939 These rules are implementation-defined behavior according to the C 940standard. To minimize the risk of different compilers interpreting your 941computed includes differently, we recommend you use only a single 942object-like macro which expands to a string constant. This will also 943minimize confusion for people reading your program. 944 945 946File: cpp.info, Node: Wrapper Headers, Next: System Headers, Prev: Computed Includes, Up: Header Files 947 9482.7 Wrapper Headers 949=================== 950 951Sometimes it is necessary to adjust the contents of a system-provided 952header file without editing it directly. GCC's 'fixincludes' operation 953does this, for example. One way to do that would be to create a new 954header file with the same name and insert it in the search path before 955the original header. That works fine as long as you're willing to 956replace the old header entirely. But what if you want to refer to the 957old header from the new one? 958 959 You cannot simply include the old header with '#include'. That will 960start from the beginning, and find your new header again. If your 961header is not protected from multiple inclusion (*note Once-Only 962Headers::), it will recurse infinitely and cause a fatal error. 963 964 You could include the old header with an absolute pathname: 965 #include "/usr/include/old-header.h" 966This works, but is not clean; should the system headers ever move, you 967would have to edit the new headers to match. 968 969 There is no way to solve this problem within the C standard, but you 970can use the GNU extension '#include_next'. It means, "Include the 971_next_ file with this name". This directive works like '#include' 972except in searching for the specified file: it starts searching the list 973of header file directories _after_ the directory in which the current 974file was found. 975 976 Suppose you specify '-I /usr/local/include', and the list of 977directories to search also includes '/usr/include'; and suppose both 978directories contain 'signal.h'. Ordinary '#include <signal.h>' finds 979the file under '/usr/local/include'. If that file contains 980'#include_next <signal.h>', it starts searching after that directory, 981and finds the file in '/usr/include'. 982 983 '#include_next' does not distinguish between '<FILE>' and '"FILE"' 984inclusion, nor does it check that the file you specify has the same name 985as the current file. It simply looks for the file named, starting with 986the directory in the search path after the one where the current file 987was found. 988 989 The use of '#include_next' can lead to great confusion. We recommend 990it be used only when there is no other alternative. In particular, it 991should not be used in the headers belonging to a specific program; it 992should be used only to make global corrections along the lines of 993'fixincludes'. 994 995 996File: cpp.info, Node: System Headers, Prev: Wrapper Headers, Up: Header Files 997 9982.8 System Headers 999================== 1000 1001The header files declaring interfaces to the operating system and 1002runtime libraries often cannot be written in strictly conforming C. 1003Therefore, GCC gives code found in "system headers" special treatment. 1004All warnings, other than those generated by '#warning' (*note 1005Diagnostics::), are suppressed while GCC is processing a system header. 1006Macros defined in a system header are immune to a few warnings wherever 1007they are expanded. This immunity is granted on an ad-hoc basis, when we 1008find that a warning generates lots of false positives because of code in 1009macros defined in system headers. 1010 1011 Normally, only the headers found in specific directories are 1012considered system headers. These directories are determined when GCC is 1013compiled. There are, however, two ways to make normal headers into 1014system headers: 1015 1016 * Header files found in directories added to the search path with the 1017 '-isystem' and '-idirafter' command-line options are treated as 1018 system headers for the purposes of diagnostics. 1019 1020 * There is also a directive, '#pragma GCC system_header', which tells 1021 GCC to consider the rest of the current include file a system 1022 header, no matter where it was found. Code that comes before the 1023 '#pragma' in the file is not affected. '#pragma GCC system_header' 1024 has no effect in the primary source file. 1025 1026 On some targets, such as RS/6000 AIX, GCC implicitly surrounds all 1027system headers with an 'extern "C"' block when compiling as C++. 1028 1029 1030File: cpp.info, Node: Macros, Next: Conditionals, Prev: Header Files, Up: Top 1031 10323 Macros 1033******** 1034 1035A "macro" is a fragment of code which has been given a name. Whenever 1036the name is used, it is replaced by the contents of the macro. There 1037are two kinds of macros. They differ mostly in what they look like when 1038they are used. "Object-like" macros resemble data objects when used, 1039"function-like" macros resemble function calls. 1040 1041 You may define any valid identifier as a macro, even if it is a C 1042keyword. The preprocessor does not know anything about keywords. This 1043can be useful if you wish to hide a keyword such as 'const' from an 1044older compiler that does not understand it. However, the preprocessor 1045operator 'defined' (*note Defined::) can never be defined as a macro, 1046and C++'s named operators (*note C++ Named Operators::) cannot be macros 1047when you are compiling C++. 1048 1049* Menu: 1050 1051* Object-like Macros:: 1052* Function-like Macros:: 1053* Macro Arguments:: 1054* Stringizing:: 1055* Concatenation:: 1056* Variadic Macros:: 1057* Predefined Macros:: 1058* Undefining and Redefining Macros:: 1059* Directives Within Macro Arguments:: 1060* Macro Pitfalls:: 1061 1062 1063File: cpp.info, Node: Object-like Macros, Next: Function-like Macros, Up: Macros 1064 10653.1 Object-like Macros 1066====================== 1067 1068An "object-like macro" is a simple identifier which will be replaced by 1069a code fragment. It is called object-like because it looks like a data 1070object in code that uses it. They are most commonly used to give 1071symbolic names to numeric constants. 1072 1073 You create macros with the '#define' directive. '#define' is 1074followed by the name of the macro and then the token sequence it should 1075be an abbreviation for, which is variously referred to as the macro's 1076"body", "expansion" or "replacement list". For example, 1077 1078 #define BUFFER_SIZE 1024 1079 1080defines a macro named 'BUFFER_SIZE' as an abbreviation for the token 1081'1024'. If somewhere after this '#define' directive there comes a C 1082statement of the form 1083 1084 foo = (char *) malloc (BUFFER_SIZE); 1085 1086then the C preprocessor will recognize and "expand" the macro 1087'BUFFER_SIZE'. The C compiler will see the same tokens as it would if 1088you had written 1089 1090 foo = (char *) malloc (1024); 1091 1092 By convention, macro names are written in uppercase. Programs are 1093easier to read when it is possible to tell at a glance which names are 1094macros. 1095 1096 The macro's body ends at the end of the '#define' line. You may 1097continue the definition onto multiple lines, if necessary, using 1098backslash-newline. When the macro is expanded, however, it will all 1099come out on one line. For example, 1100 1101 #define NUMBERS 1, \ 1102 2, \ 1103 3 1104 int x[] = { NUMBERS }; 1105 ==> int x[] = { 1, 2, 3 }; 1106 1107The most common visible consequence of this is surprising line numbers 1108in error messages. 1109 1110 There is no restriction on what can go in a macro body provided it 1111decomposes into valid preprocessing tokens. Parentheses need not 1112balance, and the body need not resemble valid C code. (If it does not, 1113you may get error messages from the C compiler when you use the macro.) 1114 1115 The C preprocessor scans your program sequentially. Macro 1116definitions take effect at the place you write them. Therefore, the 1117following input to the C preprocessor 1118 1119 foo = X; 1120 #define X 4 1121 bar = X; 1122 1123produces 1124 1125 foo = X; 1126 bar = 4; 1127 1128 When the preprocessor expands a macro name, the macro's expansion 1129replaces the macro invocation, then the expansion is examined for more 1130macros to expand. For example, 1131 1132 #define TABLESIZE BUFSIZE 1133 #define BUFSIZE 1024 1134 TABLESIZE 1135 ==> BUFSIZE 1136 ==> 1024 1137 1138'TABLESIZE' is expanded first to produce 'BUFSIZE', then that macro is 1139expanded to produce the final result, '1024'. 1140 1141 Notice that 'BUFSIZE' was not defined when 'TABLESIZE' was defined. 1142The '#define' for 'TABLESIZE' uses exactly the expansion you specify--in 1143this case, 'BUFSIZE'--and does not check to see whether it too contains 1144macro names. Only when you _use_ 'TABLESIZE' is the result of its 1145expansion scanned for more macro names. 1146 1147 This makes a difference if you change the definition of 'BUFSIZE' at 1148some point in the source file. 'TABLESIZE', defined as shown, will 1149always expand using the definition of 'BUFSIZE' that is currently in 1150effect: 1151 1152 #define BUFSIZE 1020 1153 #define TABLESIZE BUFSIZE 1154 #undef BUFSIZE 1155 #define BUFSIZE 37 1156 1157Now 'TABLESIZE' expands (in two stages) to '37'. 1158 1159 If the expansion of a macro contains its own name, either directly or 1160via intermediate macros, it is not expanded again when the expansion is 1161examined for more macros. This prevents infinite recursion. *Note 1162Self-Referential Macros::, for the precise details. 1163 1164 1165File: cpp.info, Node: Function-like Macros, Next: Macro Arguments, Prev: Object-like Macros, Up: Macros 1166 11673.2 Function-like Macros 1168======================== 1169 1170You can also define macros whose use looks like a function call. These 1171are called "function-like macros". To define a function-like macro, you 1172use the same '#define' directive, but you put a pair of parentheses 1173immediately after the macro name. For example, 1174 1175 #define lang_init() c_init() 1176 lang_init() 1177 ==> c_init() 1178 1179 A function-like macro is only expanded if its name appears with a 1180pair of parentheses after it. If you write just the name, it is left 1181alone. This can be useful when you have a function and a macro of the 1182same name, and you wish to use the function sometimes. 1183 1184 extern void foo(void); 1185 #define foo() /* optimized inline version */ 1186 ... 1187 foo(); 1188 funcptr = foo; 1189 1190 Here the call to 'foo()' will use the macro, but the function pointer 1191will get the address of the real function. If the macro were to be 1192expanded, it would cause a syntax error. 1193 1194 If you put spaces between the macro name and the parentheses in the 1195macro definition, that does not define a function-like macro, it defines 1196an object-like macro whose expansion happens to begin with a pair of 1197parentheses. 1198 1199 #define lang_init () c_init() 1200 lang_init() 1201 ==> () c_init()() 1202 1203 The first two pairs of parentheses in this expansion come from the 1204macro. The third is the pair that was originally after the macro 1205invocation. Since 'lang_init' is an object-like macro, it does not 1206consume those parentheses. 1207 1208 1209File: cpp.info, Node: Macro Arguments, Next: Stringizing, Prev: Function-like Macros, Up: Macros 1210 12113.3 Macro Arguments 1212=================== 1213 1214Function-like macros can take "arguments", just like true functions. To 1215define a macro that uses arguments, you insert "parameters" between the 1216pair of parentheses in the macro definition that make the macro 1217function-like. The parameters must be valid C identifiers, separated by 1218commas and optionally whitespace. 1219 1220 To invoke a macro that takes arguments, you write the name of the 1221macro followed by a list of "actual arguments" in parentheses, separated 1222by commas. The invocation of the macro need not be restricted to a 1223single logical line--it can cross as many lines in the source file as 1224you wish. The number of arguments you give must match the number of 1225parameters in the macro definition. When the macro is expanded, each 1226use of a parameter in its body is replaced by the tokens of the 1227corresponding argument. (You need not use all of the parameters in the 1228macro body.) 1229 1230 As an example, here is a macro that computes the minimum of two 1231numeric values, as it is defined in many C programs, and some uses. 1232 1233 #define min(X, Y) ((X) < (Y) ? (X) : (Y)) 1234 x = min(a, b); ==> x = ((a) < (b) ? (a) : (b)); 1235 y = min(1, 2); ==> y = ((1) < (2) ? (1) : (2)); 1236 z = min(a + 28, *p); ==> z = ((a + 28) < (*p) ? (a + 28) : (*p)); 1237 1238(In this small example you can already see several of the dangers of 1239macro arguments. *Note Macro Pitfalls::, for detailed explanations.) 1240 1241 Leading and trailing whitespace in each argument is dropped, and all 1242whitespace between the tokens of an argument is reduced to a single 1243space. Parentheses within each argument must balance; a comma within 1244such parentheses does not end the argument. However, there is no 1245requirement for square brackets or braces to balance, and they do not 1246prevent a comma from separating arguments. Thus, 1247 1248 macro (array[x = y, x + 1]) 1249 1250passes two arguments to 'macro': 'array[x = y' and 'x + 1]'. If you 1251want to supply 'array[x = y, x + 1]' as an argument, you can write it as 1252'array[(x = y, x + 1)]', which is equivalent C code. 1253 1254 All arguments to a macro are completely macro-expanded before they 1255are substituted into the macro body. After substitution, the complete 1256text is scanned again for macros to expand, including the arguments. 1257This rule may seem strange, but it is carefully designed so you need not 1258worry about whether any function call is actually a macro invocation. 1259You can run into trouble if you try to be too clever, though. *Note 1260Argument Prescan::, for detailed discussion. 1261 1262 For example, 'min (min (a, b), c)' is first expanded to 1263 1264 min (((a) < (b) ? (a) : (b)), (c)) 1265 1266and then to 1267 1268 ((((a) < (b) ? (a) : (b))) < (c) 1269 ? (((a) < (b) ? (a) : (b))) 1270 : (c)) 1271 1272(Line breaks shown here for clarity would not actually be generated.) 1273 1274 You can leave macro arguments empty; this is not an error to the 1275preprocessor (but many macros will then expand to invalid code). You 1276cannot leave out arguments entirely; if a macro takes two arguments, 1277there must be exactly one comma at the top level of its argument list. 1278Here are some silly examples using 'min': 1279 1280 min(, b) ==> (( ) < (b) ? ( ) : (b)) 1281 min(a, ) ==> ((a ) < ( ) ? (a ) : ( )) 1282 min(,) ==> (( ) < ( ) ? ( ) : ( )) 1283 min((,),) ==> (((,)) < ( ) ? ((,)) : ( )) 1284 1285 min() error-> macro "min" requires 2 arguments, but only 1 given 1286 min(,,) error-> macro "min" passed 3 arguments, but takes just 2 1287 1288 Whitespace is not a preprocessing token, so if a macro 'foo' takes 1289one argument, 'foo ()' and 'foo ( )' both supply it an empty argument. 1290Previous GNU preprocessor implementations and documentation were 1291incorrect on this point, insisting that a function-like macro that takes 1292a single argument be passed a space if an empty argument was required. 1293 1294 Macro parameters appearing inside string literals are not replaced by 1295their corresponding actual arguments. 1296 1297 #define foo(x) x, "x" 1298 foo(bar) ==> bar, "x" 1299 1300 1301File: cpp.info, Node: Stringizing, Next: Concatenation, Prev: Macro Arguments, Up: Macros 1302 13033.4 Stringizing 1304=============== 1305 1306Sometimes you may want to convert a macro argument into a string 1307constant. Parameters are not replaced inside string constants, but you 1308can use the '#' preprocessing operator instead. When a macro parameter 1309is used with a leading '#', the preprocessor replaces it with the 1310literal text of the actual argument, converted to a string constant. 1311Unlike normal parameter replacement, the argument is not macro-expanded 1312first. This is called "stringizing". 1313 1314 There is no way to combine an argument with surrounding text and 1315stringize it all together. Instead, you can write a series of adjacent 1316string constants and stringized arguments. The preprocessor replaces 1317the stringized arguments with string constants. The C compiler then 1318combines all the adjacent string constants into one long string. 1319 1320 Here is an example of a macro definition that uses stringizing: 1321 1322 #define WARN_IF(EXP) \ 1323 do { if (EXP) \ 1324 fprintf (stderr, "Warning: " #EXP "\n"); } \ 1325 while (0) 1326 WARN_IF (x == 0); 1327 ==> do { if (x == 0) 1328 fprintf (stderr, "Warning: " "x == 0" "\n"); } while (0); 1329 1330The argument for 'EXP' is substituted once, as-is, into the 'if' 1331statement, and once, stringized, into the argument to 'fprintf'. If 'x' 1332were a macro, it would be expanded in the 'if' statement, but not in the 1333string. 1334 1335 The 'do' and 'while (0)' are a kludge to make it possible to write 1336'WARN_IF (ARG);', which the resemblance of 'WARN_IF' to a function would 1337make C programmers want to do; see *note Swallowing the Semicolon::. 1338 1339 Stringizing in C involves more than putting double-quote characters 1340around the fragment. The preprocessor backslash-escapes the quotes 1341surrounding embedded string constants, and all backslashes within string 1342and character constants, in order to get a valid C string constant with 1343the proper contents. Thus, stringizing 'p = "foo\n";' results in 1344"p = \"foo\\n\";". However, backslashes that are not inside string or 1345character constants are not duplicated: '\n' by itself stringizes to 1346"\n". 1347 1348 All leading and trailing whitespace in text being stringized is 1349ignored. Any sequence of whitespace in the middle of the text is 1350converted to a single space in the stringized result. Comments are 1351replaced by whitespace long before stringizing happens, so they never 1352appear in stringized text. 1353 1354 There is no way to convert a macro argument into a character 1355constant. 1356 1357 If you want to stringize the result of expansion of a macro argument, 1358you have to use two levels of macros. 1359 1360 #define xstr(s) str(s) 1361 #define str(s) #s 1362 #define foo 4 1363 str (foo) 1364 ==> "foo" 1365 xstr (foo) 1366 ==> xstr (4) 1367 ==> str (4) 1368 ==> "4" 1369 1370 's' is stringized when it is used in 'str', so it is not 1371macro-expanded first. But 's' is an ordinary argument to 'xstr', so it 1372is completely macro-expanded before 'xstr' itself is expanded (*note 1373Argument Prescan::). Therefore, by the time 'str' gets to its argument, 1374it has already been macro-expanded. 1375 1376 1377File: cpp.info, Node: Concatenation, Next: Variadic Macros, Prev: Stringizing, Up: Macros 1378 13793.5 Concatenation 1380================= 1381 1382It is often useful to merge two tokens into one while expanding macros. 1383This is called "token pasting" or "token concatenation". The '##' 1384preprocessing operator performs token pasting. When a macro is 1385expanded, the two tokens on either side of each '##' operator are 1386combined into a single token, which then replaces the '##' and the two 1387original tokens in the macro expansion. Usually both will be 1388identifiers, or one will be an identifier and the other a preprocessing 1389number. When pasted, they make a longer identifier. This isn't the 1390only valid case. It is also possible to concatenate two numbers (or a 1391number and a name, such as '1.5' and 'e3') into a number. Also, 1392multi-character operators such as '+=' can be formed by token pasting. 1393 1394 However, two tokens that don't together form a valid token cannot be 1395pasted together. For example, you cannot concatenate 'x' with '+' in 1396either order. If you try, the preprocessor issues a warning and emits 1397the two tokens. Whether it puts white space between the tokens is 1398undefined. It is common to find unnecessary uses of '##' in complex 1399macros. If you get this warning, it is likely that you can simply 1400remove the '##'. 1401 1402 Both the tokens combined by '##' could come from the macro body, but 1403you could just as well write them as one token in the first place. 1404Token pasting is most useful when one or both of the tokens comes from a 1405macro argument. If either of the tokens next to an '##' is a parameter 1406name, it is replaced by its actual argument before '##' executes. As 1407with stringizing, the actual argument is not macro-expanded first. If 1408the argument is empty, that '##' has no effect. 1409 1410 Keep in mind that the C preprocessor converts comments to whitespace 1411before macros are even considered. Therefore, you cannot create a 1412comment by concatenating '/' and '*'. You can put as much whitespace 1413between '##' and its operands as you like, including comments, and you 1414can put comments in arguments that will be concatenated. However, it is 1415an error if '##' appears at either end of a macro body. 1416 1417 Consider a C program that interprets named commands. There probably 1418needs to be a table of commands, perhaps an array of structures declared 1419as follows: 1420 1421 struct command 1422 { 1423 char *name; 1424 void (*function) (void); 1425 }; 1426 1427 struct command commands[] = 1428 { 1429 { "quit", quit_command }, 1430 { "help", help_command }, 1431 ... 1432 }; 1433 1434 It would be cleaner not to have to give each command name twice, once 1435in the string constant and once in the function name. A macro which 1436takes the name of a command as an argument can make this unnecessary. 1437The string constant can be created with stringizing, and the function 1438name by concatenating the argument with '_command'. Here is how it is 1439done: 1440 1441 #define COMMAND(NAME) { #NAME, NAME ## _command } 1442 1443 struct command commands[] = 1444 { 1445 COMMAND (quit), 1446 COMMAND (help), 1447 ... 1448 }; 1449 1450 1451File: cpp.info, Node: Variadic Macros, Next: Predefined Macros, Prev: Concatenation, Up: Macros 1452 14533.6 Variadic Macros 1454=================== 1455 1456A macro can be declared to accept a variable number of arguments much as 1457a function can. The syntax for defining the macro is similar to that of 1458a function. Here is an example: 1459 1460 #define eprintf(...) fprintf (stderr, __VA_ARGS__) 1461 1462 This kind of macro is called "variadic". When the macro is invoked, 1463all the tokens in its argument list after the last named argument (this 1464macro has none), including any commas, become the "variable argument". 1465This sequence of tokens replaces the identifier '__VA_ARGS__' in the 1466macro body wherever it appears. Thus, we have this expansion: 1467 1468 eprintf ("%s:%d: ", input_file, lineno) 1469 ==> fprintf (stderr, "%s:%d: ", input_file, lineno) 1470 1471 The variable argument is completely macro-expanded before it is 1472inserted into the macro expansion, just like an ordinary argument. You 1473may use the '#' and '##' operators to stringize the variable argument or 1474to paste its leading or trailing token with another token. (But see 1475below for an important special case for '##'.) 1476 1477 If your macro is complicated, you may want a more descriptive name 1478for the variable argument than '__VA_ARGS__'. CPP permits this, as an 1479extension. You may write an argument name immediately before the '...'; 1480that name is used for the variable argument. The 'eprintf' macro above 1481could be written 1482 1483 #define eprintf(args...) fprintf (stderr, args) 1484 1485using this extension. You cannot use '__VA_ARGS__' and this extension 1486in the same macro. 1487 1488 You can have named arguments as well as variable arguments in a 1489variadic macro. We could define 'eprintf' like this, instead: 1490 1491 #define eprintf(format, ...) fprintf (stderr, format, __VA_ARGS__) 1492 1493This formulation looks more descriptive, but historically it was less 1494flexible: you had to supply at least one argument after the format 1495string. In standard C, you could not omit the comma separating the 1496named argument from the variable arguments. (Note that this restriction 1497has been lifted in C++2a, and never existed in GNU C; see below.) 1498 1499 Furthermore, if you left the variable argument empty, you would have 1500gotten a syntax error, because there would have been an extra comma 1501after the format string. 1502 1503 eprintf("success!\n", ); 1504 ==> fprintf(stderr, "success!\n", ); 1505 1506 This has been fixed in C++2a, and GNU CPP also has a pair of 1507extensions which deal with this problem. 1508 1509 First, in GNU CPP, and in C++ beginning in C++2a, you are allowed to 1510leave the variable argument out entirely: 1511 1512 eprintf ("success!\n") 1513 ==> fprintf(stderr, "success!\n", ); 1514 1515Second, C++2a introduces the '__VA_OPT__' function macro. This macro 1516may only appear in the definition of a variadic macro. If the variable 1517argument has any tokens, then a '__VA_OPT__' invocation expands to its 1518argument; but if the variable argument does not have any tokens, the 1519'__VA_OPT__' expands to nothing: 1520 1521 #define eprintf(format, ...) \ 1522 fprintf (stderr, format __VA_OPT__(,) __VA_ARGS__) 1523 1524 '__VA_OPT__' is also available in GNU C and GNU C++. 1525 1526 Historically, GNU CPP has also had another extension to handle the 1527trailing comma: the '##' token paste operator has a special meaning when 1528placed between a comma and a variable argument. Despite the 1529introduction of '__VA_OPT__', this extension remains supported in GNU 1530CPP, for backward compatibility. If you write 1531 1532 #define eprintf(format, ...) fprintf (stderr, format, ##__VA_ARGS__) 1533 1534and the variable argument is left out when the 'eprintf' macro is used, 1535then the comma before the '##' will be deleted. This does _not_ happen 1536if you pass an empty argument, nor does it happen if the token preceding 1537'##' is anything other than a comma. 1538 1539 eprintf ("success!\n") 1540 ==> fprintf(stderr, "success!\n"); 1541 1542The above explanation is ambiguous about the case where the only macro 1543parameter is a variable arguments parameter, as it is meaningless to try 1544to distinguish whether no argument at all is an empty argument or a 1545missing argument. CPP retains the comma when conforming to a specific C 1546standard. Otherwise the comma is dropped as an extension to the 1547standard. 1548 1549 The C standard mandates that the only place the identifier 1550'__VA_ARGS__' can appear is in the replacement list of a variadic macro. 1551It may not be used as a macro name, macro argument name, or within a 1552different type of macro. It may also be forbidden in open text; the 1553standard is ambiguous. We recommend you avoid using it except for its 1554defined purpose. 1555 1556 Likewise, C++ forbids '__VA_OPT__' anywhere outside the replacement 1557list of a variadic macro. 1558 1559 Variadic macros became a standard part of the C language with C99. 1560GNU CPP previously supported them with a named variable argument 1561('args...', not '...' and '__VA_ARGS__'), which is still supported for 1562backward compatibility. 1563 1564 1565File: cpp.info, Node: Predefined Macros, Next: Undefining and Redefining Macros, Prev: Variadic Macros, Up: Macros 1566 15673.7 Predefined Macros 1568===================== 1569 1570Several object-like macros are predefined; you use them without 1571supplying their definitions. They fall into three classes: standard, 1572common, and system-specific. 1573 1574 In C++, there is a fourth category, the named operators. They act 1575like predefined macros, but you cannot undefine them. 1576 1577* Menu: 1578 1579* Standard Predefined Macros:: 1580* Common Predefined Macros:: 1581* System-specific Predefined Macros:: 1582* C++ Named Operators:: 1583 1584 1585File: cpp.info, Node: Standard Predefined Macros, Next: Common Predefined Macros, Up: Predefined Macros 1586 15873.7.1 Standard Predefined Macros 1588-------------------------------- 1589 1590The standard predefined macros are specified by the relevant language 1591standards, so they are available with all compilers that implement those 1592standards. Older compilers may not provide all of them. Their names 1593all start with double underscores. 1594 1595'__FILE__' 1596 This macro expands to the name of the current input file, in the 1597 form of a C string constant. This is the path by which the 1598 preprocessor opened the file, not the short name specified in 1599 '#include' or as the input file name argument. For example, 1600 '"/usr/local/include/myheader.h"' is a possible expansion of this 1601 macro. 1602 1603'__LINE__' 1604 This macro expands to the current input line number, in the form of 1605 a decimal integer constant. While we call it a predefined macro, 1606 it's a pretty strange macro, since its "definition" changes with 1607 each new line of source code. 1608 1609 '__FILE__' and '__LINE__' are useful in generating an error message 1610to report an inconsistency detected by the program; the message can 1611state the source line at which the inconsistency was detected. For 1612example, 1613 1614 fprintf (stderr, "Internal error: " 1615 "negative string length " 1616 "%d at %s, line %d.", 1617 length, __FILE__, __LINE__); 1618 1619 An '#include' directive changes the expansions of '__FILE__' and 1620'__LINE__' to correspond to the included file. At the end of that file, 1621when processing resumes on the input file that contained the '#include' 1622directive, the expansions of '__FILE__' and '__LINE__' revert to the 1623values they had before the '#include' (but '__LINE__' is then 1624incremented by one as processing moves to the line after the 1625'#include'). 1626 1627 A '#line' directive changes '__LINE__', and may change '__FILE__' as 1628well. *Note Line Control::. 1629 1630 C99 introduced '__func__', and GCC has provided '__FUNCTION__' for a 1631long time. Both of these are strings containing the name of the current 1632function (there are slight semantic differences; see the GCC manual). 1633Neither of them is a macro; the preprocessor does not know the name of 1634the current function. They tend to be useful in conjunction with 1635'__FILE__' and '__LINE__', though. 1636 1637'__DATE__' 1638 This macro expands to a string constant that describes the date on 1639 which the preprocessor is being run. The string constant contains 1640 eleven characters and looks like '"Feb 12 1996"'. If the day of 1641 the month is less than 10, it is padded with a space on the left. 1642 1643 If GCC cannot determine the current date, it will emit a warning 1644 message (once per compilation) and '__DATE__' will expand to 1645 '"??? ?? ????"'. 1646 1647'__TIME__' 1648 This macro expands to a string constant that describes the time at 1649 which the preprocessor is being run. The string constant contains 1650 eight characters and looks like '"23:59:01"'. 1651 1652 If GCC cannot determine the current time, it will emit a warning 1653 message (once per compilation) and '__TIME__' will expand to 1654 '"??:??:??"'. 1655 1656'__STDC__' 1657 In normal operation, this macro expands to the constant 1, to 1658 signify that this compiler conforms to ISO Standard C. If GNU CPP 1659 is used with a compiler other than GCC, this is not necessarily 1660 true; however, the preprocessor always conforms to the standard 1661 unless the '-traditional-cpp' option is used. 1662 1663 This macro is not defined if the '-traditional-cpp' option is used. 1664 1665 On some hosts, the system compiler uses a different convention, 1666 where '__STDC__' is normally 0, but is 1 if the user specifies 1667 strict conformance to the C Standard. CPP follows the host 1668 convention when processing system header files, but when processing 1669 user files '__STDC__' is always 1. This has been reported to cause 1670 problems; for instance, some versions of Solaris provide X Windows 1671 headers that expect '__STDC__' to be either undefined or 1. *Note 1672 Invocation::. 1673 1674'__STDC_VERSION__' 1675 This macro expands to the C Standard's version number, a long 1676 integer constant of the form 'YYYYMML' where YYYY and MM are the 1677 year and month of the Standard version. This signifies which 1678 version of the C Standard the compiler conforms to. Like 1679 '__STDC__', this is not necessarily accurate for the entire 1680 implementation, unless GNU CPP is being used with GCC. 1681 1682 The value '199409L' signifies the 1989 C standard as amended in 1683 1994, which is the current default; the value '199901L' signifies 1684 the 1999 revision of the C standard; the value '201112L' signifies 1685 the 2011 revision of the C standard; the value '201710L' signifies 1686 the 2017 revision of the C standard (which is otherwise identical 1687 to the 2011 version apart from correction of defects). An 1688 unspecified value larger than '201710L' is used for the 1689 experimental '-std=c2x' and '-std=gnu2x' modes. 1690 1691 This macro is not defined if the '-traditional-cpp' option is used, 1692 nor when compiling C++ or Objective-C. 1693 1694'__STDC_HOSTED__' 1695 This macro is defined, with value 1, if the compiler's target is a 1696 "hosted environment". A hosted environment has the complete 1697 facilities of the standard C library available. 1698 1699'__cplusplus' 1700 This macro is defined when the C++ compiler is in use. You can use 1701 '__cplusplus' to test whether a header is compiled by a C compiler 1702 or a C++ compiler. This macro is similar to '__STDC_VERSION__', in 1703 that it expands to a version number. Depending on the language 1704 standard selected, the value of the macro is '199711L' for the 1998 1705 C++ standard, '201103L' for the 2011 C++ standard, '201402L' for 1706 the 2014 C++ standard, '201703L' for the 2017 C++ standard, or an 1707 unspecified value strictly larger than '201703L' for the 1708 experimental languages enabled by '-std=c++2a' and '-std=gnu++2a'. 1709 1710'__OBJC__' 1711 This macro is defined, with value 1, when the Objective-C compiler 1712 is in use. You can use '__OBJC__' to test whether a header is 1713 compiled by a C compiler or an Objective-C compiler. 1714 1715'__ASSEMBLER__' 1716 This macro is defined with value 1 when preprocessing assembly 1717 language. 1718 1719 1720File: cpp.info, Node: Common Predefined Macros, Next: System-specific Predefined Macros, Prev: Standard Predefined Macros, Up: Predefined Macros 1721 17223.7.2 Common Predefined Macros 1723------------------------------ 1724 1725The common predefined macros are GNU C extensions. They are available 1726with the same meanings regardless of the machine or operating system on 1727which you are using GNU C or GNU Fortran. Their names all start with 1728double underscores. 1729 1730'__COUNTER__' 1731 This macro expands to sequential integral values starting from 0. 1732 In conjunction with the '##' operator, this provides a convenient 1733 means to generate unique identifiers. Care must be taken to ensure 1734 that '__COUNTER__' is not expanded prior to inclusion of 1735 precompiled headers which use it. Otherwise, the precompiled 1736 headers will not be used. 1737 1738'__GFORTRAN__' 1739 The GNU Fortran compiler defines this. 1740 1741'__GNUC__' 1742'__GNUC_MINOR__' 1743'__GNUC_PATCHLEVEL__' 1744 These macros are defined by all GNU compilers that use the C 1745 preprocessor: C, C++, Objective-C and Fortran. Their values are 1746 the major version, minor version, and patch level of the compiler, 1747 as integer constants. For example, GCC version X.Y.Z defines 1748 '__GNUC__' to X, '__GNUC_MINOR__' to Y, and '__GNUC_PATCHLEVEL__' 1749 to Z. These macros are also defined if you invoke the preprocessor 1750 directly. 1751 1752 If all you need to know is whether or not your program is being 1753 compiled by GCC, or a non-GCC compiler that claims to accept the 1754 GNU C dialects, you can simply test '__GNUC__'. If you need to 1755 write code which depends on a specific version, you must be more 1756 careful. Each time the minor version is increased, the patch level 1757 is reset to zero; each time the major version is increased, the 1758 minor version and patch level are reset. If you wish to use the 1759 predefined macros directly in the conditional, you will need to 1760 write it like this: 1761 1762 /* Test for GCC > 3.2.0 */ 1763 #if __GNUC__ > 3 || \ 1764 (__GNUC__ == 3 && (__GNUC_MINOR__ > 2 || \ 1765 (__GNUC_MINOR__ == 2 && \ 1766 __GNUC_PATCHLEVEL__ > 0)) 1767 1768 Another approach is to use the predefined macros to calculate a 1769 single number, then compare that against a threshold: 1770 1771 #define GCC_VERSION (__GNUC__ * 10000 \ 1772 + __GNUC_MINOR__ * 100 \ 1773 + __GNUC_PATCHLEVEL__) 1774 ... 1775 /* Test for GCC > 3.2.0 */ 1776 #if GCC_VERSION > 30200 1777 1778 Many people find this form easier to understand. 1779 1780'__GNUG__' 1781 The GNU C++ compiler defines this. Testing it is equivalent to 1782 testing '(__GNUC__ && __cplusplus)'. 1783 1784'__STRICT_ANSI__' 1785 GCC defines this macro if and only if the '-ansi' switch, or a 1786 '-std' switch specifying strict conformance to some version of ISO 1787 C or ISO C++, was specified when GCC was invoked. It is defined to 1788 '1'. This macro exists primarily to direct GNU libc's header files 1789 to use only definitions found in standard C. 1790 1791'__BASE_FILE__' 1792 This macro expands to the name of the main input file, in the form 1793 of a C string constant. This is the source file that was specified 1794 on the command line of the preprocessor or C compiler. 1795 1796'__INCLUDE_LEVEL__' 1797 This macro expands to a decimal integer constant that represents 1798 the depth of nesting in include files. The value of this macro is 1799 incremented on every '#include' directive and decremented at the 1800 end of every included file. It starts out at 0, its value within 1801 the base file specified on the command line. 1802 1803'__ELF__' 1804 This macro is defined if the target uses the ELF object format. 1805 1806'__VERSION__' 1807 This macro expands to a string constant which describes the version 1808 of the compiler in use. You should not rely on its contents having 1809 any particular form, but it can be counted on to contain at least 1810 the release number. 1811 1812'__OPTIMIZE__' 1813'__OPTIMIZE_SIZE__' 1814'__NO_INLINE__' 1815 These macros describe the compilation mode. '__OPTIMIZE__' is 1816 defined in all optimizing compilations. '__OPTIMIZE_SIZE__' is 1817 defined if the compiler is optimizing for size, not speed. 1818 '__NO_INLINE__' is defined if no functions will be inlined into 1819 their callers (when not optimizing, or when inlining has been 1820 specifically disabled by '-fno-inline'). 1821 1822 These macros cause certain GNU header files to provide optimized 1823 definitions, using macros or inline functions, of system library 1824 functions. You should not use these macros in any way unless you 1825 make sure that programs will execute with the same effect whether 1826 or not they are defined. If they are defined, their value is 1. 1827 1828'__GNUC_GNU_INLINE__' 1829 GCC defines this macro if functions declared 'inline' will be 1830 handled in GCC's traditional gnu90 mode. Object files will contain 1831 externally visible definitions of all functions declared 'inline' 1832 without 'extern' or 'static'. They will not contain any 1833 definitions of any functions declared 'extern inline'. 1834 1835'__GNUC_STDC_INLINE__' 1836 GCC defines this macro if functions declared 'inline' will be 1837 handled according to the ISO C99 or later standards. Object files 1838 will contain externally visible definitions of all functions 1839 declared 'extern inline'. They will not contain definitions of any 1840 functions declared 'inline' without 'extern'. 1841 1842 If this macro is defined, GCC supports the 'gnu_inline' function 1843 attribute as a way to always get the gnu90 behavior. 1844 1845'__CHAR_UNSIGNED__' 1846 GCC defines this macro if and only if the data type 'char' is 1847 unsigned on the target machine. It exists to cause the standard 1848 header file 'limits.h' to work correctly. You should not use this 1849 macro yourself; instead, refer to the standard macros defined in 1850 'limits.h'. 1851 1852'__WCHAR_UNSIGNED__' 1853 Like '__CHAR_UNSIGNED__', this macro is defined if and only if the 1854 data type 'wchar_t' is unsigned and the front-end is in C++ mode. 1855 1856'__REGISTER_PREFIX__' 1857 This macro expands to a single token (not a string constant) which 1858 is the prefix applied to CPU register names in assembly language 1859 for this target. You can use it to write assembly that is usable 1860 in multiple environments. For example, in the 'm68k-aout' 1861 environment it expands to nothing, but in the 'm68k-coff' 1862 environment it expands to a single '%'. 1863 1864'__USER_LABEL_PREFIX__' 1865 This macro expands to a single token which is the prefix applied to 1866 user labels (symbols visible to C code) in assembly. For example, 1867 in the 'm68k-aout' environment it expands to an '_', but in the 1868 'm68k-coff' environment it expands to nothing. 1869 1870 This macro will have the correct definition even if 1871 '-f(no-)underscores' is in use, but it will not be correct if 1872 target-specific options that adjust this prefix are used (e.g. the 1873 OSF/rose '-mno-underscores' option). 1874 1875'__SIZE_TYPE__' 1876'__PTRDIFF_TYPE__' 1877'__WCHAR_TYPE__' 1878'__WINT_TYPE__' 1879'__INTMAX_TYPE__' 1880'__UINTMAX_TYPE__' 1881'__SIG_ATOMIC_TYPE__' 1882'__INT8_TYPE__' 1883'__INT16_TYPE__' 1884'__INT32_TYPE__' 1885'__INT64_TYPE__' 1886'__UINT8_TYPE__' 1887'__UINT16_TYPE__' 1888'__UINT32_TYPE__' 1889'__UINT64_TYPE__' 1890'__INT_LEAST8_TYPE__' 1891'__INT_LEAST16_TYPE__' 1892'__INT_LEAST32_TYPE__' 1893'__INT_LEAST64_TYPE__' 1894'__UINT_LEAST8_TYPE__' 1895'__UINT_LEAST16_TYPE__' 1896'__UINT_LEAST32_TYPE__' 1897'__UINT_LEAST64_TYPE__' 1898'__INT_FAST8_TYPE__' 1899'__INT_FAST16_TYPE__' 1900'__INT_FAST32_TYPE__' 1901'__INT_FAST64_TYPE__' 1902'__UINT_FAST8_TYPE__' 1903'__UINT_FAST16_TYPE__' 1904'__UINT_FAST32_TYPE__' 1905'__UINT_FAST64_TYPE__' 1906'__INTPTR_TYPE__' 1907'__UINTPTR_TYPE__' 1908 These macros are defined to the correct underlying types for the 1909 'size_t', 'ptrdiff_t', 'wchar_t', 'wint_t', 'intmax_t', 1910 'uintmax_t', 'sig_atomic_t', 'int8_t', 'int16_t', 'int32_t', 1911 'int64_t', 'uint8_t', 'uint16_t', 'uint32_t', 'uint64_t', 1912 'int_least8_t', 'int_least16_t', 'int_least32_t', 'int_least64_t', 1913 'uint_least8_t', 'uint_least16_t', 'uint_least32_t', 1914 'uint_least64_t', 'int_fast8_t', 'int_fast16_t', 'int_fast32_t', 1915 'int_fast64_t', 'uint_fast8_t', 'uint_fast16_t', 'uint_fast32_t', 1916 'uint_fast64_t', 'intptr_t', and 'uintptr_t' typedefs, 1917 respectively. They exist to make the standard header files 1918 'stddef.h', 'stdint.h', and 'wchar.h' work correctly. You should 1919 not use these macros directly; instead, include the appropriate 1920 headers and use the typedefs. Some of these macros may not be 1921 defined on particular systems if GCC does not provide a 'stdint.h' 1922 header on those systems. 1923 1924'__CHAR_BIT__' 1925 Defined to the number of bits used in the representation of the 1926 'char' data type. It exists to make the standard header given 1927 numerical limits work correctly. You should not use this macro 1928 directly; instead, include the appropriate headers. 1929 1930'__SCHAR_MAX__' 1931'__WCHAR_MAX__' 1932'__SHRT_MAX__' 1933'__INT_MAX__' 1934'__LONG_MAX__' 1935'__LONG_LONG_MAX__' 1936'__WINT_MAX__' 1937'__SIZE_MAX__' 1938'__PTRDIFF_MAX__' 1939'__INTMAX_MAX__' 1940'__UINTMAX_MAX__' 1941'__SIG_ATOMIC_MAX__' 1942'__INT8_MAX__' 1943'__INT16_MAX__' 1944'__INT32_MAX__' 1945'__INT64_MAX__' 1946'__UINT8_MAX__' 1947'__UINT16_MAX__' 1948'__UINT32_MAX__' 1949'__UINT64_MAX__' 1950'__INT_LEAST8_MAX__' 1951'__INT_LEAST16_MAX__' 1952'__INT_LEAST32_MAX__' 1953'__INT_LEAST64_MAX__' 1954'__UINT_LEAST8_MAX__' 1955'__UINT_LEAST16_MAX__' 1956'__UINT_LEAST32_MAX__' 1957'__UINT_LEAST64_MAX__' 1958'__INT_FAST8_MAX__' 1959'__INT_FAST16_MAX__' 1960'__INT_FAST32_MAX__' 1961'__INT_FAST64_MAX__' 1962'__UINT_FAST8_MAX__' 1963'__UINT_FAST16_MAX__' 1964'__UINT_FAST32_MAX__' 1965'__UINT_FAST64_MAX__' 1966'__INTPTR_MAX__' 1967'__UINTPTR_MAX__' 1968'__WCHAR_MIN__' 1969'__WINT_MIN__' 1970'__SIG_ATOMIC_MIN__' 1971 Defined to the maximum value of the 'signed char', 'wchar_t', 1972 'signed short', 'signed int', 'signed long', 'signed long long', 1973 'wint_t', 'size_t', 'ptrdiff_t', 'intmax_t', 'uintmax_t', 1974 'sig_atomic_t', 'int8_t', 'int16_t', 'int32_t', 'int64_t', 1975 'uint8_t', 'uint16_t', 'uint32_t', 'uint64_t', 'int_least8_t', 1976 'int_least16_t', 'int_least32_t', 'int_least64_t', 'uint_least8_t', 1977 'uint_least16_t', 'uint_least32_t', 'uint_least64_t', 1978 'int_fast8_t', 'int_fast16_t', 'int_fast32_t', 'int_fast64_t', 1979 'uint_fast8_t', 'uint_fast16_t', 'uint_fast32_t', 'uint_fast64_t', 1980 'intptr_t', and 'uintptr_t' types and to the minimum value of the 1981 'wchar_t', 'wint_t', and 'sig_atomic_t' types respectively. They 1982 exist to make the standard header given numerical limits work 1983 correctly. You should not use these macros directly; instead, 1984 include the appropriate headers. Some of these macros may not be 1985 defined on particular systems if GCC does not provide a 'stdint.h' 1986 header on those systems. 1987 1988'__INT8_C' 1989'__INT16_C' 1990'__INT32_C' 1991'__INT64_C' 1992'__UINT8_C' 1993'__UINT16_C' 1994'__UINT32_C' 1995'__UINT64_C' 1996'__INTMAX_C' 1997'__UINTMAX_C' 1998 Defined to implementations of the standard 'stdint.h' macros with 1999 the same names without the leading '__'. They exist the make the 2000 implementation of that header work correctly. You should not use 2001 these macros directly; instead, include the appropriate headers. 2002 Some of these macros may not be defined on particular systems if 2003 GCC does not provide a 'stdint.h' header on those systems. 2004 2005'__SCHAR_WIDTH__' 2006'__SHRT_WIDTH__' 2007'__INT_WIDTH__' 2008'__LONG_WIDTH__' 2009'__LONG_LONG_WIDTH__' 2010'__PTRDIFF_WIDTH__' 2011'__SIG_ATOMIC_WIDTH__' 2012'__SIZE_WIDTH__' 2013'__WCHAR_WIDTH__' 2014'__WINT_WIDTH__' 2015'__INT_LEAST8_WIDTH__' 2016'__INT_LEAST16_WIDTH__' 2017'__INT_LEAST32_WIDTH__' 2018'__INT_LEAST64_WIDTH__' 2019'__INT_FAST8_WIDTH__' 2020'__INT_FAST16_WIDTH__' 2021'__INT_FAST32_WIDTH__' 2022'__INT_FAST64_WIDTH__' 2023'__INTPTR_WIDTH__' 2024'__INTMAX_WIDTH__' 2025 Defined to the bit widths of the corresponding types. They exist 2026 to make the implementations of 'limits.h' and 'stdint.h' behave 2027 correctly. You should not use these macros directly; instead, 2028 include the appropriate headers. Some of these macros may not be 2029 defined on particular systems if GCC does not provide a 'stdint.h' 2030 header on those systems. 2031 2032'__SIZEOF_INT__' 2033'__SIZEOF_LONG__' 2034'__SIZEOF_LONG_LONG__' 2035'__SIZEOF_SHORT__' 2036'__SIZEOF_POINTER__' 2037'__SIZEOF_FLOAT__' 2038'__SIZEOF_DOUBLE__' 2039'__SIZEOF_LONG_DOUBLE__' 2040'__SIZEOF_SIZE_T__' 2041'__SIZEOF_WCHAR_T__' 2042'__SIZEOF_WINT_T__' 2043'__SIZEOF_PTRDIFF_T__' 2044 Defined to the number of bytes of the C standard data types: 'int', 2045 'long', 'long long', 'short', 'void *', 'float', 'double', 'long 2046 double', 'size_t', 'wchar_t', 'wint_t' and 'ptrdiff_t'. 2047 2048'__BYTE_ORDER__' 2049'__ORDER_LITTLE_ENDIAN__' 2050'__ORDER_BIG_ENDIAN__' 2051'__ORDER_PDP_ENDIAN__' 2052 '__BYTE_ORDER__' is defined to one of the values 2053 '__ORDER_LITTLE_ENDIAN__', '__ORDER_BIG_ENDIAN__', or 2054 '__ORDER_PDP_ENDIAN__' to reflect the layout of multi-byte and 2055 multi-word quantities in memory. If '__BYTE_ORDER__' is equal to 2056 '__ORDER_LITTLE_ENDIAN__' or '__ORDER_BIG_ENDIAN__', then 2057 multi-byte and multi-word quantities are laid out identically: the 2058 byte (word) at the lowest address is the least significant or most 2059 significant byte (word) of the quantity, respectively. If 2060 '__BYTE_ORDER__' is equal to '__ORDER_PDP_ENDIAN__', then bytes in 2061 16-bit words are laid out in a little-endian fashion, whereas the 2062 16-bit subwords of a 32-bit quantity are laid out in big-endian 2063 fashion. 2064 2065 You should use these macros for testing like this: 2066 2067 /* Test for a little-endian machine */ 2068 #if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__ 2069 2070'__FLOAT_WORD_ORDER__' 2071 '__FLOAT_WORD_ORDER__' is defined to one of the values 2072 '__ORDER_LITTLE_ENDIAN__' or '__ORDER_BIG_ENDIAN__' to reflect the 2073 layout of the words of multi-word floating-point quantities. 2074 2075'__DEPRECATED' 2076 This macro is defined, with value 1, when compiling a C++ source 2077 file with warnings about deprecated constructs enabled. These 2078 warnings are enabled by default, but can be disabled with 2079 '-Wno-deprecated'. 2080 2081'__EXCEPTIONS' 2082 This macro is defined, with value 1, when compiling a C++ source 2083 file with exceptions enabled. If '-fno-exceptions' is used when 2084 compiling the file, then this macro is not defined. 2085 2086'__GXX_RTTI' 2087 This macro is defined, with value 1, when compiling a C++ source 2088 file with runtime type identification enabled. If '-fno-rtti' is 2089 used when compiling the file, then this macro is not defined. 2090 2091'__USING_SJLJ_EXCEPTIONS__' 2092 This macro is defined, with value 1, if the compiler uses the old 2093 mechanism based on 'setjmp' and 'longjmp' for exception handling. 2094 2095'__GXX_EXPERIMENTAL_CXX0X__' 2096 This macro is defined when compiling a C++ source file with C++11 2097 features enabled, i.e., for all C++ language dialects except 2098 '-std=c++98' and '-std=gnu++98'. This macro is obsolete, but can 2099 be used to detect experimental C++0x features in very old versions 2100 of GCC. Since GCC 4.7.0 the '__cplusplus' macro is defined 2101 correctly, so most code should test '__cplusplus >= 201103L' 2102 instead of using this macro. 2103 2104'__GXX_WEAK__' 2105 This macro is defined when compiling a C++ source file. It has the 2106 value 1 if the compiler will use weak symbols, COMDAT sections, or 2107 other similar techniques to collapse symbols with "vague linkage" 2108 that are defined in multiple translation units. If the compiler 2109 will not collapse such symbols, this macro is defined with value 0. 2110 In general, user code should not need to make use of this macro; 2111 the purpose of this macro is to ease implementation of the C++ 2112 runtime library provided with G++. 2113 2114'__NEXT_RUNTIME__' 2115 This macro is defined, with value 1, if (and only if) the NeXT 2116 runtime (as in '-fnext-runtime') is in use for Objective-C. If the 2117 GNU runtime is used, this macro is not defined, so that you can use 2118 this macro to determine which runtime (NeXT or GNU) is being used. 2119 2120'__LP64__' 2121'_LP64' 2122 These macros are defined, with value 1, if (and only if) the 2123 compilation is for a target where 'long int' and pointer both use 2124 64-bits and 'int' uses 32-bit. 2125 2126'__SSP__' 2127 This macro is defined, with value 1, when '-fstack-protector' is in 2128 use. 2129 2130'__SSP_ALL__' 2131 This macro is defined, with value 2, when '-fstack-protector-all' 2132 is in use. 2133 2134'__SSP_STRONG__' 2135 This macro is defined, with value 3, when 2136 '-fstack-protector-strong' is in use. 2137 2138'__SSP_EXPLICIT__' 2139 This macro is defined, with value 4, when 2140 '-fstack-protector-explicit' is in use. 2141 2142'__SANITIZE_ADDRESS__' 2143 This macro is defined, with value 1, when '-fsanitize=address' or 2144 '-fsanitize=kernel-address' are in use. 2145 2146'__SANITIZE_THREAD__' 2147 This macro is defined, with value 1, when '-fsanitize=thread' is in 2148 use. 2149 2150'__TIMESTAMP__' 2151 This macro expands to a string constant that describes the date and 2152 time of the last modification of the current source file. The 2153 string constant contains abbreviated day of the week, month, day of 2154 the month, time in hh:mm:ss form, year and looks like 2155 '"Sun Sep 16 01:03:52 1973"'. If the day of the month is less than 2156 10, it is padded with a space on the left. 2157 2158 If GCC cannot determine the current date, it will emit a warning 2159 message (once per compilation) and '__TIMESTAMP__' will expand to 2160 '"??? ??? ?? ??:??:?? ????"'. 2161 2162'__GCC_HAVE_SYNC_COMPARE_AND_SWAP_1' 2163'__GCC_HAVE_SYNC_COMPARE_AND_SWAP_2' 2164'__GCC_HAVE_SYNC_COMPARE_AND_SWAP_4' 2165'__GCC_HAVE_SYNC_COMPARE_AND_SWAP_8' 2166'__GCC_HAVE_SYNC_COMPARE_AND_SWAP_16' 2167 These macros are defined when the target processor supports atomic 2168 compare and swap operations on operands 1, 2, 4, 8 or 16 bytes in 2169 length, respectively. 2170 2171'__HAVE_SPECULATION_SAFE_VALUE' 2172 This macro is defined with the value 1 to show that this version of 2173 GCC supports '__builtin_speculation_safe_value'. 2174 2175'__GCC_HAVE_DWARF2_CFI_ASM' 2176 This macro is defined when the compiler is emitting DWARF CFI 2177 directives to the assembler. When this is defined, it is possible 2178 to emit those same directives in inline assembly. 2179 2180'__FP_FAST_FMA' 2181'__FP_FAST_FMAF' 2182'__FP_FAST_FMAL' 2183 These macros are defined with value 1 if the backend supports the 2184 'fma', 'fmaf', and 'fmal' builtin functions, so that the include 2185 file 'math.h' can define the macros 'FP_FAST_FMA', 'FP_FAST_FMAF', 2186 and 'FP_FAST_FMAL' for compatibility with the 1999 C standard. 2187 2188'__FP_FAST_FMAF16' 2189'__FP_FAST_FMAF32' 2190'__FP_FAST_FMAF64' 2191'__FP_FAST_FMAF128' 2192'__FP_FAST_FMAF32X' 2193'__FP_FAST_FMAF64X' 2194'__FP_FAST_FMAF128X' 2195 These macros are defined with the value 1 if the backend supports 2196 the 'fma' functions using the additional '_FloatN' and '_FloatNx' 2197 types that are defined in ISO/IEC TS 18661-3:2015. The include 2198 file 'math.h' can define the 'FP_FAST_FMAFN' and 'FP_FAST_FMAFNx' 2199 macros if the user defined '__STDC_WANT_IEC_60559_TYPES_EXT__' 2200 before including 'math.h'. 2201 2202'__GCC_IEC_559' 2203 This macro is defined to indicate the intended level of support for 2204 IEEE 754 (IEC 60559) floating-point arithmetic. It expands to a 2205 nonnegative integer value. If 0, it indicates that the combination 2206 of the compiler configuration and the command-line options is not 2207 intended to support IEEE 754 arithmetic for 'float' and 'double' as 2208 defined in C99 and C11 Annex F (for example, that the standard 2209 rounding modes and exceptions are not supported, or that 2210 optimizations are enabled that conflict with IEEE 754 semantics). 2211 If 1, it indicates that IEEE 754 arithmetic is intended to be 2212 supported; this does not mean that all relevant language features 2213 are supported by GCC. If 2 or more, it additionally indicates 2214 support for IEEE 754-2008 (in particular, that the binary encodings 2215 for quiet and signaling NaNs are as specified in IEEE 754-2008). 2216 2217 This macro does not indicate the default state of command-line 2218 options that control optimizations that C99 and C11 permit to be 2219 controlled by standard pragmas, where those standards do not 2220 require a particular default state. It does not indicate whether 2221 optimizations respect signaling NaN semantics (the macro for that 2222 is '__SUPPORT_SNAN__'). It does not indicate support for decimal 2223 floating point or the IEEE 754 binary16 and binary128 types. 2224 2225'__GCC_IEC_559_COMPLEX' 2226 This macro is defined to indicate the intended level of support for 2227 IEEE 754 (IEC 60559) floating-point arithmetic for complex numbers, 2228 as defined in C99 and C11 Annex G. It expands to a nonnegative 2229 integer value. If 0, it indicates that the combination of the 2230 compiler configuration and the command-line options is not intended 2231 to support Annex G requirements (for example, because 2232 '-fcx-limited-range' was used). If 1 or more, it indicates that it 2233 is intended to support those requirements; this does not mean that 2234 all relevant language features are supported by GCC. 2235 2236'__NO_MATH_ERRNO__' 2237 This macro is defined if '-fno-math-errno' is used, or enabled by 2238 another option such as '-ffast-math' or by default. 2239 2240 2241File: cpp.info, Node: System-specific Predefined Macros, Next: C++ Named Operators, Prev: Common Predefined Macros, Up: Predefined Macros 2242 22433.7.3 System-specific Predefined Macros 2244--------------------------------------- 2245 2246The C preprocessor normally predefines several macros that indicate what 2247type of system and machine is in use. They are obviously different on 2248each target supported by GCC. This manual, being for all systems and 2249machines, cannot tell you what their names are, but you can use 'cpp 2250-dM' to see them all. *Note Invocation::. All system-specific 2251predefined macros expand to a constant value, so you can test them with 2252either '#ifdef' or '#if'. 2253 2254 The C standard requires that all system-specific macros be part of 2255the "reserved namespace". All names which begin with two underscores, 2256or an underscore and a capital letter, are reserved for the compiler and 2257library to use as they wish. However, historically system-specific 2258macros have had names with no special prefix; for instance, it is common 2259to find 'unix' defined on Unix systems. For all such macros, GCC 2260provides a parallel macro with two underscores added at the beginning 2261and the end. If 'unix' is defined, '__unix__' will be defined too. 2262There will never be more than two underscores; the parallel of '_mips' 2263is '__mips__'. 2264 2265 When the '-ansi' option, or any '-std' option that requests strict 2266conformance, is given to the compiler, all the system-specific 2267predefined macros outside the reserved namespace are suppressed. The 2268parallel macros, inside the reserved namespace, remain defined. 2269 2270 We are slowly phasing out all predefined macros which are outside the 2271reserved namespace. You should never use them in new programs, and we 2272encourage you to correct older code to use the parallel macros whenever 2273you find it. We don't recommend you use the system-specific macros that 2274are in the reserved namespace, either. It is better in the long run to 2275check specifically for features you need, using a tool such as 2276'autoconf'. 2277 2278 2279File: cpp.info, Node: C++ Named Operators, Prev: System-specific Predefined Macros, Up: Predefined Macros 2280 22813.7.4 C++ Named Operators 2282------------------------- 2283 2284In C++, there are eleven keywords which are simply alternate spellings 2285of operators normally written with punctuation. These keywords are 2286treated as such even in the preprocessor. They function as operators in 2287'#if', and they cannot be defined as macros or poisoned. In C, you can 2288request that those keywords take their C++ meaning by including 2289'iso646.h'. That header defines each one as a normal object-like macro 2290expanding to the appropriate punctuator. 2291 2292 These are the named operators and their corresponding punctuators: 2293 2294Named Operator Punctuator 2295'and' '&&' 2296'and_eq' '&=' 2297'bitand' '&' 2298'bitor' '|' 2299'compl' '~' 2300'not' '!' 2301'not_eq' '!=' 2302'or' '||' 2303'or_eq' '|=' 2304'xor' '^' 2305'xor_eq' '^=' 2306 2307 2308File: cpp.info, Node: Undefining and Redefining Macros, Next: Directives Within Macro Arguments, Prev: Predefined Macros, Up: Macros 2309 23103.8 Undefining and Redefining Macros 2311==================================== 2312 2313If a macro ceases to be useful, it may be "undefined" with the '#undef' 2314directive. '#undef' takes a single argument, the name of the macro to 2315undefine. You use the bare macro name, even if the macro is 2316function-like. It is an error if anything appears on the line after the 2317macro name. '#undef' has no effect if the name is not a macro. 2318 2319 #define FOO 4 2320 x = FOO; ==> x = 4; 2321 #undef FOO 2322 x = FOO; ==> x = FOO; 2323 2324 Once a macro has been undefined, that identifier may be "redefined" 2325as a macro by a subsequent '#define' directive. The new definition need 2326not have any resemblance to the old definition. 2327 2328 However, if an identifier which is currently a macro is redefined, 2329then the new definition must be "effectively the same" as the old one. 2330Two macro definitions are effectively the same if: 2331 * Both are the same type of macro (object- or function-like). 2332 * All the tokens of the replacement list are the same. 2333 * If there are any parameters, they are the same. 2334 * Whitespace appears in the same places in both. It need not be 2335 exactly the same amount of whitespace, though. Remember that 2336 comments count as whitespace. 2337 2338These definitions are effectively the same: 2339 #define FOUR (2 + 2) 2340 #define FOUR (2 + 2) 2341 #define FOUR (2 /* two */ + 2) 2342but these are not: 2343 #define FOUR (2 + 2) 2344 #define FOUR ( 2+2 ) 2345 #define FOUR (2 * 2) 2346 #define FOUR(score,and,seven,years,ago) (2 + 2) 2347 2348 If a macro is redefined with a definition that is not effectively the 2349same as the old one, the preprocessor issues a warning and changes the 2350macro to use the new definition. If the new definition is effectively 2351the same, the redefinition is silently ignored. This allows, for 2352instance, two different headers to define a common macro. The 2353preprocessor will only complain if the definitions do not match. 2354 2355 2356File: cpp.info, Node: Directives Within Macro Arguments, Next: Macro Pitfalls, Prev: Undefining and Redefining Macros, Up: Macros 2357 23583.9 Directives Within Macro Arguments 2359===================================== 2360 2361Occasionally it is convenient to use preprocessor directives within the 2362arguments of a macro. The C and C++ standards declare that behavior in 2363these cases is undefined. GNU CPP processes arbitrary directives within 2364macro arguments in exactly the same way as it would have processed the 2365directive were the function-like macro invocation not present. 2366 2367 If, within a macro invocation, that macro is redefined, then the new 2368definition takes effect in time for argument pre-expansion, but the 2369original definition is still used for argument replacement. Here is a 2370pathological example: 2371 2372 #define f(x) x x 2373 f (1 2374 #undef f 2375 #define f 2 2376 f) 2377 2378which expands to 2379 2380 1 2 1 2 2381 2382with the semantics described above. 2383 2384 2385File: cpp.info, Node: Macro Pitfalls, Prev: Directives Within Macro Arguments, Up: Macros 2386 23873.10 Macro Pitfalls 2388=================== 2389 2390In this section we describe some special rules that apply to macros and 2391macro expansion, and point out certain cases in which the rules have 2392counter-intuitive consequences that you must watch out for. 2393 2394* Menu: 2395 2396* Misnesting:: 2397* Operator Precedence Problems:: 2398* Swallowing the Semicolon:: 2399* Duplication of Side Effects:: 2400* Self-Referential Macros:: 2401* Argument Prescan:: 2402* Newlines in Arguments:: 2403 2404 2405File: cpp.info, Node: Misnesting, Next: Operator Precedence Problems, Up: Macro Pitfalls 2406 24073.10.1 Misnesting 2408----------------- 2409 2410When a macro is called with arguments, the arguments are substituted 2411into the macro body and the result is checked, together with the rest of 2412the input file, for more macro calls. It is possible to piece together 2413a macro call coming partially from the macro body and partially from the 2414arguments. For example, 2415 2416 #define twice(x) (2*(x)) 2417 #define call_with_1(x) x(1) 2418 call_with_1 (twice) 2419 ==> twice(1) 2420 ==> (2*(1)) 2421 2422 Macro definitions do not have to have balanced parentheses. By 2423writing an unbalanced open parenthesis in a macro body, it is possible 2424to create a macro call that begins inside the macro body but ends 2425outside of it. For example, 2426 2427 #define strange(file) fprintf (file, "%s %d", 2428 ... 2429 strange(stderr) p, 35) 2430 ==> fprintf (stderr, "%s %d", p, 35) 2431 2432 The ability to piece together a macro call can be useful, but the use 2433of unbalanced open parentheses in a macro body is just confusing, and 2434should be avoided. 2435 2436 2437File: cpp.info, Node: Operator Precedence Problems, Next: Swallowing the Semicolon, Prev: Misnesting, Up: Macro Pitfalls 2438 24393.10.2 Operator Precedence Problems 2440----------------------------------- 2441 2442You may have noticed that in most of the macro definition examples shown 2443above, each occurrence of a macro argument name had parentheses around 2444it. In addition, another pair of parentheses usually surround the 2445entire macro definition. Here is why it is best to write macros that 2446way. 2447 2448 Suppose you define a macro as follows, 2449 2450 #define ceil_div(x, y) (x + y - 1) / y 2451 2452whose purpose is to divide, rounding up. (One use for this operation is 2453to compute how many 'int' objects are needed to hold a certain number of 2454'char' objects.) Then suppose it is used as follows: 2455 2456 a = ceil_div (b & c, sizeof (int)); 2457 ==> a = (b & c + sizeof (int) - 1) / sizeof (int); 2458 2459This does not do what is intended. The operator-precedence rules of C 2460make it equivalent to this: 2461 2462 a = (b & (c + sizeof (int) - 1)) / sizeof (int); 2463 2464What we want is this: 2465 2466 a = ((b & c) + sizeof (int) - 1)) / sizeof (int); 2467 2468Defining the macro as 2469 2470 #define ceil_div(x, y) ((x) + (y) - 1) / (y) 2471 2472provides the desired result. 2473 2474 Unintended grouping can result in another way. Consider 'sizeof 2475ceil_div(1, 2)'. That has the appearance of a C expression that would 2476compute the size of the type of 'ceil_div (1, 2)', but in fact it means 2477something very different. Here is what it expands to: 2478 2479 sizeof ((1) + (2) - 1) / (2) 2480 2481This would take the size of an integer and divide it by two. The 2482precedence rules have put the division outside the 'sizeof' when it was 2483intended to be inside. 2484 2485 Parentheses around the entire macro definition prevent such problems. 2486Here, then, is the recommended way to define 'ceil_div': 2487 2488 #define ceil_div(x, y) (((x) + (y) - 1) / (y)) 2489 2490 2491File: cpp.info, Node: Swallowing the Semicolon, Next: Duplication of Side Effects, Prev: Operator Precedence Problems, Up: Macro Pitfalls 2492 24933.10.3 Swallowing the Semicolon 2494------------------------------- 2495 2496Often it is desirable to define a macro that expands into a compound 2497statement. Consider, for example, the following macro, that advances a 2498pointer (the argument 'p' says where to find it) across whitespace 2499characters: 2500 2501 #define SKIP_SPACES(p, limit) \ 2502 { char *lim = (limit); \ 2503 while (p < lim) { \ 2504 if (*p++ != ' ') { \ 2505 p--; break; }}} 2506 2507Here backslash-newline is used to split the macro definition, which must 2508be a single logical line, so that it resembles the way such code would 2509be laid out if not part of a macro definition. 2510 2511 A call to this macro might be 'SKIP_SPACES (p, lim)'. Strictly 2512speaking, the call expands to a compound statement, which is a complete 2513statement with no need for a semicolon to end it. However, since it 2514looks like a function call, it minimizes confusion if you can use it 2515like a function call, writing a semicolon afterward, as in 'SKIP_SPACES 2516(p, lim);' 2517 2518 This can cause trouble before 'else' statements, because the 2519semicolon is actually a null statement. Suppose you write 2520 2521 if (*p != 0) 2522 SKIP_SPACES (p, lim); 2523 else ... 2524 2525The presence of two statements--the compound statement and a null 2526statement--in between the 'if' condition and the 'else' makes invalid C 2527code. 2528 2529 The definition of the macro 'SKIP_SPACES' can be altered to solve 2530this problem, using a 'do ... while' statement. Here is how: 2531 2532 #define SKIP_SPACES(p, limit) \ 2533 do { char *lim = (limit); \ 2534 while (p < lim) { \ 2535 if (*p++ != ' ') { \ 2536 p--; break; }}} \ 2537 while (0) 2538 2539 Now 'SKIP_SPACES (p, lim);' expands into 2540 2541 do {...} while (0); 2542 2543which is one statement. The loop executes exactly once; most compilers 2544generate no extra code for it. 2545 2546 2547File: cpp.info, Node: Duplication of Side Effects, Next: Self-Referential Macros, Prev: Swallowing the Semicolon, Up: Macro Pitfalls 2548 25493.10.4 Duplication of Side Effects 2550---------------------------------- 2551 2552Many C programs define a macro 'min', for "minimum", like this: 2553 2554 #define min(X, Y) ((X) < (Y) ? (X) : (Y)) 2555 2556 When you use this macro with an argument containing a side effect, as 2557shown here, 2558 2559 next = min (x + y, foo (z)); 2560 2561it expands as follows: 2562 2563 next = ((x + y) < (foo (z)) ? (x + y) : (foo (z))); 2564 2565where 'x + y' has been substituted for 'X' and 'foo (z)' for 'Y'. 2566 2567 The function 'foo' is used only once in the statement as it appears 2568in the program, but the expression 'foo (z)' has been substituted twice 2569into the macro expansion. As a result, 'foo' might be called two times 2570when the statement is executed. If it has side effects or if it takes a 2571long time to compute, the results might not be what you intended. We 2572say that 'min' is an "unsafe" macro. 2573 2574 The best solution to this problem is to define 'min' in a way that 2575computes the value of 'foo (z)' only once. The C language offers no 2576standard way to do this, but it can be done with GNU extensions as 2577follows: 2578 2579 #define min(X, Y) \ 2580 ({ typeof (X) x_ = (X); \ 2581 typeof (Y) y_ = (Y); \ 2582 (x_ < y_) ? x_ : y_; }) 2583 2584 The '({ ... })' notation produces a compound statement that acts as 2585an expression. Its value is the value of its last statement. This 2586permits us to define local variables and assign each argument to one. 2587The local variables have underscores after their names to reduce the 2588risk of conflict with an identifier of wider scope (it is impossible to 2589avoid this entirely). Now each argument is evaluated exactly once. 2590 2591 If you do not wish to use GNU C extensions, the only solution is to 2592be careful when _using_ the macro 'min'. For example, you can calculate 2593the value of 'foo (z)', save it in a variable, and use that variable in 2594'min': 2595 2596 #define min(X, Y) ((X) < (Y) ? (X) : (Y)) 2597 ... 2598 { 2599 int tem = foo (z); 2600 next = min (x + y, tem); 2601 } 2602 2603(where we assume that 'foo' returns type 'int'). 2604 2605 2606File: cpp.info, Node: Self-Referential Macros, Next: Argument Prescan, Prev: Duplication of Side Effects, Up: Macro Pitfalls 2607 26083.10.5 Self-Referential Macros 2609------------------------------ 2610 2611A "self-referential" macro is one whose name appears in its definition. 2612Recall that all macro definitions are rescanned for more macros to 2613replace. If the self-reference were considered a use of the macro, it 2614would produce an infinitely large expansion. To prevent this, the 2615self-reference is not considered a macro call. It is passed into the 2616preprocessor output unchanged. Consider an example: 2617 2618 #define foo (4 + foo) 2619 2620where 'foo' is also a variable in your program. 2621 2622 Following the ordinary rules, each reference to 'foo' will expand 2623into '(4 + foo)'; then this will be rescanned and will expand into '(4 + 2624(4 + foo))'; and so on until the computer runs out of memory. 2625 2626 The self-reference rule cuts this process short after one step, at 2627'(4 + foo)'. Therefore, this macro definition has the possibly useful 2628effect of causing the program to add 4 to the value of 'foo' wherever 2629'foo' is referred to. 2630 2631 In most cases, it is a bad idea to take advantage of this feature. A 2632person reading the program who sees that 'foo' is a variable will not 2633expect that it is a macro as well. The reader will come across the 2634identifier 'foo' in the program and think its value should be that of 2635the variable 'foo', whereas in fact the value is four greater. 2636 2637 One common, useful use of self-reference is to create a macro which 2638expands to itself. If you write 2639 2640 #define EPERM EPERM 2641 2642then the macro 'EPERM' expands to 'EPERM'. Effectively, it is left 2643alone by the preprocessor whenever it's used in running text. You can 2644tell that it's a macro with '#ifdef'. You might do this if you want to 2645define numeric constants with an 'enum', but have '#ifdef' be true for 2646each constant. 2647 2648 If a macro 'x' expands to use a macro 'y', and the expansion of 'y' 2649refers to the macro 'x', that is an "indirect self-reference" of 'x'. 2650'x' is not expanded in this case either. Thus, if we have 2651 2652 #define x (4 + y) 2653 #define y (2 * x) 2654 2655then 'x' and 'y' expand as follows: 2656 2657 x ==> (4 + y) 2658 ==> (4 + (2 * x)) 2659 2660 y ==> (2 * x) 2661 ==> (2 * (4 + y)) 2662 2663Each macro is expanded when it appears in the definition of the other 2664macro, but not when it indirectly appears in its own definition. 2665 2666 2667File: cpp.info, Node: Argument Prescan, Next: Newlines in Arguments, Prev: Self-Referential Macros, Up: Macro Pitfalls 2668 26693.10.6 Argument Prescan 2670----------------------- 2671 2672Macro arguments are completely macro-expanded before they are 2673substituted into a macro body, unless they are stringized or pasted with 2674other tokens. After substitution, the entire macro body, including the 2675substituted arguments, is scanned again for macros to be expanded. The 2676result is that the arguments are scanned _twice_ to expand macro calls 2677in them. 2678 2679 Most of the time, this has no effect. If the argument contained any 2680macro calls, they are expanded during the first scan. The result 2681therefore contains no macro calls, so the second scan does not change 2682it. If the argument were substituted as given, with no prescan, the 2683single remaining scan would find the same macro calls and produce the 2684same results. 2685 2686 You might expect the double scan to change the results when a 2687self-referential macro is used in an argument of another macro (*note 2688Self-Referential Macros::): the self-referential macro would be expanded 2689once in the first scan, and a second time in the second scan. However, 2690this is not what happens. The self-references that do not expand in the 2691first scan are marked so that they will not expand in the second scan 2692either. 2693 2694 You might wonder, "Why mention the prescan, if it makes no 2695difference? And why not skip it and make the preprocessor faster?" The 2696answer is that the prescan does make a difference in three special 2697cases: 2698 2699 * Nested calls to a macro. 2700 2701 We say that "nested" calls to a macro occur when a macro's argument 2702 contains a call to that very macro. For example, if 'f' is a macro 2703 that expects one argument, 'f (f (1))' is a nested pair of calls to 2704 'f'. The desired expansion is made by expanding 'f (1)' and 2705 substituting that into the definition of 'f'. The prescan causes 2706 the expected result to happen. Without the prescan, 'f (1)' itself 2707 would be substituted as an argument, and the inner use of 'f' would 2708 appear during the main scan as an indirect self-reference and would 2709 not be expanded. 2710 2711 * Macros that call other macros that stringize or concatenate. 2712 2713 If an argument is stringized or concatenated, the prescan does not 2714 occur. If you _want_ to expand a macro, then stringize or 2715 concatenate its expansion, you can do that by causing one macro to 2716 call another macro that does the stringizing or concatenation. For 2717 instance, if you have 2718 2719 #define AFTERX(x) X_ ## x 2720 #define XAFTERX(x) AFTERX(x) 2721 #define TABLESIZE 1024 2722 #define BUFSIZE TABLESIZE 2723 2724 then 'AFTERX(BUFSIZE)' expands to 'X_BUFSIZE', and 2725 'XAFTERX(BUFSIZE)' expands to 'X_1024'. (Not to 'X_TABLESIZE'. 2726 Prescan always does a complete expansion.) 2727 2728 * Macros used in arguments, whose expansions contain unshielded 2729 commas. 2730 2731 This can cause a macro expanded on the second scan to be called 2732 with the wrong number of arguments. Here is an example: 2733 2734 #define foo a,b 2735 #define bar(x) lose(x) 2736 #define lose(x) (1 + (x)) 2737 2738 We would like 'bar(foo)' to turn into '(1 + (foo))', which would 2739 then turn into '(1 + (a,b))'. Instead, 'bar(foo)' expands into 2740 'lose(a,b)', and you get an error because 'lose' requires a single 2741 argument. In this case, the problem is easily solved by the same 2742 parentheses that ought to be used to prevent misnesting of 2743 arithmetic operations: 2744 2745 #define foo (a,b) 2746 or 2747 #define bar(x) lose((x)) 2748 2749 The extra pair of parentheses prevents the comma in 'foo''s 2750 definition from being interpreted as an argument separator. 2751 2752 2753File: cpp.info, Node: Newlines in Arguments, Prev: Argument Prescan, Up: Macro Pitfalls 2754 27553.10.7 Newlines in Arguments 2756---------------------------- 2757 2758The invocation of a function-like macro can extend over many logical 2759lines. However, in the present implementation, the entire expansion 2760comes out on one line. Thus line numbers emitted by the compiler or 2761debugger refer to the line the invocation started on, which might be 2762different to the line containing the argument causing the problem. 2763 2764 Here is an example illustrating this: 2765 2766 #define ignore_second_arg(a,b,c) a; c 2767 2768 ignore_second_arg (foo (), 2769 ignored (), 2770 syntax error); 2771 2772The syntax error triggered by the tokens 'syntax error' results in an 2773error message citing line three--the line of ignore_second_arg-- even 2774though the problematic code comes from line five. 2775 2776 We consider this a bug, and intend to fix it in the near future. 2777 2778 2779File: cpp.info, Node: Conditionals, Next: Diagnostics, Prev: Macros, Up: Top 2780 27814 Conditionals 2782************** 2783 2784A "conditional" is a directive that instructs the preprocessor to select 2785whether or not to include a chunk of code in the final token stream 2786passed to the compiler. Preprocessor conditionals can test arithmetic 2787expressions, or whether a name is defined as a macro, or both 2788simultaneously using the special 'defined' operator. 2789 2790 A conditional in the C preprocessor resembles in some ways an 'if' 2791statement in C, but it is important to understand the difference between 2792them. The condition in an 'if' statement is tested during the execution 2793of your program. Its purpose is to allow your program to behave 2794differently from run to run, depending on the data it is operating on. 2795The condition in a preprocessing conditional directive is tested when 2796your program is compiled. Its purpose is to allow different code to be 2797included in the program depending on the situation at the time of 2798compilation. 2799 2800 However, the distinction is becoming less clear. Modern compilers 2801often do test 'if' statements when a program is compiled, if their 2802conditions are known not to vary at run time, and eliminate code which 2803can never be executed. If you can count on your compiler to do this, 2804you may find that your program is more readable if you use 'if' 2805statements with constant conditions (perhaps determined by macros). Of 2806course, you can only use this to exclude code, not type definitions or 2807other preprocessing directives, and you can only do it if the code 2808remains syntactically valid when it is not to be used. 2809 2810* Menu: 2811 2812* Conditional Uses:: 2813* Conditional Syntax:: 2814* Deleted Code:: 2815 2816 2817File: cpp.info, Node: Conditional Uses, Next: Conditional Syntax, Up: Conditionals 2818 28194.1 Conditional Uses 2820==================== 2821 2822There are three general reasons to use a conditional. 2823 2824 * A program may need to use different code depending on the machine 2825 or operating system it is to run on. In some cases the code for 2826 one operating system may be erroneous on another operating system; 2827 for example, it might refer to data types or constants that do not 2828 exist on the other system. When this happens, it is not enough to 2829 avoid executing the invalid code. Its mere presence will cause the 2830 compiler to reject the program. With a preprocessing conditional, 2831 the offending code can be effectively excised from the program when 2832 it is not valid. 2833 2834 * You may want to be able to compile the same source file into two 2835 different programs. One version might make frequent time-consuming 2836 consistency checks on its intermediate data, or print the values of 2837 those data for debugging, and the other not. 2838 2839 * A conditional whose condition is always false is one way to exclude 2840 code from the program but keep it as a sort of comment for future 2841 reference. 2842 2843 Simple programs that do not need system-specific logic or complex 2844debugging hooks generally will not need to use preprocessing 2845conditionals. 2846 2847 2848File: cpp.info, Node: Conditional Syntax, Next: Deleted Code, Prev: Conditional Uses, Up: Conditionals 2849 28504.2 Conditional Syntax 2851====================== 2852 2853A conditional in the C preprocessor begins with a "conditional 2854directive": '#if', '#ifdef' or '#ifndef'. 2855 2856* Menu: 2857 2858* Ifdef:: 2859* If:: 2860* Defined:: 2861* Else:: 2862* Elif:: 2863* __has_attribute:: 2864* __has_cpp_attribute:: 2865* __has_builtin:: 2866* __has_include:: 2867 2868 2869File: cpp.info, Node: Ifdef, Next: If, Up: Conditional Syntax 2870 28714.2.1 Ifdef 2872----------- 2873 2874The simplest sort of conditional is 2875 2876 #ifdef MACRO 2877 2878 CONTROLLED TEXT 2879 2880 #endif /* MACRO */ 2881 2882 This block is called a "conditional group". CONTROLLED TEXT will be 2883included in the output of the preprocessor if and only if MACRO is 2884defined. We say that the conditional "succeeds" if MACRO is defined, 2885"fails" if it is not. 2886 2887 The CONTROLLED TEXT inside of a conditional can include preprocessing 2888directives. They are executed only if the conditional succeeds. You 2889can nest conditional groups inside other conditional groups, but they 2890must be completely nested. In other words, '#endif' always matches the 2891nearest '#ifdef' (or '#ifndef', or '#if'). Also, you cannot start a 2892conditional group in one file and end it in another. 2893 2894 Even if a conditional fails, the CONTROLLED TEXT inside it is still 2895run through initial transformations and tokenization. Therefore, it 2896must all be lexically valid C. Normally the only way this matters is 2897that all comments and string literals inside a failing conditional group 2898must still be properly ended. 2899 2900 The comment following the '#endif' is not required, but it is a good 2901practice if there is a lot of CONTROLLED TEXT, because it helps people 2902match the '#endif' to the corresponding '#ifdef'. Older programs 2903sometimes put MACRO directly after the '#endif' without enclosing it in 2904a comment. This is invalid code according to the C standard. CPP 2905accepts it with a warning. It never affects which '#ifndef' the 2906'#endif' matches. 2907 2908 Sometimes you wish to use some code if a macro is _not_ defined. You 2909can do this by writing '#ifndef' instead of '#ifdef'. One common use of 2910'#ifndef' is to include code only the first time a header file is 2911included. *Note Once-Only Headers::. 2912 2913 Macro definitions can vary between compilations for several reasons. 2914Here are some samples. 2915 2916 * Some macros are predefined on each kind of machine (*note 2917 System-specific Predefined Macros::). This allows you to provide 2918 code specially tuned for a particular machine. 2919 2920 * System header files define more macros, associated with the 2921 features they implement. You can test these macros with 2922 conditionals to avoid using a system feature on a machine where it 2923 is not implemented. 2924 2925 * Macros can be defined or undefined with the '-D' and '-U' 2926 command-line options when you compile the program. You can arrange 2927 to compile the same source file into two different programs by 2928 choosing a macro name to specify which program you want, writing 2929 conditionals to test whether or how this macro is defined, and then 2930 controlling the state of the macro with command-line options, 2931 perhaps set in the Makefile. *Note Invocation::. 2932 2933 * Your program might have a special header file (often called 2934 'config.h') that is adjusted when the program is compiled. It can 2935 define or not define macros depending on the features of the system 2936 and the desired capabilities of the program. The adjustment can be 2937 automated by a tool such as 'autoconf', or done by hand. 2938 2939 2940File: cpp.info, Node: If, Next: Defined, Prev: Ifdef, Up: Conditional Syntax 2941 29424.2.2 If 2943-------- 2944 2945The '#if' directive allows you to test the value of an arithmetic 2946expression, rather than the mere existence of one macro. Its syntax is 2947 2948 #if EXPRESSION 2949 2950 CONTROLLED TEXT 2951 2952 #endif /* EXPRESSION */ 2953 2954 EXPRESSION is a C expression of integer type, subject to stringent 2955restrictions. It may contain 2956 2957 * Integer constants. 2958 2959 * Character constants, which are interpreted as they would be in 2960 normal code. 2961 2962 * Arithmetic operators for addition, subtraction, multiplication, 2963 division, bitwise operations, shifts, comparisons, and logical 2964 operations ('&&' and '||'). The latter two obey the usual 2965 short-circuiting rules of standard C. 2966 2967 * Macros. All macros in the expression are expanded before actual 2968 computation of the expression's value begins. 2969 2970 * Uses of the 'defined' operator, which lets you check whether macros 2971 are defined in the middle of an '#if'. 2972 2973 * Identifiers that are not macros, which are all considered to be the 2974 number zero. This allows you to write '#if MACRO' instead of 2975 '#ifdef MACRO', if you know that MACRO, when defined, will always 2976 have a nonzero value. Function-like macros used without their 2977 function call parentheses are also treated as zero. 2978 2979 In some contexts this shortcut is undesirable. The '-Wundef' 2980 option causes GCC to warn whenever it encounters an identifier 2981 which is not a macro in an '#if'. 2982 2983 The preprocessor does not know anything about types in the language. 2984Therefore, 'sizeof' operators are not recognized in '#if', and neither 2985are 'enum' constants. They will be taken as identifiers which are not 2986macros, and replaced by zero. In the case of 'sizeof', this is likely 2987to cause the expression to be invalid. 2988 2989 The preprocessor calculates the value of EXPRESSION. It carries out 2990all calculations in the widest integer type known to the compiler; on 2991most machines supported by GCC this is 64 bits. This is not the same 2992rule as the compiler uses to calculate the value of a constant 2993expression, and may give different results in some cases. If the value 2994comes out to be nonzero, the '#if' succeeds and the CONTROLLED TEXT is 2995included; otherwise it is skipped. 2996 2997 2998File: cpp.info, Node: Defined, Next: Else, Prev: If, Up: Conditional Syntax 2999 30004.2.3 Defined 3001------------- 3002 3003The special operator 'defined' is used in '#if' and '#elif' expressions 3004to test whether a certain name is defined as a macro. 'defined NAME' 3005and 'defined (NAME)' are both expressions whose value is 1 if NAME is 3006defined as a macro at the current point in the program, and 0 otherwise. 3007Thus, '#if defined MACRO' is precisely equivalent to '#ifdef MACRO'. 3008 3009 'defined' is useful when you wish to test more than one macro for 3010existence at once. For example, 3011 3012 #if defined (__vax__) || defined (__ns16000__) 3013 3014would succeed if either of the names '__vax__' or '__ns16000__' is 3015defined as a macro. 3016 3017 Conditionals written like this: 3018 3019 #if defined BUFSIZE && BUFSIZE >= 1024 3020 3021can generally be simplified to just '#if BUFSIZE >= 1024', since if 3022'BUFSIZE' is not defined, it will be interpreted as having the value 3023zero. 3024 3025 If the 'defined' operator appears as a result of a macro expansion, 3026the C standard says the behavior is undefined. GNU cpp treats it as a 3027genuine 'defined' operator and evaluates it normally. It will warn 3028wherever your code uses this feature if you use the command-line option 3029'-Wpedantic', since other compilers may handle it differently. The 3030warning is also enabled by '-Wextra', and can also be enabled 3031individually with '-Wexpansion-to-defined'. 3032 3033 3034File: cpp.info, Node: Else, Next: Elif, Prev: Defined, Up: Conditional Syntax 3035 30364.2.4 Else 3037---------- 3038 3039The '#else' directive can be added to a conditional to provide 3040alternative text to be used if the condition fails. This is what it 3041looks like: 3042 3043 #if EXPRESSION 3044 TEXT-IF-TRUE 3045 #else /* Not EXPRESSION */ 3046 TEXT-IF-FALSE 3047 #endif /* Not EXPRESSION */ 3048 3049If EXPRESSION is nonzero, the TEXT-IF-TRUE is included and the 3050TEXT-IF-FALSE is skipped. If EXPRESSION is zero, the opposite happens. 3051 3052 You can use '#else' with '#ifdef' and '#ifndef', too. 3053 3054 3055File: cpp.info, Node: Elif, Next: __has_attribute, Prev: Else, Up: Conditional Syntax 3056 30574.2.5 Elif 3058---------- 3059 3060One common case of nested conditionals is used to check for more than 3061two possible alternatives. For example, you might have 3062 3063 #if X == 1 3064 ... 3065 #else /* X != 1 */ 3066 #if X == 2 3067 ... 3068 #else /* X != 2 */ 3069 ... 3070 #endif /* X != 2 */ 3071 #endif /* X != 1 */ 3072 3073 Another conditional directive, '#elif', allows this to be abbreviated 3074as follows: 3075 3076 #if X == 1 3077 ... 3078 #elif X == 2 3079 ... 3080 #else /* X != 2 and X != 1*/ 3081 ... 3082 #endif /* X != 2 and X != 1*/ 3083 3084 '#elif' stands for "else if". Like '#else', it goes in the middle of 3085a conditional group and subdivides it; it does not require a matching 3086'#endif' of its own. Like '#if', the '#elif' directive includes an 3087expression to be tested. The text following the '#elif' is processed 3088only if the original '#if'-condition failed and the '#elif' condition 3089succeeds. 3090 3091 More than one '#elif' can go in the same conditional group. Then the 3092text after each '#elif' is processed only if the '#elif' condition 3093succeeds after the original '#if' and all previous '#elif' directives 3094within it have failed. 3095 3096 '#else' is allowed after any number of '#elif' directives, but 3097'#elif' may not follow '#else'. 3098 3099 3100File: cpp.info, Node: __has_attribute, Next: __has_cpp_attribute, Prev: Elif, Up: Conditional Syntax 3101 31024.2.6 '__has_attribute' 3103----------------------- 3104 3105The special operator '__has_attribute (OPERAND)' may be used in '#if' 3106and '#elif' expressions to test whether the attribute referenced by its 3107OPERAND is recognized by GCC. Using the operator in other contexts is 3108not valid. In C code, OPERAND must be a valid identifier. In C++ code, 3109OPERAND may be optionally introduced by the 'ATTRIBUTE-SCOPE::' prefix. 3110The ATTRIBUTE-SCOPE prefix identifies the "namespace" within which the 3111attribute is recognized. The scope of GCC attributes is 'gnu' or 3112'__gnu__'. The '__has_attribute' operator by itself, without any 3113OPERAND or parentheses, acts as a predefined macro so that support for 3114it can be tested in portable code. Thus, the recommended use of the 3115operator is as follows: 3116 3117 #if defined __has_attribute 3118 # if __has_attribute (nonnull) 3119 # define ATTR_NONNULL __attribute__ ((nonnull)) 3120 # endif 3121 #endif 3122 3123 The first '#if' test succeeds only when the operator is supported by 3124the version of GCC (or another compiler) being used. Only when that 3125test succeeds is it valid to use '__has_attribute' as a preprocessor 3126operator. As a result, combining the two tests into a single expression 3127as shown below would only be valid with a compiler that supports the 3128operator but not with others that don't. 3129 3130 #if defined __has_attribute && __has_attribute (nonnull) /* not portable */ 3131 ... 3132 #endif 3133 3134 3135File: cpp.info, Node: __has_cpp_attribute, Next: __has_builtin, Prev: __has_attribute, Up: Conditional Syntax 3136 31374.2.7 '__has_cpp_attribute' 3138--------------------------- 3139 3140The special operator '__has_cpp_attribute (OPERAND)' may be used in 3141'#if' and '#elif' expressions in C++ code to test whether the attribute 3142referenced by its OPERAND is recognized by GCC. '__has_cpp_attribute 3143(OPERAND)' is equivalent to '__has_attribute (OPERAND)' except that when 3144OPERAND designates a supported standard attribute it evaluates to an 3145integer constant of the form 'YYYYMM' indicating the year and month when 3146the attribute was first introduced into the C++ standard. For 3147additional information including the dates of the introduction of 3148current standard attributes, see 3149SD-6: SG10 Feature Test Recommendations (https://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations/). 3150 3151 3152File: cpp.info, Node: __has_builtin, Next: __has_include, Prev: __has_cpp_attribute, Up: Conditional Syntax 3153 31544.2.8 '__has_builtin' 3155--------------------- 3156 3157The special operator '__has_builtin (OPERAND)' may be used in constant 3158integer contexts and in preprocessor '#if' and '#elif' expressions to 3159test whether the symbol named by its OPERAND is recognized as a built-in 3160function by GCC in the current language and conformance mode. It 3161evaluates to a constant integer with a nonzero value if the argument 3162refers to such a function, and to zero otherwise. The operator may also 3163be used in preprocessor '#if' and '#elif' expressions. The 3164'__has_builtin' operator by itself, without any OPERAND or parentheses, 3165acts as a predefined macro so that support for it can be tested in 3166portable code. Thus, the recommended use of the operator is as follows: 3167 3168 #if defined __has_builtin 3169 # if __has_builtin (__builtin_object_size) 3170 # define builtin_object_size(ptr) __builtin_object_size (ptr, 2) 3171 # endif 3172 #endif 3173 #ifndef builtin_object_size 3174 # define builtin_object_size(ptr) ((size_t)-1) 3175 #endif 3176 3177 3178File: cpp.info, Node: __has_include, Prev: __has_builtin, Up: Conditional Syntax 3179 31804.2.9 '__has_include' 3181--------------------- 3182 3183The special operator '__has_include (OPERAND)' may be used in '#if' and 3184'#elif' expressions to test whether the header referenced by its OPERAND 3185can be included using the '#include' directive. Using the operator in 3186other contexts is not valid. The OPERAND takes the same form as the 3187file in the '#include' directive (*note Include Syntax::) and evaluates 3188to a nonzero value if the header can be included and to zero otherwise. 3189Note that that the ability to include a header doesn't imply that the 3190header doesn't contain invalid constructs or '#error' directives that 3191would cause the preprocessor to fail. 3192 3193 The '__has_include' operator by itself, without any OPERAND or 3194parentheses, acts as a predefined macro so that support for it can be 3195tested in portable code. Thus, the recommended use of the operator is 3196as follows: 3197 3198 #if defined __has_include 3199 # if __has_include (<stdatomic.h>) 3200 # include <stdatomic.h> 3201 # endif 3202 #endif 3203 3204 The first '#if' test succeeds only when the operator is supported by 3205the version of GCC (or another compiler) being used. Only when that 3206test succeeds is it valid to use '__has_include' as a preprocessor 3207operator. As a result, combining the two tests into a single expression 3208as shown below would only be valid with a compiler that supports the 3209operator but not with others that don't. 3210 3211 #if defined __has_include && __has_include ("header.h") /* not portable */ 3212 ... 3213 #endif 3214 3215 3216File: cpp.info, Node: Deleted Code, Prev: Conditional Syntax, Up: Conditionals 3217 32184.3 Deleted Code 3219================ 3220 3221If you replace or delete a part of the program but want to keep the old 3222code around for future reference, you often cannot simply comment it 3223out. Block comments do not nest, so the first comment inside the old 3224code will end the commenting-out. The probable result is a flood of 3225syntax errors. 3226 3227 One way to avoid this problem is to use an always-false conditional 3228instead. For instance, put '#if 0' before the deleted code and '#endif' 3229after it. This works even if the code being turned off contains 3230conditionals, but they must be entire conditionals (balanced '#if' and 3231'#endif'). 3232 3233 Some people use '#ifdef notdef' instead. This is risky, because 3234'notdef' might be accidentally defined as a macro, and then the 3235conditional would succeed. '#if 0' can be counted on to fail. 3236 3237 Do not use '#if 0' for comments which are not C code. Use a real 3238comment, instead. The interior of '#if 0' must consist of complete 3239tokens; in particular, single-quote characters must balance. Comments 3240often contain unbalanced single-quote characters (known in English as 3241apostrophes). These confuse '#if 0'. They don't confuse '/*'. 3242 3243 3244File: cpp.info, Node: Diagnostics, Next: Line Control, Prev: Conditionals, Up: Top 3245 32465 Diagnostics 3247************* 3248 3249The directive '#error' causes the preprocessor to report a fatal error. 3250The tokens forming the rest of the line following '#error' are used as 3251the error message. 3252 3253 You would use '#error' inside of a conditional that detects a 3254combination of parameters which you know the program does not properly 3255support. For example, if you know that the program will not run 3256properly on a VAX, you might write 3257 3258 #ifdef __vax__ 3259 #error "Won't work on VAXen. See comments at get_last_object." 3260 #endif 3261 3262 If you have several configuration parameters that must be set up by 3263the installation in a consistent way, you can use conditionals to detect 3264an inconsistency and report it with '#error'. For example, 3265 3266 #if !defined(FOO) && defined(BAR) 3267 #error "BAR requires FOO." 3268 #endif 3269 3270 The directive '#warning' is like '#error', but causes the 3271preprocessor to issue a warning and continue preprocessing. The tokens 3272following '#warning' are used as the warning message. 3273 3274 You might use '#warning' in obsolete header files, with a message 3275directing the user to the header file which should be used instead. 3276 3277 Neither '#error' nor '#warning' macro-expands its argument. Internal 3278whitespace sequences are each replaced with a single space. The line 3279must consist of complete tokens. It is wisest to make the argument of 3280these directives be a single string constant; this avoids problems with 3281apostrophes and the like. 3282 3283 3284File: cpp.info, Node: Line Control, Next: Pragmas, Prev: Diagnostics, Up: Top 3285 32866 Line Control 3287************** 3288 3289The C preprocessor informs the C compiler of the location in your source 3290code where each token came from. Presently, this is just the file name 3291and line number. All the tokens resulting from macro expansion are 3292reported as having appeared on the line of the source file where the 3293outermost macro was used. We intend to be more accurate in the future. 3294 3295 If you write a program which generates source code, such as the 3296'bison' parser generator, you may want to adjust the preprocessor's 3297notion of the current file name and line number by hand. Parts of the 3298output from 'bison' are generated from scratch, other parts come from a 3299standard parser file. The rest are copied verbatim from 'bison''s 3300input. You would like compiler error messages and symbolic debuggers to 3301be able to refer to 'bison''s input file. 3302 3303 'bison' or any such program can arrange this by writing '#line' 3304directives into the output file. '#line' is a directive that specifies 3305the original line number and source file name for subsequent input in 3306the current preprocessor input file. '#line' has three variants: 3307 3308'#line LINENUM' 3309 LINENUM is a non-negative decimal integer constant. It specifies 3310 the line number which should be reported for the following line of 3311 input. Subsequent lines are counted from LINENUM. 3312 3313'#line LINENUM FILENAME' 3314 LINENUM is the same as for the first form, and has the same effect. 3315 In addition, FILENAME is a string constant. The following line and 3316 all subsequent lines are reported to come from the file it 3317 specifies, until something else happens to change that. FILENAME 3318 is interpreted according to the normal rules for a string constant: 3319 backslash escapes are interpreted. This is different from 3320 '#include'. 3321 3322'#line ANYTHING ELSE' 3323 ANYTHING ELSE is checked for macro calls, which are expanded. The 3324 result should match one of the above two forms. 3325 3326 '#line' directives alter the results of the '__FILE__' and '__LINE__' 3327predefined macros from that point on. *Note Standard Predefined 3328Macros::. They do not have any effect on '#include''s idea of the 3329directory containing the current file. 3330 3331 3332File: cpp.info, Node: Pragmas, Next: Other Directives, Prev: Line Control, Up: Top 3333 33347 Pragmas 3335********* 3336 3337The '#pragma' directive is the method specified by the C standard for 3338providing additional information to the compiler, beyond what is 3339conveyed in the language itself. The forms of this directive (commonly 3340known as "pragmas") specified by C standard are prefixed with 'STDC'. A 3341C compiler is free to attach any meaning it likes to other pragmas. 3342Most GNU-defined, supported pragmas have been given a 'GCC' prefix. 3343 3344 C99 introduced the '_Pragma' operator. This feature addresses a 3345major problem with '#pragma': being a directive, it cannot be produced 3346as the result of macro expansion. '_Pragma' is an operator, much like 3347'sizeof' or 'defined', and can be embedded in a macro. 3348 3349 Its syntax is '_Pragma (STRING-LITERAL)', where STRING-LITERAL can be 3350either a normal or wide-character string literal. It is destringized, 3351by replacing all '\\' with a single '\' and all '\"' with a '"'. The 3352result is then processed as if it had appeared as the right hand side of 3353a '#pragma' directive. For example, 3354 3355 _Pragma ("GCC dependency \"parse.y\"") 3356 3357has the same effect as '#pragma GCC dependency "parse.y"'. The same 3358effect could be achieved using macros, for example 3359 3360 #define DO_PRAGMA(x) _Pragma (#x) 3361 DO_PRAGMA (GCC dependency "parse.y") 3362 3363 The standard is unclear on where a '_Pragma' operator can appear. 3364The preprocessor does not accept it within a preprocessing conditional 3365directive like '#if'. To be safe, you are probably best keeping it out 3366of directives other than '#define', and putting it on a line of its own. 3367 3368 This manual documents the pragmas which are meaningful to the 3369preprocessor itself. Other pragmas are meaningful to the C or C++ 3370compilers. They are documented in the GCC manual. 3371 3372 GCC plugins may provide their own pragmas. 3373 3374'#pragma GCC dependency' 3375 '#pragma GCC dependency' allows you to check the relative dates of 3376 the current file and another file. If the other file is more 3377 recent than the current file, a warning is issued. This is useful 3378 if the current file is derived from the other file, and should be 3379 regenerated. The other file is searched for using the normal 3380 include search path. Optional trailing text can be used to give 3381 more information in the warning message. 3382 3383 #pragma GCC dependency "parse.y" 3384 #pragma GCC dependency "/usr/include/time.h" rerun fixincludes 3385 3386'#pragma GCC poison' 3387 Sometimes, there is an identifier that you want to remove 3388 completely from your program, and make sure that it never creeps 3389 back in. To enforce this, you can "poison" the identifier with 3390 this pragma. '#pragma GCC poison' is followed by a list of 3391 identifiers to poison. If any of those identifiers appears 3392 anywhere in the source after the directive, it is a hard error. 3393 For example, 3394 3395 #pragma GCC poison printf sprintf fprintf 3396 sprintf(some_string, "hello"); 3397 3398 will produce an error. 3399 3400 If a poisoned identifier appears as part of the expansion of a 3401 macro which was defined before the identifier was poisoned, it will 3402 _not_ cause an error. This lets you poison an identifier without 3403 worrying about system headers defining macros that use it. 3404 3405 For example, 3406 3407 #define strrchr rindex 3408 #pragma GCC poison rindex 3409 strrchr(some_string, 'h'); 3410 3411 will not produce an error. 3412 3413'#pragma GCC system_header' 3414 This pragma takes no arguments. It causes the rest of the code in 3415 the current file to be treated as if it came from a system header. 3416 *Note System Headers::. 3417 3418'#pragma GCC warning' 3419'#pragma GCC error' 3420 '#pragma GCC warning "message"' causes the preprocessor to issue a 3421 warning diagnostic with the text 'message'. The message contained 3422 in the pragma must be a single string literal. Similarly, '#pragma 3423 GCC error "message"' issues an error message. Unlike the 3424 '#warning' and '#error' directives, these pragmas can be embedded 3425 in preprocessor macros using '_Pragma'. 3426 3427'#pragma once' 3428 If '#pragma once' is seen when scanning a header file, that file 3429 will never be read again, no matter what. It is a less-portable 3430 alternative to using '#ifndef' to guard the contents of header 3431 files against multiple inclusions. 3432 3433 3434File: cpp.info, Node: Other Directives, Next: Preprocessor Output, Prev: Pragmas, Up: Top 3435 34368 Other Directives 3437****************** 3438 3439The '#ident' directive takes one argument, a string constant. On some 3440systems, that string constant is copied into a special segment of the 3441object file. On other systems, the directive is ignored. The '#sccs' 3442directive is a synonym for '#ident'. 3443 3444 These directives are not part of the C standard, but they are not 3445official GNU extensions either. What historical information we have 3446been able to find, suggests they originated with System V. 3447 3448 The "null directive" consists of a '#' followed by a newline, with 3449only whitespace (including comments) in between. A null directive is 3450understood as a preprocessing directive but has no effect on the 3451preprocessor output. The primary significance of the existence of the 3452null directive is that an input line consisting of just a '#' will 3453produce no output, rather than a line of output containing just a '#'. 3454Supposedly some old C programs contain such lines. 3455 3456 3457File: cpp.info, Node: Preprocessor Output, Next: Traditional Mode, Prev: Other Directives, Up: Top 3458 34599 Preprocessor Output 3460********************* 3461 3462When the C preprocessor is used with the C, C++, or Objective-C 3463compilers, it is integrated into the compiler and communicates a stream 3464of binary tokens directly to the compiler's parser. However, it can 3465also be used in the more conventional standalone mode, where it produces 3466textual output. 3467 3468 The output from the C preprocessor looks much like the input, except 3469that all preprocessing directive lines have been replaced with blank 3470lines and all comments with spaces. Long runs of blank lines are 3471discarded. 3472 3473 The ISO standard specifies that it is implementation defined whether 3474a preprocessor preserves whitespace between tokens, or replaces it with 3475e.g. a single space. In GNU CPP, whitespace between tokens is collapsed 3476to become a single space, with the exception that the first token on a 3477non-directive line is preceded with sufficient spaces that it appears in 3478the same column in the preprocessed output that it appeared in the 3479original source file. This is so the output is easy to read. CPP does 3480not insert any whitespace where there was none in the original source, 3481except where necessary to prevent an accidental token paste. 3482 3483 Source file name and line number information is conveyed by lines of 3484the form 3485 3486 # LINENUM FILENAME FLAGS 3487 3488These are called "linemarkers". They are inserted as needed into the 3489output (but never within a string or character constant). They mean 3490that the following line originated in file FILENAME at line LINENUM. 3491FILENAME will never contain any non-printing characters; they are 3492replaced with octal escape sequences. 3493 3494 After the file name comes zero or more flags, which are '1', '2', 3495'3', or '4'. If there are multiple flags, spaces separate them. Here 3496is what the flags mean: 3497 3498'1' 3499 This indicates the start of a new file. 3500'2' 3501 This indicates returning to a file (after having included another 3502 file). 3503'3' 3504 This indicates that the following text comes from a system header 3505 file, so certain warnings should be suppressed. 3506'4' 3507 This indicates that the following text should be treated as being 3508 wrapped in an implicit 'extern "C"' block. 3509 3510 As an extension, the preprocessor accepts linemarkers in 3511non-assembler input files. They are treated like the corresponding 3512'#line' directive, (*note Line Control::), except that trailing flags 3513are permitted, and are interpreted with the meanings described above. 3514If multiple flags are given, they must be in ascending order. 3515 3516 Some directives may be duplicated in the output of the preprocessor. 3517These are '#ident' (always), '#pragma' (only if the preprocessor does 3518not handle the pragma itself), and '#define' and '#undef' (with certain 3519debugging options). If this happens, the '#' of the directive will 3520always be in the first column, and there will be no space between the 3521'#' and the directive name. If macro expansion happens to generate 3522tokens which might be mistaken for a duplicated directive, a space will 3523be inserted between the '#' and the directive name. 3524 3525 3526File: cpp.info, Node: Traditional Mode, Next: Implementation Details, Prev: Preprocessor Output, Up: Top 3527 352810 Traditional Mode 3529******************* 3530 3531Traditional (pre-standard) C preprocessing is rather different from the 3532preprocessing specified by the standard. When the preprocessor is 3533invoked with the '-traditional-cpp' option, it attempts to emulate a 3534traditional preprocessor. 3535 3536 This mode is not useful for compiling C code with GCC, but is 3537intended for use with non-C preprocessing applications. Thus 3538traditional mode semantics are supported only when invoking the 3539preprocessor explicitly, and not in the compiler front ends. 3540 3541 The implementation does not correspond precisely to the behavior of 3542early pre-standard versions of GCC, nor to any true traditional 3543preprocessor. After all, inconsistencies among traditional 3544implementations were a major motivation for C standardization. However, 3545we intend that it should be compatible with true traditional 3546preprocessors in all ways that actually matter. 3547 3548* Menu: 3549 3550* Traditional lexical analysis:: 3551* Traditional macros:: 3552* Traditional miscellany:: 3553* Traditional warnings:: 3554 3555 3556File: cpp.info, Node: Traditional lexical analysis, Next: Traditional macros, Up: Traditional Mode 3557 355810.1 Traditional lexical analysis 3559================================= 3560 3561The traditional preprocessor does not decompose its input into tokens 3562the same way a standards-conforming preprocessor does. The input is 3563simply treated as a stream of text with minimal internal form. 3564 3565 This implementation does not treat trigraphs (*note trigraphs::) 3566specially since they were an invention of the standards committee. It 3567handles arbitrarily-positioned escaped newlines properly and splices the 3568lines as you would expect; many traditional preprocessors did not do 3569this. 3570 3571 The form of horizontal whitespace in the input file is preserved in 3572the output. In particular, hard tabs remain hard tabs. This can be 3573useful if, for example, you are preprocessing a Makefile. 3574 3575 Traditional CPP only recognizes C-style block comments, and treats 3576the '/*' sequence as introducing a comment only if it lies outside 3577quoted text. Quoted text is introduced by the usual single and double 3578quotes, and also by an initial '<' in a '#include' directive. 3579 3580 Traditionally, comments are completely removed and are not replaced 3581with a space. Since a traditional compiler does its own tokenization of 3582the output of the preprocessor, this means that comments can effectively 3583be used as token paste operators. However, comments behave like 3584separators for text handled by the preprocessor itself, since it doesn't 3585re-lex its input. For example, in 3586 3587 #if foo/**/bar 3588 3589'foo' and 'bar' are distinct identifiers and expanded separately if they 3590happen to be macros. In other words, this directive is equivalent to 3591 3592 #if foo bar 3593 3594rather than 3595 3596 #if foobar 3597 3598 Generally speaking, in traditional mode an opening quote need not 3599have a matching closing quote. In particular, a macro may be defined 3600with replacement text that contains an unmatched quote. Of course, if 3601you attempt to compile preprocessed output containing an unmatched quote 3602you will get a syntax error. 3603 3604 However, all preprocessing directives other than '#define' require 3605matching quotes. For example: 3606 3607 #define m This macro's fine and has an unmatched quote 3608 "/* This is not a comment. */ 3609 /* This is a comment. The following #include directive 3610 is ill-formed. */ 3611 #include <stdio.h 3612 3613 Just as for the ISO preprocessor, what would be a closing quote can 3614be escaped with a backslash to prevent the quoted text from closing. 3615 3616 3617File: cpp.info, Node: Traditional macros, Next: Traditional miscellany, Prev: Traditional lexical analysis, Up: Traditional Mode 3618 361910.2 Traditional macros 3620======================= 3621 3622The major difference between traditional and ISO macros is that the 3623former expand to text rather than to a token sequence. CPP removes all 3624leading and trailing horizontal whitespace from a macro's replacement 3625text before storing it, but preserves the form of internal whitespace. 3626 3627 One consequence is that it is legitimate for the replacement text to 3628contain an unmatched quote (*note Traditional lexical analysis::). An 3629unclosed string or character constant continues into the text following 3630the macro call. Similarly, the text at the end of a macro's expansion 3631can run together with the text after the macro invocation to produce a 3632single token. 3633 3634 Normally comments are removed from the replacement text after the 3635macro is expanded, but if the '-CC' option is passed on the command-line 3636comments are preserved. (In fact, the current implementation removes 3637comments even before saving the macro replacement text, but it careful 3638to do it in such a way that the observed effect is identical even in the 3639function-like macro case.) 3640 3641 The ISO stringizing operator '#' and token paste operator '##' have 3642no special meaning. As explained later, an effect similar to these 3643operators can be obtained in a different way. Macro names that are 3644embedded in quotes, either from the main file or after macro 3645replacement, do not expand. 3646 3647 CPP replaces an unquoted object-like macro name with its replacement 3648text, and then rescans it for further macros to replace. Unlike 3649standard macro expansion, traditional macro expansion has no provision 3650to prevent recursion. If an object-like macro appears unquoted in its 3651replacement text, it will be replaced again during the rescan pass, and 3652so on _ad infinitum_. GCC detects when it is expanding recursive 3653macros, emits an error message, and continues after the offending macro 3654invocation. 3655 3656 #define PLUS + 3657 #define INC(x) PLUS+x 3658 INC(foo); 3659 ==> ++foo; 3660 3661 Function-like macros are similar in form but quite different in 3662behavior to their ISO counterparts. Their arguments are contained 3663within parentheses, are comma-separated, and can cross physical lines. 3664Commas within nested parentheses are not treated as argument separators. 3665Similarly, a quote in an argument cannot be left unclosed; a following 3666comma or parenthesis that comes before the closing quote is treated like 3667any other character. There is no facility for handling variadic macros. 3668 3669 This implementation removes all comments from macro arguments, unless 3670the '-C' option is given. The form of all other horizontal whitespace 3671in arguments is preserved, including leading and trailing whitespace. 3672In particular 3673 3674 f( ) 3675 3676is treated as an invocation of the macro 'f' with a single argument 3677consisting of a single space. If you want to invoke a function-like 3678macro that takes no arguments, you must not leave any whitespace between 3679the parentheses. 3680 3681 If a macro argument crosses a new line, the new line is replaced with 3682a space when forming the argument. If the previous line contained an 3683unterminated quote, the following line inherits the quoted state. 3684 3685 Traditional preprocessors replace parameters in the replacement text 3686with their arguments regardless of whether the parameters are within 3687quotes or not. This provides a way to stringize arguments. For example 3688 3689 #define str(x) "x" 3690 str(/* A comment */some text ) 3691 ==> "some text " 3692 3693Note that the comment is removed, but that the trailing space is 3694preserved. Here is an example of using a comment to effect token 3695pasting. 3696 3697 #define suffix(x) foo_/**/x 3698 suffix(bar) 3699 ==> foo_bar 3700 3701 3702File: cpp.info, Node: Traditional miscellany, Next: Traditional warnings, Prev: Traditional macros, Up: Traditional Mode 3703 370410.3 Traditional miscellany 3705=========================== 3706 3707Here are some things to be aware of when using the traditional 3708preprocessor. 3709 3710 * Preprocessing directives are recognized only when their leading '#' 3711 appears in the first column. There can be no whitespace between 3712 the beginning of the line and the '#', but whitespace can follow 3713 the '#'. 3714 3715 * A true traditional C preprocessor does not recognize '#error' or 3716 '#pragma', and may not recognize '#elif'. CPP supports all the 3717 directives in traditional mode that it supports in ISO mode, 3718 including extensions, with the exception that the effects of 3719 '#pragma GCC poison' are undefined. 3720 3721 * __STDC__ is not defined. 3722 3723 * If you use digraphs the behavior is undefined. 3724 3725 * If a line that looks like a directive appears within macro 3726 arguments, the behavior is undefined. 3727 3728 3729File: cpp.info, Node: Traditional warnings, Prev: Traditional miscellany, Up: Traditional Mode 3730 373110.4 Traditional warnings 3732========================= 3733 3734You can request warnings about features that did not exist, or worked 3735differently, in traditional C with the '-Wtraditional' option. GCC does 3736not warn about features of ISO C which you must use when you are using a 3737conforming compiler, such as the '#' and '##' operators. 3738 3739 Presently '-Wtraditional' warns about: 3740 3741 * Macro parameters that appear within string literals in the macro 3742 body. In traditional C macro replacement takes place within string 3743 literals, but does not in ISO C. 3744 3745 * In traditional C, some preprocessor directives did not exist. 3746 Traditional preprocessors would only consider a line to be a 3747 directive if the '#' appeared in column 1 on the line. Therefore 3748 '-Wtraditional' warns about directives that traditional C 3749 understands but would ignore because the '#' does not appear as the 3750 first character on the line. It also suggests you hide directives 3751 like '#pragma' not understood by traditional C by indenting them. 3752 Some traditional implementations would not recognize '#elif', so it 3753 suggests avoiding it altogether. 3754 3755 * A function-like macro that appears without an argument list. In 3756 some traditional preprocessors this was an error. In ISO C it 3757 merely means that the macro is not expanded. 3758 3759 * The unary plus operator. This did not exist in traditional C. 3760 3761 * The 'U' and 'LL' integer constant suffixes, which were not 3762 available in traditional C. (Traditional C does support the 'L' 3763 suffix for simple long integer constants.) You are not warned 3764 about uses of these suffixes in macros defined in system headers. 3765 For instance, 'UINT_MAX' may well be defined as '4294967295U', but 3766 you will not be warned if you use 'UINT_MAX'. 3767 3768 You can usually avoid the warning, and the related warning about 3769 constants which are so large that they are unsigned, by writing the 3770 integer constant in question in hexadecimal, with no U suffix. 3771 Take care, though, because this gives the wrong result in exotic 3772 cases. 3773 3774 3775File: cpp.info, Node: Implementation Details, Next: Invocation, Prev: Traditional Mode, Up: Top 3776 377711 Implementation Details 3778************************* 3779 3780Here we document details of how the preprocessor's implementation 3781affects its user-visible behavior. You should try to avoid undue 3782reliance on behavior described here, as it is possible that it will 3783change subtly in future implementations. 3784 3785 Also documented here are obsolete features still supported by CPP. 3786 3787* Menu: 3788 3789* Implementation-defined behavior:: 3790* Implementation limits:: 3791* Obsolete Features:: 3792 3793 3794File: cpp.info, Node: Implementation-defined behavior, Next: Implementation limits, Up: Implementation Details 3795 379611.1 Implementation-defined behavior 3797==================================== 3798 3799This is how CPP behaves in all the cases which the C standard describes 3800as "implementation-defined". This term means that the implementation is 3801free to do what it likes, but must document its choice and stick to it. 3802 3803 * The mapping of physical source file multi-byte characters to the 3804 execution character set. 3805 3806 The input character set can be specified using the 3807 '-finput-charset' option, while the execution character set may be 3808 controlled using the '-fexec-charset' and '-fwide-exec-charset' 3809 options. 3810 3811 * Identifier characters. 3812 3813 The C and C++ standards allow identifiers to be composed of '_' and 3814 the alphanumeric characters. C++ also allows universal character 3815 names. C99 and later C standards permit both universal character 3816 names and implementation-defined characters. In both C and C++ 3817 modes, GCC accepts in identifiers exactly those extended characters 3818 that correspond to universal character names permitted by the 3819 chosen standard. 3820 3821 GCC allows the '$' character in identifiers as an extension for 3822 most targets. This is true regardless of the 'std=' switch, since 3823 this extension cannot conflict with standards-conforming programs. 3824 When preprocessing assembler, however, dollars are not identifier 3825 characters by default. 3826 3827 Currently the targets that by default do not permit '$' are AVR, 3828 IP2K, MMIX, MIPS Irix 3, ARM aout, and PowerPC targets for the AIX 3829 operating system. 3830 3831 You can override the default with '-fdollars-in-identifiers' or 3832 'fno-dollars-in-identifiers'. *Note fdollars-in-identifiers::. 3833 3834 * Non-empty sequences of whitespace characters. 3835 3836 In textual output, each whitespace sequence is collapsed to a 3837 single space. For aesthetic reasons, the first token on each 3838 non-directive line of output is preceded with sufficient spaces 3839 that it appears in the same column as it did in the original source 3840 file. 3841 3842 * The numeric value of character constants in preprocessor 3843 expressions. 3844 3845 The preprocessor and compiler interpret character constants in the 3846 same way; i.e. escape sequences such as '\a' are given the values 3847 they would have on the target machine. 3848 3849 The compiler evaluates a multi-character character constant a 3850 character at a time, shifting the previous value left by the number 3851 of bits per target character, and then or-ing in the bit-pattern of 3852 the new character truncated to the width of a target character. 3853 The final bit-pattern is given type 'int', and is therefore signed, 3854 regardless of whether single characters are signed or not. If 3855 there are more characters in the constant than would fit in the 3856 target 'int' the compiler issues a warning, and the excess leading 3857 characters are ignored. 3858 3859 For example, ''ab'' for a target with an 8-bit 'char' would be 3860 interpreted as 3861 '(int) ((unsigned char) 'a' * 256 + (unsigned char) 'b')', and 3862 ''\234a'' as 3863 '(int) ((unsigned char) '\234' * 256 + (unsigned char) 'a')'. 3864 3865 * Source file inclusion. 3866 3867 For a discussion on how the preprocessor locates header files, 3868 *note Include Operation::. 3869 3870 * Interpretation of the filename resulting from a macro-expanded 3871 '#include' directive. 3872 3873 *Note Computed Includes::. 3874 3875 * Treatment of a '#pragma' directive that after macro-expansion 3876 results in a standard pragma. 3877 3878 No macro expansion occurs on any '#pragma' directive line, so the 3879 question does not arise. 3880 3881 Note that GCC does not yet implement any of the standard pragmas. 3882 3883 3884File: cpp.info, Node: Implementation limits, Next: Obsolete Features, Prev: Implementation-defined behavior, Up: Implementation Details 3885 388611.2 Implementation limits 3887========================== 3888 3889CPP has a small number of internal limits. This section lists the 3890limits which the C standard requires to be no lower than some minimum, 3891and all the others known. It is intended that there should be as few 3892limits as possible. If you encounter an undocumented or inconvenient 3893limit, please report that as a bug. *Note Reporting Bugs: (gcc)Bugs. 3894 3895 Where we say something is limited "only by available memory", that 3896means that internal data structures impose no intrinsic limit, and space 3897is allocated with 'malloc' or equivalent. The actual limit will 3898therefore depend on many things, such as the size of other things 3899allocated by the compiler at the same time, the amount of memory 3900consumed by other processes on the same computer, etc. 3901 3902 * Nesting levels of '#include' files. 3903 3904 We impose an arbitrary limit of 200 levels, to avoid runaway 3905 recursion. The standard requires at least 15 levels. 3906 3907 * Nesting levels of conditional inclusion. 3908 3909 The C standard mandates this be at least 63. CPP is limited only 3910 by available memory. 3911 3912 * Levels of parenthesized expressions within a full expression. 3913 3914 The C standard requires this to be at least 63. In preprocessor 3915 conditional expressions, it is limited only by available memory. 3916 3917 * Significant initial characters in an identifier or macro name. 3918 3919 The preprocessor treats all characters as significant. The C 3920 standard requires only that the first 63 be significant. 3921 3922 * Number of macros simultaneously defined in a single translation 3923 unit. 3924 3925 The standard requires at least 4095 be possible. CPP is limited 3926 only by available memory. 3927 3928 * Number of parameters in a macro definition and arguments in a macro 3929 call. 3930 3931 We allow 'USHRT_MAX', which is no smaller than 65,535. The minimum 3932 required by the standard is 127. 3933 3934 * Number of characters on a logical source line. 3935 3936 The C standard requires a minimum of 4096 be permitted. CPP places 3937 no limits on this, but you may get incorrect column numbers 3938 reported in diagnostics for lines longer than 65,535 characters. 3939 3940 * Maximum size of a source file. 3941 3942 The standard does not specify any lower limit on the maximum size 3943 of a source file. GNU cpp maps files into memory, so it is limited 3944 by the available address space. This is generally at least two 3945 gigabytes. Depending on the operating system, the size of physical 3946 memory may or may not be a limitation. 3947 3948 3949File: cpp.info, Node: Obsolete Features, Prev: Implementation limits, Up: Implementation Details 3950 395111.3 Obsolete Features 3952====================== 3953 3954CPP has some features which are present mainly for compatibility with 3955older programs. We discourage their use in new code. In some cases, we 3956plan to remove the feature in a future version of GCC. 3957 395811.3.1 Assertions 3959----------------- 3960 3961"Assertions" are a deprecated alternative to macros in writing 3962conditionals to test what sort of computer or system the compiled 3963program will run on. Assertions are usually predefined, but you can 3964define them with preprocessing directives or command-line options. 3965 3966 Assertions were intended to provide a more systematic way to describe 3967the compiler's target system and we added them for compatibility with 3968existing compilers. In practice they are just as unpredictable as the 3969system-specific predefined macros. In addition, they are not part of 3970any standard, and only a few compilers support them. Therefore, the use 3971of assertions is *less* portable than the use of system-specific 3972predefined macros. We recommend you do not use them at all. 3973 3974 An assertion looks like this: 3975 3976 #PREDICATE (ANSWER) 3977 3978PREDICATE must be a single identifier. ANSWER can be any sequence of 3979tokens; all characters are significant except for leading and trailing 3980whitespace, and differences in internal whitespace sequences are 3981ignored. (This is similar to the rules governing macro redefinition.) 3982Thus, '(x + y)' is different from '(x+y)' but equivalent to '( x + y )'. 3983Parentheses do not nest inside an answer. 3984 3985 To test an assertion, you write it in an '#if'. For example, this 3986conditional succeeds if either 'vax' or 'ns16000' has been asserted as 3987an answer for 'machine'. 3988 3989 #if #machine (vax) || #machine (ns16000) 3990 3991You can test whether _any_ answer is asserted for a predicate by 3992omitting the answer in the conditional: 3993 3994 #if #machine 3995 3996 Assertions are made with the '#assert' directive. Its sole argument 3997is the assertion to make, without the leading '#' that identifies 3998assertions in conditionals. 3999 4000 #assert PREDICATE (ANSWER) 4001 4002You may make several assertions with the same predicate and different 4003answers. Subsequent assertions do not override previous ones for the 4004same predicate. All the answers for any given predicate are 4005simultaneously true. 4006 4007 Assertions can be canceled with the '#unassert' directive. It has 4008the same syntax as '#assert'. In that form it cancels only the answer 4009which was specified on the '#unassert' line; other answers for that 4010predicate remain true. You can cancel an entire predicate by leaving 4011out the answer: 4012 4013 #unassert PREDICATE 4014 4015In either form, if no such assertion has been made, '#unassert' has no 4016effect. 4017 4018 You can also make or cancel assertions using command-line options. 4019*Note Invocation::. 4020 4021 4022File: cpp.info, Node: Invocation, Next: Environment Variables, Prev: Implementation Details, Up: Top 4023 402412 Invocation 4025************* 4026 4027Most often when you use the C preprocessor you do not have to invoke it 4028explicitly: the C compiler does so automatically. However, the 4029preprocessor is sometimes useful on its own. You can invoke the 4030preprocessor either with the 'cpp' command, or via 'gcc -E'. In GCC, 4031the preprocessor is actually integrated with the compiler rather than a 4032separate program, and both of these commands invoke GCC and tell it to 4033stop after the preprocessing phase. 4034 4035 The 'cpp' options listed here are also accepted by 'gcc' and have the 4036same meaning. Likewise the 'cpp' command accepts all the usual 'gcc' 4037driver options, although those pertaining to compilation phases after 4038preprocessing are ignored. 4039 4040 Only options specific to preprocessing behavior are documented here. 4041Refer to the GCC manual for full documentation of other driver options. 4042 4043 The 'cpp' command expects two file names as arguments, INFILE and 4044OUTFILE. The preprocessor reads INFILE together with any other files it 4045specifies with '#include'. All the output generated by the combined 4046input files is written in OUTFILE. 4047 4048 Either INFILE or OUTFILE may be '-', which as INFILE means to read 4049from standard input and as OUTFILE means to write to standard output. 4050If either file is omitted, it means the same as if '-' had been 4051specified for that file. You can also use the '-o OUTFILE' option to 4052specify the output file. 4053 4054 Unless otherwise noted, or the option ends in '=', all options which 4055take an argument may have that argument appear either immediately after 4056the option, or with a space between option and argument: '-Ifoo' and '-I 4057foo' have the same effect. 4058 4059 Many options have multi-letter names; therefore multiple 4060single-letter options may _not_ be grouped: '-dM' is very different from 4061'-d -M'. 4062 4063'-D NAME' 4064 Predefine NAME as a macro, with definition '1'. 4065 4066'-D NAME=DEFINITION' 4067 The contents of DEFINITION are tokenized and processed as if they 4068 appeared during translation phase three in a '#define' directive. 4069 In particular, the definition is truncated by embedded newline 4070 characters. 4071 4072 If you are invoking the preprocessor from a shell or shell-like 4073 program you may need to use the shell's quoting syntax to protect 4074 characters such as spaces that have a meaning in the shell syntax. 4075 4076 If you wish to define a function-like macro on the command line, 4077 write its argument list with surrounding parentheses before the 4078 equals sign (if any). Parentheses are meaningful to most shells, 4079 so you should quote the option. With 'sh' and 'csh', 4080 '-D'NAME(ARGS...)=DEFINITION'' works. 4081 4082 '-D' and '-U' options are processed in the order they are given on 4083 the command line. All '-imacros FILE' and '-include FILE' options 4084 are processed after all '-D' and '-U' options. 4085 4086'-U NAME' 4087 Cancel any previous definition of NAME, either built in or provided 4088 with a '-D' option. 4089 4090'-include FILE' 4091 Process FILE as if '#include "file"' appeared as the first line of 4092 the primary source file. However, the first directory searched for 4093 FILE is the preprocessor's working directory _instead of_ the 4094 directory containing the main source file. If not found there, it 4095 is searched for in the remainder of the '#include "..."' search 4096 chain as normal. 4097 4098 If multiple '-include' options are given, the files are included in 4099 the order they appear on the command line. 4100 4101'-imacros FILE' 4102 Exactly like '-include', except that any output produced by 4103 scanning FILE is thrown away. Macros it defines remain defined. 4104 This allows you to acquire all the macros from a header without 4105 also processing its declarations. 4106 4107 All files specified by '-imacros' are processed before all files 4108 specified by '-include'. 4109 4110'-undef' 4111 Do not predefine any system-specific or GCC-specific macros. The 4112 standard predefined macros remain defined. *Note Standard 4113 Predefined Macros::. 4114 4115'-pthread' 4116 Define additional macros required for using the POSIX threads 4117 library. You should use this option consistently for both 4118 compilation and linking. This option is supported on GNU/Linux 4119 targets, most other Unix derivatives, and also on x86 Cygwin and 4120 MinGW targets. 4121 4122'-M' 4123 Instead of outputting the result of preprocessing, output a rule 4124 suitable for 'make' describing the dependencies of the main source 4125 file. The preprocessor outputs one 'make' rule containing the 4126 object file name for that source file, a colon, and the names of 4127 all the included files, including those coming from '-include' or 4128 '-imacros' command-line options. 4129 4130 Unless specified explicitly (with '-MT' or '-MQ'), the object file 4131 name consists of the name of the source file with any suffix 4132 replaced with object file suffix and with any leading directory 4133 parts removed. If there are many included files then the rule is 4134 split into several lines using '\'-newline. The rule has no 4135 commands. 4136 4137 This option does not suppress the preprocessor's debug output, such 4138 as '-dM'. To avoid mixing such debug output with the dependency 4139 rules you should explicitly specify the dependency output file with 4140 '-MF', or use an environment variable like 'DEPENDENCIES_OUTPUT' 4141 (*note Environment Variables::). Debug output is still sent to the 4142 regular output stream as normal. 4143 4144 Passing '-M' to the driver implies '-E', and suppresses warnings 4145 with an implicit '-w'. 4146 4147'-MM' 4148 Like '-M' but do not mention header files that are found in system 4149 header directories, nor header files that are included, directly or 4150 indirectly, from such a header. 4151 4152 This implies that the choice of angle brackets or double quotes in 4153 an '#include' directive does not in itself determine whether that 4154 header appears in '-MM' dependency output. 4155 4156'-MF FILE' 4157 When used with '-M' or '-MM', specifies a file to write the 4158 dependencies to. If no '-MF' switch is given the preprocessor 4159 sends the rules to the same place it would send preprocessed 4160 output. 4161 4162 When used with the driver options '-MD' or '-MMD', '-MF' overrides 4163 the default dependency output file. 4164 4165 If FILE is '-', then the dependencies are written to 'stdout'. 4166 4167'-MG' 4168 In conjunction with an option such as '-M' requesting dependency 4169 generation, '-MG' assumes missing header files are generated files 4170 and adds them to the dependency list without raising an error. The 4171 dependency filename is taken directly from the '#include' directive 4172 without prepending any path. '-MG' also suppresses preprocessed 4173 output, as a missing header file renders this useless. 4174 4175 This feature is used in automatic updating of makefiles. 4176 4177'-MP' 4178 This option instructs CPP to add a phony target for each dependency 4179 other than the main file, causing each to depend on nothing. These 4180 dummy rules work around errors 'make' gives if you remove header 4181 files without updating the 'Makefile' to match. 4182 4183 This is typical output: 4184 4185 test.o: test.c test.h 4186 4187 test.h: 4188 4189'-MT TARGET' 4190 4191 Change the target of the rule emitted by dependency generation. By 4192 default CPP takes the name of the main input file, deletes any 4193 directory components and any file suffix such as '.c', and appends 4194 the platform's usual object suffix. The result is the target. 4195 4196 An '-MT' option sets the target to be exactly the string you 4197 specify. If you want multiple targets, you can specify them as a 4198 single argument to '-MT', or use multiple '-MT' options. 4199 4200 For example, '-MT '$(objpfx)foo.o'' might give 4201 4202 $(objpfx)foo.o: foo.c 4203 4204'-MQ TARGET' 4205 4206 Same as '-MT', but it quotes any characters which are special to 4207 Make. '-MQ '$(objpfx)foo.o'' gives 4208 4209 $$(objpfx)foo.o: foo.c 4210 4211 The default target is automatically quoted, as if it were given 4212 with '-MQ'. 4213 4214'-MD' 4215 '-MD' is equivalent to '-M -MF FILE', except that '-E' is not 4216 implied. The driver determines FILE based on whether an '-o' 4217 option is given. If it is, the driver uses its argument but with a 4218 suffix of '.d', otherwise it takes the name of the input file, 4219 removes any directory components and suffix, and applies a '.d' 4220 suffix. 4221 4222 If '-MD' is used in conjunction with '-E', any '-o' switch is 4223 understood to specify the dependency output file (*note -MF: 4224 dashMF.), but if used without '-E', each '-o' is understood to 4225 specify a target object file. 4226 4227 Since '-E' is not implied, '-MD' can be used to generate a 4228 dependency output file as a side effect of the compilation process. 4229 4230'-MMD' 4231 Like '-MD' except mention only user header files, not system header 4232 files. 4233 4234'-fpreprocessed' 4235 Indicate to the preprocessor that the input file has already been 4236 preprocessed. This suppresses things like macro expansion, 4237 trigraph conversion, escaped newline splicing, and processing of 4238 most directives. The preprocessor still recognizes and removes 4239 comments, so that you can pass a file preprocessed with '-C' to the 4240 compiler without problems. In this mode the integrated 4241 preprocessor is little more than a tokenizer for the front ends. 4242 4243 '-fpreprocessed' is implicit if the input file has one of the 4244 extensions '.i', '.ii' or '.mi'. These are the extensions that GCC 4245 uses for preprocessed files created by '-save-temps'. 4246 4247'-fdirectives-only' 4248 When preprocessing, handle directives, but do not expand macros. 4249 4250 The option's behavior depends on the '-E' and '-fpreprocessed' 4251 options. 4252 4253 With '-E', preprocessing is limited to the handling of directives 4254 such as '#define', '#ifdef', and '#error'. Other preprocessor 4255 operations, such as macro expansion and trigraph conversion are not 4256 performed. In addition, the '-dD' option is implicitly enabled. 4257 4258 With '-fpreprocessed', predefinition of command line and most 4259 builtin macros is disabled. Macros such as '__LINE__', which are 4260 contextually dependent, are handled normally. This enables 4261 compilation of files previously preprocessed with '-E 4262 -fdirectives-only'. 4263 4264 With both '-E' and '-fpreprocessed', the rules for '-fpreprocessed' 4265 take precedence. This enables full preprocessing of files 4266 previously preprocessed with '-E -fdirectives-only'. 4267 4268'-fdollars-in-identifiers' 4269 Accept '$' in identifiers. *Note Identifier characters::. 4270 4271'-fextended-identifiers' 4272 Accept universal character names and extended characters in 4273 identifiers. This option is enabled by default for C99 (and later 4274 C standard versions) and C++. 4275 4276'-fno-canonical-system-headers' 4277 When preprocessing, do not shorten system header paths with 4278 canonicalization. 4279 4280'-fmax-include-depth=DEPTH' 4281 Set the maximum depth of the nested #include. The default is 200. 4282 4283'-ftabstop=WIDTH' 4284 Set the distance between tab stops. This helps the preprocessor 4285 report correct column numbers in warnings or errors, even if tabs 4286 appear on the line. If the value is less than 1 or greater than 4287 100, the option is ignored. The default is 8. 4288 4289'-ftrack-macro-expansion[=LEVEL]' 4290 Track locations of tokens across macro expansions. This allows the 4291 compiler to emit diagnostic about the current macro expansion stack 4292 when a compilation error occurs in a macro expansion. Using this 4293 option makes the preprocessor and the compiler consume more memory. 4294 The LEVEL parameter can be used to choose the level of precision of 4295 token location tracking thus decreasing the memory consumption if 4296 necessary. Value '0' of LEVEL de-activates this option. Value '1' 4297 tracks tokens locations in a degraded mode for the sake of minimal 4298 memory overhead. In this mode all tokens resulting from the 4299 expansion of an argument of a function-like macro have the same 4300 location. Value '2' tracks tokens locations completely. This 4301 value is the most memory hungry. When this option is given no 4302 argument, the default parameter value is '2'. 4303 4304 Note that '-ftrack-macro-expansion=2' is activated by default. 4305 4306'-fmacro-prefix-map=OLD=NEW' 4307 When preprocessing files residing in directory 'OLD', expand the 4308 '__FILE__' and '__BASE_FILE__' macros as if the files resided in 4309 directory 'NEW' instead. This can be used to change an absolute 4310 path to a relative path by using '.' for NEW which can result in 4311 more reproducible builds that are location independent. This 4312 option also affects '__builtin_FILE()' during compilation. See 4313 also '-ffile-prefix-map'. 4314 4315'-fexec-charset=CHARSET' 4316 Set the execution character set, used for string and character 4317 constants. The default is UTF-8. CHARSET can be any encoding 4318 supported by the system's 'iconv' library routine. 4319 4320'-fwide-exec-charset=CHARSET' 4321 Set the wide execution character set, used for wide string and 4322 character constants. The default is one of UTF-32BE, UTF-32LE, 4323 UTF-16BE, or UTF-16LE, whichever corresponds to the width of 4324 'wchar_t' and the big-endian or little-endian byte order being used 4325 for code generation. As with '-fexec-charset', CHARSET can be any 4326 encoding supported by the system's 'iconv' library routine; 4327 however, you will have problems with encodings that do not fit 4328 exactly in 'wchar_t'. 4329 4330'-finput-charset=CHARSET' 4331 Set the input character set, used for translation from the 4332 character set of the input file to the source character set used by 4333 GCC. If the locale does not specify, or GCC cannot get this 4334 information from the locale, the default is UTF-8. This can be 4335 overridden by either the locale or this command-line option. 4336 Currently the command-line option takes precedence if there's a 4337 conflict. CHARSET can be any encoding supported by the system's 4338 'iconv' library routine. 4339 4340'-fworking-directory' 4341 Enable generation of linemarkers in the preprocessor output that 4342 let the compiler know the current working directory at the time of 4343 preprocessing. When this option is enabled, the preprocessor 4344 emits, after the initial linemarker, a second linemarker with the 4345 current working directory followed by two slashes. GCC uses this 4346 directory, when it's present in the preprocessed input, as the 4347 directory emitted as the current working directory in some 4348 debugging information formats. This option is implicitly enabled 4349 if debugging information is enabled, but this can be inhibited with 4350 the negated form '-fno-working-directory'. If the '-P' flag is 4351 present in the command line, this option has no effect, since no 4352 '#line' directives are emitted whatsoever. 4353 4354'-A PREDICATE=ANSWER' 4355 Make an assertion with the predicate PREDICATE and answer ANSWER. 4356 This form is preferred to the older form '-A PREDICATE(ANSWER)', 4357 which is still supported, because it does not use shell special 4358 characters. *Note Obsolete Features::. 4359 4360'-A -PREDICATE=ANSWER' 4361 Cancel an assertion with the predicate PREDICATE and answer ANSWER. 4362 4363'-C' 4364 Do not discard comments. All comments are passed through to the 4365 output file, except for comments in processed directives, which are 4366 deleted along with the directive. 4367 4368 You should be prepared for side effects when using '-C'; it causes 4369 the preprocessor to treat comments as tokens in their own right. 4370 For example, comments appearing at the start of what would be a 4371 directive line have the effect of turning that line into an 4372 ordinary source line, since the first token on the line is no 4373 longer a '#'. 4374 4375'-CC' 4376 Do not discard comments, including during macro expansion. This is 4377 like '-C', except that comments contained within macros are also 4378 passed through to the output file where the macro is expanded. 4379 4380 In addition to the side effects of the '-C' option, the '-CC' 4381 option causes all C++-style comments inside a macro to be converted 4382 to C-style comments. This is to prevent later use of that macro 4383 from inadvertently commenting out the remainder of the source line. 4384 4385 The '-CC' option is generally used to support lint comments. 4386 4387'-P' 4388 Inhibit generation of linemarkers in the output from the 4389 preprocessor. This might be useful when running the preprocessor 4390 on something that is not C code, and will be sent to a program 4391 which might be confused by the linemarkers. *Note Preprocessor 4392 Output::. 4393 4394'-traditional' 4395'-traditional-cpp' 4396 4397 Try to imitate the behavior of pre-standard C preprocessors, as 4398 opposed to ISO C preprocessors. *Note Traditional Mode::. 4399 4400 Note that GCC does not otherwise attempt to emulate a pre-standard 4401 C compiler, and these options are only supported with the '-E' 4402 switch, or when invoking CPP explicitly. 4403 4404'-trigraphs' 4405 Support ISO C trigraphs. These are three-character sequences, all 4406 starting with '??', that are defined by ISO C to stand for single 4407 characters. For example, '??/' stands for '\', so ''??/n'' is a 4408 character constant for a newline. *Note Initial processing::. 4409 4410 By default, GCC ignores trigraphs, but in standard-conforming modes 4411 it converts them. See the '-std' and '-ansi' options. 4412 4413'-remap' 4414 Enable special code to work around file systems which only permit 4415 very short file names, such as MS-DOS. 4416 4417'-H' 4418 Print the name of each header file used, in addition to other 4419 normal activities. Each name is indented to show how deep in the 4420 '#include' stack it is. Precompiled header files are also printed, 4421 even if they are found to be invalid; an invalid precompiled header 4422 file is printed with '...x' and a valid one with '...!' . 4423 4424'-dLETTERS' 4425 Says to make debugging dumps during compilation as specified by 4426 LETTERS. The flags documented here are those relevant to the 4427 preprocessor. Other LETTERS are interpreted by the compiler 4428 proper, or reserved for future versions of GCC, and so are silently 4429 ignored. If you specify LETTERS whose behavior conflicts, the 4430 result is undefined. 4431 4432 '-dM' 4433 Instead of the normal output, generate a list of '#define' 4434 directives for all the macros defined during the execution of 4435 the preprocessor, including predefined macros. This gives you 4436 a way of finding out what is predefined in your version of the 4437 preprocessor. Assuming you have no file 'foo.h', the command 4438 4439 touch foo.h; cpp -dM foo.h 4440 4441 shows all the predefined macros. 4442 4443 '-dD' 4444 Like '-dM' except in two respects: it does _not_ include the 4445 predefined macros, and it outputs _both_ the '#define' 4446 directives and the result of preprocessing. Both kinds of 4447 output go to the standard output file. 4448 4449 '-dN' 4450 Like '-dD', but emit only the macro names, not their 4451 expansions. 4452 4453 '-dI' 4454 Output '#include' directives in addition to the result of 4455 preprocessing. 4456 4457 '-dU' 4458 Like '-dD' except that only macros that are expanded, or whose 4459 definedness is tested in preprocessor directives, are output; 4460 the output is delayed until the use or test of the macro; and 4461 '#undef' directives are also output for macros tested but 4462 undefined at the time. 4463 4464'-fdebug-cpp' 4465 This option is only useful for debugging GCC. When used from CPP or 4466 with '-E', it dumps debugging information about location maps. 4467 Every token in the output is preceded by the dump of the map its 4468 location belongs to. 4469 4470 When used from GCC without '-E', this option has no effect. 4471 4472'-I DIR' 4473'-iquote DIR' 4474'-isystem DIR' 4475'-idirafter DIR' 4476 Add the directory DIR to the list of directories to be searched for 4477 header files during preprocessing. *Note Search Path::. If DIR 4478 begins with '=' or '$SYSROOT', then the '=' or '$SYSROOT' is 4479 replaced by the sysroot prefix; see '--sysroot' and '-isysroot'. 4480 4481 Directories specified with '-iquote' apply only to the quote form 4482 of the directive, '#include "FILE"'. Directories specified with 4483 '-I', '-isystem', or '-idirafter' apply to lookup for both the 4484 '#include "FILE"' and '#include <FILE>' directives. 4485 4486 You can specify any number or combination of these options on the 4487 command line to search for header files in several directories. 4488 The lookup order is as follows: 4489 4490 1. For the quote form of the include directive, the directory of 4491 the current file is searched first. 4492 4493 2. For the quote form of the include directive, the directories 4494 specified by '-iquote' options are searched in left-to-right 4495 order, as they appear on the command line. 4496 4497 3. Directories specified with '-I' options are scanned in 4498 left-to-right order. 4499 4500 4. Directories specified with '-isystem' options are scanned in 4501 left-to-right order. 4502 4503 5. Standard system directories are scanned. 4504 4505 6. Directories specified with '-idirafter' options are scanned in 4506 left-to-right order. 4507 4508 You can use '-I' to override a system header file, substituting 4509 your own version, since these directories are searched before the 4510 standard system header file directories. However, you should not 4511 use this option to add directories that contain vendor-supplied 4512 system header files; use '-isystem' for that. 4513 4514 The '-isystem' and '-idirafter' options also mark the directory as 4515 a system directory, so that it gets the same special treatment that 4516 is applied to the standard system directories. *Note System 4517 Headers::. 4518 4519 If a standard system include directory, or a directory specified 4520 with '-isystem', is also specified with '-I', the '-I' option is 4521 ignored. The directory is still searched but as a system directory 4522 at its normal position in the system include chain. This is to 4523 ensure that GCC's procedure to fix buggy system headers and the 4524 ordering for the '#include_next' directive are not inadvertently 4525 changed. If you really need to change the search order for system 4526 directories, use the '-nostdinc' and/or '-isystem' options. *Note 4527 System Headers::. 4528 4529'-I-' 4530 Split the include path. This option has been deprecated. Please 4531 use '-iquote' instead for '-I' directories before the '-I-' and 4532 remove the '-I-' option. 4533 4534 Any directories specified with '-I' options before '-I-' are 4535 searched only for headers requested with '#include "FILE"'; they 4536 are not searched for '#include <FILE>'. If additional directories 4537 are specified with '-I' options after the '-I-', those directories 4538 are searched for all '#include' directives. 4539 4540 In addition, '-I-' inhibits the use of the directory of the current 4541 file directory as the first search directory for '#include "FILE"'. 4542 There is no way to override this effect of '-I-'. *Note Search 4543 Path::. 4544 4545'-iprefix PREFIX' 4546 Specify PREFIX as the prefix for subsequent '-iwithprefix' options. 4547 If the prefix represents a directory, you should include the final 4548 '/'. 4549 4550'-iwithprefix DIR' 4551'-iwithprefixbefore DIR' 4552 Append DIR to the prefix specified previously with '-iprefix', and 4553 add the resulting directory to the include search path. 4554 '-iwithprefixbefore' puts it in the same place '-I' would; 4555 '-iwithprefix' puts it where '-idirafter' would. 4556 4557'-isysroot DIR' 4558 This option is like the '--sysroot' option, but applies only to 4559 header files (except for Darwin targets, where it applies to both 4560 header files and libraries). See the '--sysroot' option for more 4561 information. 4562 4563'-imultilib DIR' 4564 Use DIR as a subdirectory of the directory containing 4565 target-specific C++ headers. 4566 4567'-nostdinc' 4568 Do not search the standard system directories for header files. 4569 Only the directories explicitly specified with '-I', '-iquote', 4570 '-isystem', and/or '-idirafter' options (and the directory of the 4571 current file, if appropriate) are searched. 4572 4573'-nostdinc++' 4574 Do not search for header files in the C++-specific standard 4575 directories, but do still search the other standard directories. 4576 (This option is used when building the C++ library.) 4577 4578'-Wcomment' 4579'-Wcomments' 4580 Warn whenever a comment-start sequence '/*' appears in a '/*' 4581 comment, or whenever a backslash-newline appears in a '//' comment. 4582 This warning is enabled by '-Wall'. 4583 4584'-Wtrigraphs' 4585 Warn if any trigraphs are encountered that might change the meaning 4586 of the program. Trigraphs within comments are not warned about, 4587 except those that would form escaped newlines. 4588 4589 This option is implied by '-Wall'. If '-Wall' is not given, this 4590 option is still enabled unless trigraphs are enabled. To get 4591 trigraph conversion without warnings, but get the other '-Wall' 4592 warnings, use '-trigraphs -Wall -Wno-trigraphs'. 4593 4594'-Wundef' 4595 Warn if an undefined identifier is evaluated in an '#if' directive. 4596 Such identifiers are replaced with zero. 4597 4598'-Wexpansion-to-defined' 4599 Warn whenever 'defined' is encountered in the expansion of a macro 4600 (including the case where the macro is expanded by an '#if' 4601 directive). Such usage is not portable. This warning is also 4602 enabled by '-Wpedantic' and '-Wextra'. 4603 4604'-Wunused-macros' 4605 Warn about macros defined in the main file that are unused. A 4606 macro is "used" if it is expanded or tested for existence at least 4607 once. The preprocessor also warns if the macro has not been used 4608 at the time it is redefined or undefined. 4609 4610 Built-in macros, macros defined on the command line, and macros 4611 defined in include files are not warned about. 4612 4613 _Note:_ If a macro is actually used, but only used in skipped 4614 conditional blocks, then the preprocessor reports it as unused. To 4615 avoid the warning in such a case, you might improve the scope of 4616 the macro's definition by, for example, moving it into the first 4617 skipped block. Alternatively, you could provide a dummy use with 4618 something like: 4619 4620 #if defined the_macro_causing_the_warning 4621 #endif 4622 4623'-Wno-endif-labels' 4624 Do not warn whenever an '#else' or an '#endif' are followed by 4625 text. This sometimes happens in older programs with code of the 4626 form 4627 4628 #if FOO 4629 ... 4630 #else FOO 4631 ... 4632 #endif FOO 4633 4634 The second and third 'FOO' should be in comments. This warning is 4635 on by default. 4636 4637 4638File: cpp.info, Node: Environment Variables, Next: GNU Free Documentation License, Prev: Invocation, Up: Top 4639 464013 Environment Variables 4641************************ 4642 4643This section describes the environment variables that affect how CPP 4644operates. You can use them to specify directories or prefixes to use 4645when searching for include files, or to control dependency output. 4646 4647 Note that you can also specify places to search using options such as 4648'-I', and control dependency output with options like '-M' (*note 4649Invocation::). These take precedence over environment variables, which 4650in turn take precedence over the configuration of GCC. 4651 4652'CPATH' 4653'C_INCLUDE_PATH' 4654'CPLUS_INCLUDE_PATH' 4655'OBJC_INCLUDE_PATH' 4656 Each variable's value is a list of directories separated by a 4657 special character, much like 'PATH', in which to look for header 4658 files. The special character, 'PATH_SEPARATOR', is 4659 target-dependent and determined at GCC build time. For Microsoft 4660 Windows-based targets it is a semicolon, and for almost all other 4661 targets it is a colon. 4662 4663 'CPATH' specifies a list of directories to be searched as if 4664 specified with '-I', but after any paths given with '-I' options on 4665 the command line. This environment variable is used regardless of 4666 which language is being preprocessed. 4667 4668 The remaining environment variables apply only when preprocessing 4669 the particular language indicated. Each specifies a list of 4670 directories to be searched as if specified with '-isystem', but 4671 after any paths given with '-isystem' options on the command line. 4672 4673 In all these variables, an empty element instructs the compiler to 4674 search its current working directory. Empty elements can appear at 4675 the beginning or end of a path. For instance, if the value of 4676 'CPATH' is ':/special/include', that has the same effect as 4677 '-I. -I/special/include'. 4678 4679 See also *note Search Path::. 4680 4681'DEPENDENCIES_OUTPUT' 4682 If this variable is set, its value specifies how to output 4683 dependencies for Make based on the non-system header files 4684 processed by the compiler. System header files are ignored in the 4685 dependency output. 4686 4687 The value of 'DEPENDENCIES_OUTPUT' can be just a file name, in 4688 which case the Make rules are written to that file, guessing the 4689 target name from the source file name. Or the value can have the 4690 form 'FILE TARGET', in which case the rules are written to file 4691 FILE using TARGET as the target name. 4692 4693 In other words, this environment variable is equivalent to 4694 combining the options '-MM' and '-MF' (*note Invocation::), with an 4695 optional '-MT' switch too. 4696 4697'SUNPRO_DEPENDENCIES' 4698 This variable is the same as 'DEPENDENCIES_OUTPUT' (see above), 4699 except that system header files are not ignored, so it implies '-M' 4700 rather than '-MM'. However, the dependence on the main input file 4701 is omitted. *Note Invocation::. 4702 4703'SOURCE_DATE_EPOCH' 4704 If this variable is set, its value specifies a UNIX timestamp to be 4705 used in replacement of the current date and time in the '__DATE__' 4706 and '__TIME__' macros, so that the embedded timestamps become 4707 reproducible. 4708 4709 The value of 'SOURCE_DATE_EPOCH' must be a UNIX timestamp, defined 4710 as the number of seconds (excluding leap seconds) since 01 Jan 1970 4711 00:00:00 represented in ASCII; identical to the output of ''date 4712 +%s'' on GNU/Linux and other systems that support the '%s' 4713 extension in the 'date' command. 4714 4715 The value should be a known timestamp such as the last modification 4716 time of the source or package and it should be set by the build 4717 process. 4718 4719 4720File: cpp.info, Node: GNU Free Documentation License, Next: Index of Directives, Prev: Environment Variables, Up: Top 4721 4722GNU Free Documentation License 4723****************************** 4724 4725 Version 1.3, 3 November 2008 4726 4727 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. 4728 <http://fsf.org/> 4729 4730 Everyone is permitted to copy and distribute verbatim copies 4731 of this license document, but changing it is not allowed. 4732 4733 0. PREAMBLE 4734 4735 The purpose of this License is to make a manual, textbook, or other 4736 functional and useful document "free" in the sense of freedom: to 4737 assure everyone the effective freedom to copy and redistribute it, 4738 with or without modifying it, either commercially or 4739 noncommercially. Secondarily, this License preserves for the 4740 author and publisher a way to get credit for their work, while not 4741 being considered responsible for modifications made by others. 4742 4743 This License is a kind of "copyleft", which means that derivative 4744 works of the document must themselves be free in the same sense. 4745 It complements the GNU General Public License, which is a copyleft 4746 license designed for free software. 4747 4748 We have designed this License in order to use it for manuals for 4749 free software, because free software needs free documentation: a 4750 free program should come with manuals providing the same freedoms 4751 that the software does. But this License is not limited to 4752 software manuals; it can be used for any textual work, regardless 4753 of subject matter or whether it is published as a printed book. We 4754 recommend this License principally for works whose purpose is 4755 instruction or reference. 4756 4757 1. APPLICABILITY AND DEFINITIONS 4758 4759 This License applies to any manual or other work, in any medium, 4760 that contains a notice placed by the copyright holder saying it can 4761 be distributed under the terms of this License. Such a notice 4762 grants a world-wide, royalty-free license, unlimited in duration, 4763 to use that work under the conditions stated herein. The 4764 "Document", below, refers to any such manual or work. Any member 4765 of the public is a licensee, and is addressed as "you". You accept 4766 the license if you copy, modify or distribute the work in a way 4767 requiring permission under copyright law. 4768 4769 A "Modified Version" of the Document means any work containing the 4770 Document or a portion of it, either copied verbatim, or with 4771 modifications and/or translated into another language. 4772 4773 A "Secondary Section" is a named appendix or a front-matter section 4774 of the Document that deals exclusively with the relationship of the 4775 publishers or authors of the Document to the Document's overall 4776 subject (or to related matters) and contains nothing that could 4777 fall directly within that overall subject. (Thus, if the Document 4778 is in part a textbook of mathematics, a Secondary Section may not 4779 explain any mathematics.) The relationship could be a matter of 4780 historical connection with the subject or with related matters, or 4781 of legal, commercial, philosophical, ethical or political position 4782 regarding them. 4783 4784 The "Invariant Sections" are certain Secondary Sections whose 4785 titles are designated, as being those of Invariant Sections, in the 4786 notice that says that the Document is released under this License. 4787 If a section does not fit the above definition of Secondary then it 4788 is not allowed to be designated as Invariant. The Document may 4789 contain zero Invariant Sections. If the Document does not identify 4790 any Invariant Sections then there are none. 4791 4792 The "Cover Texts" are certain short passages of text that are 4793 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 4794 that says that the Document is released under this License. A 4795 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 4796 be at most 25 words. 4797 4798 A "Transparent" copy of the Document means a machine-readable copy, 4799 represented in a format whose specification is available to the 4800 general public, that is suitable for revising the document 4801 straightforwardly with generic text editors or (for images composed 4802 of pixels) generic paint programs or (for drawings) some widely 4803 available drawing editor, and that is suitable for input to text 4804 formatters or for automatic translation to a variety of formats 4805 suitable for input to text formatters. A copy made in an otherwise 4806 Transparent file format whose markup, or absence of markup, has 4807 been arranged to thwart or discourage subsequent modification by 4808 readers is not Transparent. An image format is not Transparent if 4809 used for any substantial amount of text. A copy that is not 4810 "Transparent" is called "Opaque". 4811 4812 Examples of suitable formats for Transparent copies include plain 4813 ASCII without markup, Texinfo input format, LaTeX input format, 4814 SGML or XML using a publicly available DTD, and standard-conforming 4815 simple HTML, PostScript or PDF designed for human modification. 4816 Examples of transparent image formats include PNG, XCF and JPG. 4817 Opaque formats include proprietary formats that can be read and 4818 edited only by proprietary word processors, SGML or XML for which 4819 the DTD and/or processing tools are not generally available, and 4820 the machine-generated HTML, PostScript or PDF produced by some word 4821 processors for output purposes only. 4822 4823 The "Title Page" means, for a printed book, the title page itself, 4824 plus such following pages as are needed to hold, legibly, the 4825 material this License requires to appear in the title page. For 4826 works in formats which do not have any title page as such, "Title 4827 Page" means the text near the most prominent appearance of the 4828 work's title, preceding the beginning of the body of the text. 4829 4830 The "publisher" means any person or entity that distributes copies 4831 of the Document to the public. 4832 4833 A section "Entitled XYZ" means a named subunit of the Document 4834 whose title either is precisely XYZ or contains XYZ in parentheses 4835 following text that translates XYZ in another language. (Here XYZ 4836 stands for a specific section name mentioned below, such as 4837 "Acknowledgements", "Dedications", "Endorsements", or "History".) 4838 To "Preserve the Title" of such a section when you modify the 4839 Document means that it remains a section "Entitled XYZ" according 4840 to this definition. 4841 4842 The Document may include Warranty Disclaimers next to the notice 4843 which states that this License applies to the Document. These 4844 Warranty Disclaimers are considered to be included by reference in 4845 this License, but only as regards disclaiming warranties: any other 4846 implication that these Warranty Disclaimers may have is void and 4847 has no effect on the meaning of this License. 4848 4849 2. VERBATIM COPYING 4850 4851 You may copy and distribute the Document in any medium, either 4852 commercially or noncommercially, provided that this License, the 4853 copyright notices, and the license notice saying this License 4854 applies to the Document are reproduced in all copies, and that you 4855 add no other conditions whatsoever to those of this License. You 4856 may not use technical measures to obstruct or control the reading 4857 or further copying of the copies you make or distribute. However, 4858 you may accept compensation in exchange for copies. If you 4859 distribute a large enough number of copies you must also follow the 4860 conditions in section 3. 4861 4862 You may also lend copies, under the same conditions stated above, 4863 and you may publicly display copies. 4864 4865 3. COPYING IN QUANTITY 4866 4867 If you publish printed copies (or copies in media that commonly 4868 have printed covers) of the Document, numbering more than 100, and 4869 the Document's license notice requires Cover Texts, you must 4870 enclose the copies in covers that carry, clearly and legibly, all 4871 these Cover Texts: Front-Cover Texts on the front cover, and 4872 Back-Cover Texts on the back cover. Both covers must also clearly 4873 and legibly identify you as the publisher of these copies. The 4874 front cover must present the full title with all words of the title 4875 equally prominent and visible. You may add other material on the 4876 covers in addition. Copying with changes limited to the covers, as 4877 long as they preserve the title of the Document and satisfy these 4878 conditions, can be treated as verbatim copying in other respects. 4879 4880 If the required texts for either cover are too voluminous to fit 4881 legibly, you should put the first ones listed (as many as fit 4882 reasonably) on the actual cover, and continue the rest onto 4883 adjacent pages. 4884 4885 If you publish or distribute Opaque copies of the Document 4886 numbering more than 100, you must either include a machine-readable 4887 Transparent copy along with each Opaque copy, or state in or with 4888 each Opaque copy a computer-network location from which the general 4889 network-using public has access to download using public-standard 4890 network protocols a complete Transparent copy of the Document, free 4891 of added material. If you use the latter option, you must take 4892 reasonably prudent steps, when you begin distribution of Opaque 4893 copies in quantity, to ensure that this Transparent copy will 4894 remain thus accessible at the stated location until at least one 4895 year after the last time you distribute an Opaque copy (directly or 4896 through your agents or retailers) of that edition to the public. 4897 4898 It is requested, but not required, that you contact the authors of 4899 the Document well before redistributing any large number of copies, 4900 to give them a chance to provide you with an updated version of the 4901 Document. 4902 4903 4. MODIFICATIONS 4904 4905 You may copy and distribute a Modified Version of the Document 4906 under the conditions of sections 2 and 3 above, provided that you 4907 release the Modified Version under precisely this License, with the 4908 Modified Version filling the role of the Document, thus licensing 4909 distribution and modification of the Modified Version to whoever 4910 possesses a copy of it. In addition, you must do these things in 4911 the Modified Version: 4912 4913 A. Use in the Title Page (and on the covers, if any) a title 4914 distinct from that of the Document, and from those of previous 4915 versions (which should, if there were any, be listed in the 4916 History section of the Document). You may use the same title 4917 as a previous version if the original publisher of that 4918 version gives permission. 4919 4920 B. List on the Title Page, as authors, one or more persons or 4921 entities responsible for authorship of the modifications in 4922 the Modified Version, together with at least five of the 4923 principal authors of the Document (all of its principal 4924 authors, if it has fewer than five), unless they release you 4925 from this requirement. 4926 4927 C. State on the Title page the name of the publisher of the 4928 Modified Version, as the publisher. 4929 4930 D. Preserve all the copyright notices of the Document. 4931 4932 E. Add an appropriate copyright notice for your modifications 4933 adjacent to the other copyright notices. 4934 4935 F. Include, immediately after the copyright notices, a license 4936 notice giving the public permission to use the Modified 4937 Version under the terms of this License, in the form shown in 4938 the Addendum below. 4939 4940 G. Preserve in that license notice the full lists of Invariant 4941 Sections and required Cover Texts given in the Document's 4942 license notice. 4943 4944 H. Include an unaltered copy of this License. 4945 4946 I. Preserve the section Entitled "History", Preserve its Title, 4947 and add to it an item stating at least the title, year, new 4948 authors, and publisher of the Modified Version as given on the 4949 Title Page. If there is no section Entitled "History" in the 4950 Document, create one stating the title, year, authors, and 4951 publisher of the Document as given on its Title Page, then add 4952 an item describing the Modified Version as stated in the 4953 previous sentence. 4954 4955 J. Preserve the network location, if any, given in the Document 4956 for public access to a Transparent copy of the Document, and 4957 likewise the network locations given in the Document for 4958 previous versions it was based on. These may be placed in the 4959 "History" section. You may omit a network location for a work 4960 that was published at least four years before the Document 4961 itself, or if the original publisher of the version it refers 4962 to gives permission. 4963 4964 K. For any section Entitled "Acknowledgements" or "Dedications", 4965 Preserve the Title of the section, and preserve in the section 4966 all the substance and tone of each of the contributor 4967 acknowledgements and/or dedications given therein. 4968 4969 L. Preserve all the Invariant Sections of the Document, unaltered 4970 in their text and in their titles. Section numbers or the 4971 equivalent are not considered part of the section titles. 4972 4973 M. Delete any section Entitled "Endorsements". Such a section 4974 may not be included in the Modified Version. 4975 4976 N. Do not retitle any existing section to be Entitled 4977 "Endorsements" or to conflict in title with any Invariant 4978 Section. 4979 4980 O. Preserve any Warranty Disclaimers. 4981 4982 If the Modified Version includes new front-matter sections or 4983 appendices that qualify as Secondary Sections and contain no 4984 material copied from the Document, you may at your option designate 4985 some or all of these sections as invariant. To do this, add their 4986 titles to the list of Invariant Sections in the Modified Version's 4987 license notice. These titles must be distinct from any other 4988 section titles. 4989 4990 You may add a section Entitled "Endorsements", provided it contains 4991 nothing but endorsements of your Modified Version by various 4992 parties--for example, statements of peer review or that the text 4993 has been approved by an organization as the authoritative 4994 definition of a standard. 4995 4996 You may add a passage of up to five words as a Front-Cover Text, 4997 and a passage of up to 25 words as a Back-Cover Text, to the end of 4998 the list of Cover Texts in the Modified Version. Only one passage 4999 of Front-Cover Text and one of Back-Cover Text may be added by (or 5000 through arrangements made by) any one entity. If the Document 5001 already includes a cover text for the same cover, previously added 5002 by you or by arrangement made by the same entity you are acting on 5003 behalf of, you may not add another; but you may replace the old 5004 one, on explicit permission from the previous publisher that added 5005 the old one. 5006 5007 The author(s) and publisher(s) of the Document do not by this 5008 License give permission to use their names for publicity for or to 5009 assert or imply endorsement of any Modified Version. 5010 5011 5. COMBINING DOCUMENTS 5012 5013 You may combine the Document with other documents released under 5014 this License, under the terms defined in section 4 above for 5015 modified versions, provided that you include in the combination all 5016 of the Invariant Sections of all of the original documents, 5017 unmodified, and list them all as Invariant Sections of your 5018 combined work in its license notice, and that you preserve all 5019 their Warranty Disclaimers. 5020 5021 The combined work need only contain one copy of this License, and 5022 multiple identical Invariant Sections may be replaced with a single 5023 copy. If there are multiple Invariant Sections with the same name 5024 but different contents, make the title of each such section unique 5025 by adding at the end of it, in parentheses, the name of the 5026 original author or publisher of that section if known, or else a 5027 unique number. Make the same adjustment to the section titles in 5028 the list of Invariant Sections in the license notice of the 5029 combined work. 5030 5031 In the combination, you must combine any sections Entitled 5032 "History" in the various original documents, forming one section 5033 Entitled "History"; likewise combine any sections Entitled 5034 "Acknowledgements", and any sections Entitled "Dedications". You 5035 must delete all sections Entitled "Endorsements." 5036 5037 6. COLLECTIONS OF DOCUMENTS 5038 5039 You may make a collection consisting of the Document and other 5040 documents released under this License, and replace the individual 5041 copies of this License in the various documents with a single copy 5042 that is included in the collection, provided that you follow the 5043 rules of this License for verbatim copying of each of the documents 5044 in all other respects. 5045 5046 You may extract a single document from such a collection, and 5047 distribute it individually under this License, provided you insert 5048 a copy of this License into the extracted document, and follow this 5049 License in all other respects regarding verbatim copying of that 5050 document. 5051 5052 7. AGGREGATION WITH INDEPENDENT WORKS 5053 5054 A compilation of the Document or its derivatives with other 5055 separate and independent documents or works, in or on a volume of a 5056 storage or distribution medium, is called an "aggregate" if the 5057 copyright resulting from the compilation is not used to limit the 5058 legal rights of the compilation's users beyond what the individual 5059 works permit. When the Document is included in an aggregate, this 5060 License does not apply to the other works in the aggregate which 5061 are not themselves derivative works of the Document. 5062 5063 If the Cover Text requirement of section 3 is applicable to these 5064 copies of the Document, then if the Document is less than one half 5065 of the entire aggregate, the Document's Cover Texts may be placed 5066 on covers that bracket the Document within the aggregate, or the 5067 electronic equivalent of covers if the Document is in electronic 5068 form. Otherwise they must appear on printed covers that bracket 5069 the whole aggregate. 5070 5071 8. TRANSLATION 5072 5073 Translation is considered a kind of modification, so you may 5074 distribute translations of the Document under the terms of section 5075 4. Replacing Invariant Sections with translations requires special 5076 permission from their copyright holders, but you may include 5077 translations of some or all Invariant Sections in addition to the 5078 original versions of these Invariant Sections. You may include a 5079 translation of this License, and all the license notices in the 5080 Document, and any Warranty Disclaimers, provided that you also 5081 include the original English version of this License and the 5082 original versions of those notices and disclaimers. In case of a 5083 disagreement between the translation and the original version of 5084 this License or a notice or disclaimer, the original version will 5085 prevail. 5086 5087 If a section in the Document is Entitled "Acknowledgements", 5088 "Dedications", or "History", the requirement (section 4) to 5089 Preserve its Title (section 1) will typically require changing the 5090 actual title. 5091 5092 9. TERMINATION 5093 5094 You may not copy, modify, sublicense, or distribute the Document 5095 except as expressly provided under this License. Any attempt 5096 otherwise to copy, modify, sublicense, or distribute it is void, 5097 and will automatically terminate your rights under this License. 5098 5099 However, if you cease all violation of this License, then your 5100 license from a particular copyright holder is reinstated (a) 5101 provisionally, unless and until the copyright holder explicitly and 5102 finally terminates your license, and (b) permanently, if the 5103 copyright holder fails to notify you of the violation by some 5104 reasonable means prior to 60 days after the cessation. 5105 5106 Moreover, your license from a particular copyright holder is 5107 reinstated permanently if the copyright holder notifies you of the 5108 violation by some reasonable means, this is the first time you have 5109 received notice of violation of this License (for any work) from 5110 that copyright holder, and you cure the violation prior to 30 days 5111 after your receipt of the notice. 5112 5113 Termination of your rights under this section does not terminate 5114 the licenses of parties who have received copies or rights from you 5115 under this License. If your rights have been terminated and not 5116 permanently reinstated, receipt of a copy of some or all of the 5117 same material does not give you any rights to use it. 5118 5119 10. FUTURE REVISIONS OF THIS LICENSE 5120 5121 The Free Software Foundation may publish new, revised versions of 5122 the GNU Free Documentation License from time to time. Such new 5123 versions will be similar in spirit to the present version, but may 5124 differ in detail to address new problems or concerns. See 5125 <http://www.gnu.org/copyleft/>. 5126 5127 Each version of the License is given a distinguishing version 5128 number. If the Document specifies that a particular numbered 5129 version of this License "or any later version" applies to it, you 5130 have the option of following the terms and conditions either of 5131 that specified version or of any later version that has been 5132 published (not as a draft) by the Free Software Foundation. If the 5133 Document does not specify a version number of this License, you may 5134 choose any version ever published (not as a draft) by the Free 5135 Software Foundation. If the Document specifies that a proxy can 5136 decide which future versions of this License can be used, that 5137 proxy's public statement of acceptance of a version permanently 5138 authorizes you to choose that version for the Document. 5139 5140 11. RELICENSING 5141 5142 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any 5143 World Wide Web server that publishes copyrightable works and also 5144 provides prominent facilities for anybody to edit those works. A 5145 public wiki that anybody can edit is an example of such a server. 5146 A "Massive Multiauthor Collaboration" (or "MMC") contained in the 5147 site means any set of copyrightable works thus published on the MMC 5148 site. 5149 5150 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 5151 license published by Creative Commons Corporation, a not-for-profit 5152 corporation with a principal place of business in San Francisco, 5153 California, as well as future copyleft versions of that license 5154 published by that same organization. 5155 5156 "Incorporate" means to publish or republish a Document, in whole or 5157 in part, as part of another Document. 5158 5159 An MMC is "eligible for relicensing" if it is licensed under this 5160 License, and if all works that were first published under this 5161 License somewhere other than this MMC, and subsequently 5162 incorporated in whole or in part into the MMC, (1) had no cover 5163 texts or invariant sections, and (2) were thus incorporated prior 5164 to November 1, 2008. 5165 5166 The operator of an MMC Site may republish an MMC contained in the 5167 site under CC-BY-SA on the same site at any time before August 1, 5168 2009, provided the MMC is eligible for relicensing. 5169 5170ADDENDUM: How to use this License for your documents 5171==================================================== 5172 5173To use this License in a document you have written, include a copy of 5174the License in the document and put the following copyright and license 5175notices just after the title page: 5176 5177 Copyright (C) YEAR YOUR NAME. 5178 Permission is granted to copy, distribute and/or modify this document 5179 under the terms of the GNU Free Documentation License, Version 1.3 5180 or any later version published by the Free Software Foundation; 5181 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 5182 Texts. A copy of the license is included in the section entitled ``GNU 5183 Free Documentation License''. 5184 5185 If you have Invariant Sections, Front-Cover Texts and Back-Cover 5186Texts, replace the "with...Texts." line with this: 5187 5188 with the Invariant Sections being LIST THEIR TITLES, with 5189 the Front-Cover Texts being LIST, and with the Back-Cover Texts 5190 being LIST. 5191 5192 If you have Invariant Sections without Cover Texts, or some other 5193combination of the three, merge those two alternatives to suit the 5194situation. 5195 5196 If your document contains nontrivial examples of program code, we 5197recommend releasing these examples in parallel under your choice of free 5198software license, such as the GNU General Public License, to permit 5199their use in free software. 5200 5201 5202File: cpp.info, Node: Index of Directives, Next: Option Index, Prev: GNU Free Documentation License, Up: Top 5203 5204Index of Directives 5205******************* 5206 5207[index] 5208* Menu: 5209 5210* #assert: Obsolete Features. (line 48) 5211* #define: Object-like Macros. (line 11) 5212* #elif: Elif. (line 6) 5213* #else: Else. (line 6) 5214* #endif: Ifdef. (line 6) 5215* #error: Diagnostics. (line 6) 5216* #ident: Other Directives. (line 6) 5217* #if: Conditional Syntax. (line 6) 5218* #ifdef: Ifdef. (line 6) 5219* #ifndef: Ifdef. (line 40) 5220* #import: Alternatives to Wrapper #ifndef. 5221 (line 11) 5222* #include: Include Syntax. (line 6) 5223* #include_next: Wrapper Headers. (line 6) 5224* #line: Line Control. (line 20) 5225* #pragma GCC dependency: Pragmas. (line 43) 5226* #pragma GCC error: Pragmas. (line 88) 5227* #pragma GCC poison: Pragmas. (line 55) 5228* #pragma GCC system_header: System Headers. (line 25) 5229* #pragma GCC system_header <1>: Pragmas. (line 82) 5230* #pragma GCC warning: Pragmas. (line 87) 5231* #pragma once: Pragmas. (line 96) 5232* #sccs: Other Directives. (line 6) 5233* #unassert: Obsolete Features. (line 59) 5234* #undef: Undefining and Redefining Macros. 5235 (line 6) 5236* #warning: Diagnostics. (line 27) 5237 5238 5239File: cpp.info, Node: Option Index, Next: Concept Index, Prev: Index of Directives, Up: Top 5240 5241Option Index 5242************ 5243 5244CPP's command-line options and environment variables are indexed here 5245without any initial '-' or '--'. 5246 5247[index] 5248* Menu: 5249 5250* A: Invocation. (line 335) 5251* C: Invocation. (line 344) 5252* CC: Invocation. (line 356) 5253* CPATH: Environment Variables. 5254 (line 15) 5255* CPLUS_INCLUDE_PATH: Environment Variables. 5256 (line 17) 5257* C_INCLUDE_PATH: Environment Variables. 5258 (line 16) 5259* D: Invocation. (line 44) 5260* d: Invocation. (line 405) 5261* dD: Invocation. (line 424) 5262* DEPENDENCIES_OUTPUT: Environment Variables. 5263 (line 45) 5264* dI: Invocation. (line 434) 5265* dM: Invocation. (line 413) 5266* dN: Invocation. (line 430) 5267* dU: Invocation. (line 438) 5268* fdebug-cpp: Invocation. (line 445) 5269* fdirectives-only: Invocation. (line 228) 5270* fdollars-in-identifiers: Invocation. (line 249) 5271* fexec-charset: Invocation. (line 296) 5272* fextended-identifiers: Invocation. (line 252) 5273* finput-charset: Invocation. (line 311) 5274* fmacro-prefix-map: Invocation. (line 287) 5275* fmax-include-depth: Invocation. (line 261) 5276* fno-canonical-system-headers: Invocation. (line 257) 5277* fno-working-directory: Invocation. (line 321) 5278* fpreprocessed: Invocation. (line 215) 5279* ftabstop: Invocation. (line 264) 5280* ftrack-macro-expansion: Invocation. (line 270) 5281* fwide-exec-charset: Invocation. (line 301) 5282* fworking-directory: Invocation. (line 321) 5283* H: Invocation. (line 398) 5284* I: Invocation. (line 456) 5285* I-: Invocation. (line 510) 5286* idirafter: Invocation. (line 456) 5287* imacros: Invocation. (line 82) 5288* imultilib: Invocation. (line 544) 5289* include: Invocation. (line 71) 5290* iprefix: Invocation. (line 526) 5291* iquote: Invocation. (line 456) 5292* isysroot: Invocation. (line 538) 5293* isystem: Invocation. (line 456) 5294* iwithprefix: Invocation. (line 532) 5295* iwithprefixbefore: Invocation. (line 532) 5296* M: Invocation. (line 103) 5297* MD: Invocation. (line 195) 5298* MF: Invocation. (line 137) 5299* MG: Invocation. (line 148) 5300* MM: Invocation. (line 128) 5301* MMD: Invocation. (line 211) 5302* MP: Invocation. (line 158) 5303* MQ: Invocation. (line 185) 5304* MT: Invocation. (line 170) 5305* nostdinc: Invocation. (line 548) 5306* nostdinc++: Invocation. (line 554) 5307* OBJC_INCLUDE_PATH: Environment Variables. 5308 (line 18) 5309* P: Invocation. (line 368) 5310* pthread: Invocation. (line 96) 5311* remap: Invocation. (line 394) 5312* SOURCE_DATE_EPOCH: Environment Variables. 5313 (line 67) 5314* SUNPRO_DEPENDENCIES: Environment Variables. 5315 (line 61) 5316* traditional: Invocation. (line 376) 5317* traditional-cpp: Invocation. (line 376) 5318* trigraphs: Invocation. (line 385) 5319* U: Invocation. (line 67) 5320* undef: Invocation. (line 91) 5321* Wcomment: Invocation. (line 560) 5322* Wcomments: Invocation. (line 560) 5323* Wendif-labels: Invocation. (line 604) 5324* Wexpansion-to-defined: Invocation. (line 579) 5325* Wno-endif-labels: Invocation. (line 604) 5326* Wno-undef: Invocation. (line 575) 5327* Wtrigraphs: Invocation. (line 565) 5328* Wundef: Invocation. (line 575) 5329* Wunused-macros: Invocation. (line 585) 5330 5331 5332File: cpp.info, Node: Concept Index, Prev: Option Index, Up: Top 5333 5334Concept Index 5335************* 5336 5337[index] 5338* Menu: 5339 5340* # operator: Stringizing. (line 6) 5341* ## operator: Concatenation. (line 6) 5342* _Pragma: Pragmas. (line 13) 5343* __has_attribute: __has_attribute. (line 6) 5344* __has_builtin: __has_builtin. (line 6) 5345* __has_cpp_attribute: __has_cpp_attribute. (line 6) 5346* __has_include: __has_include. (line 6) 5347* alternative tokens: Tokenization. (line 100) 5348* arguments: Macro Arguments. (line 6) 5349* arguments in macro definitions: Macro Arguments. (line 6) 5350* assertions: Obsolete Features. (line 13) 5351* assertions, canceling: Obsolete Features. (line 59) 5352* backslash-newline: Initial processing. (line 61) 5353* block comments: Initial processing. (line 77) 5354* C language, traditional: Invocation. (line 374) 5355* C++ named operators: C++ Named Operators. (line 6) 5356* character constants: Tokenization. (line 81) 5357* character set, execution: Invocation. (line 296) 5358* character set, input: Invocation. (line 311) 5359* character set, wide execution: Invocation. (line 301) 5360* command line: Invocation. (line 6) 5361* commenting out code: Deleted Code. (line 6) 5362* comments: Initial processing. (line 77) 5363* common predefined macros: Common Predefined Macros. 5364 (line 6) 5365* computed includes: Computed Includes. (line 6) 5366* concatenation: Concatenation. (line 6) 5367* conditional group: Ifdef. (line 14) 5368* conditionals: Conditionals. (line 6) 5369* continued lines: Initial processing. (line 61) 5370* controlling macro: Once-Only Headers. (line 35) 5371* defined: Defined. (line 6) 5372* dependencies for make as output: Environment Variables. 5373 (line 46) 5374* dependencies for make as output <1>: Environment Variables. 5375 (line 62) 5376* dependencies, make: Invocation. (line 103) 5377* diagnostic: Diagnostics. (line 6) 5378* digraphs: Tokenization. (line 100) 5379* directive line: The preprocessing language. 5380 (line 6) 5381* directive name: The preprocessing language. 5382 (line 6) 5383* directives: The preprocessing language. 5384 (line 6) 5385* empty macro arguments: Macro Arguments. (line 66) 5386* environment variables: Environment Variables. 5387 (line 6) 5388* expansion of arguments: Argument Prescan. (line 6) 5389* FDL, GNU Free Documentation License: GNU Free Documentation License. 5390 (line 6) 5391* function-like macros: Function-like Macros. 5392 (line 6) 5393* grouping options: Invocation. (line 38) 5394* guard macro: Once-Only Headers. (line 35) 5395* header file: Header Files. (line 6) 5396* header file names: Tokenization. (line 81) 5397* identifiers: Tokenization. (line 33) 5398* implementation limits: Implementation limits. 5399 (line 6) 5400* implementation-defined behavior: Implementation-defined behavior. 5401 (line 6) 5402* including just once: Once-Only Headers. (line 6) 5403* invocation: Invocation. (line 6) 5404* iso646.h: C++ Named Operators. (line 6) 5405* line comments: Initial processing. (line 77) 5406* line control: Line Control. (line 6) 5407* line endings: Initial processing. (line 14) 5408* linemarkers: Preprocessor Output. (line 27) 5409* macro argument expansion: Argument Prescan. (line 6) 5410* macro arguments and directives: Directives Within Macro Arguments. 5411 (line 6) 5412* macros in include: Computed Includes. (line 6) 5413* macros with arguments: Macro Arguments. (line 6) 5414* macros with variable arguments: Variadic Macros. (line 6) 5415* make: Invocation. (line 103) 5416* manifest constants: Object-like Macros. (line 6) 5417* named operators: C++ Named Operators. (line 6) 5418* newlines in macro arguments: Newlines in Arguments. 5419 (line 6) 5420* null directive: Other Directives. (line 15) 5421* numbers: Tokenization. (line 58) 5422* object-like macro: Object-like Macros. (line 6) 5423* options: Invocation. (line 43) 5424* options, grouping: Invocation. (line 38) 5425* other tokens: Tokenization. (line 114) 5426* output format: Preprocessor Output. (line 12) 5427* overriding a header file: Wrapper Headers. (line 6) 5428* parentheses in macro bodies: Operator Precedence Problems. 5429 (line 6) 5430* pitfalls of macros: Macro Pitfalls. (line 6) 5431* pragma directive: Pragmas. (line 6) 5432* predefined macros: Predefined Macros. (line 6) 5433* predefined macros, system-specific: System-specific Predefined Macros. 5434 (line 6) 5435* predicates: Obsolete Features. (line 26) 5436* preprocessing directives: The preprocessing language. 5437 (line 6) 5438* preprocessing numbers: Tokenization. (line 58) 5439* preprocessing tokens: Tokenization. (line 6) 5440* prescan of macro arguments: Argument Prescan. (line 6) 5441* problems with macros: Macro Pitfalls. (line 6) 5442* punctuators: Tokenization. (line 100) 5443* redefining macros: Undefining and Redefining Macros. 5444 (line 6) 5445* repeated inclusion: Once-Only Headers. (line 6) 5446* reporting errors: Diagnostics. (line 6) 5447* reporting warnings: Diagnostics. (line 6) 5448* reserved namespace: System-specific Predefined Macros. 5449 (line 6) 5450* self-reference: Self-Referential Macros. 5451 (line 6) 5452* semicolons (after macro calls): Swallowing the Semicolon. 5453 (line 6) 5454* side effects (in macro arguments): Duplication of Side Effects. 5455 (line 6) 5456* standard predefined macros.: Standard Predefined Macros. 5457 (line 6) 5458* string constants: Tokenization. (line 81) 5459* string literals: Tokenization. (line 81) 5460* stringizing: Stringizing. (line 6) 5461* symbolic constants: Object-like Macros. (line 6) 5462* system header files: Header Files. (line 13) 5463* system header files <1>: System Headers. (line 6) 5464* system-specific predefined macros: System-specific Predefined Macros. 5465 (line 6) 5466* testing predicates: Obsolete Features. (line 37) 5467* token concatenation: Concatenation. (line 6) 5468* token pasting: Concatenation. (line 6) 5469* tokens: Tokenization. (line 6) 5470* traditional C language: Invocation. (line 374) 5471* trigraphs: Initial processing. (line 32) 5472* undefining macros: Undefining and Redefining Macros. 5473 (line 6) 5474* unsafe macros: Duplication of Side Effects. 5475 (line 6) 5476* variable number of arguments: Variadic Macros. (line 6) 5477* variadic macros: Variadic Macros. (line 6) 5478* wrapper #ifndef: Once-Only Headers. (line 6) 5479* wrapper headers: Wrapper Headers. (line 6) 5480 5481 5482 5483Tag Table: 5484Node: Top945 5485Node: Overview3506 5486Node: Character sets6344 5487Ref: Character sets-Footnote-18516 5488Node: Initial processing8697 5489Ref: trigraphs10256 5490Node: Tokenization14456 5491Ref: Tokenization-Footnote-121286 5492Node: The preprocessing language21397 5493Node: Header Files24276 5494Node: Include Syntax26192 5495Node: Include Operation27829 5496Node: Search Path29677 5497Node: Once-Only Headers31899 5498Node: Alternatives to Wrapper #ifndef33558 5499Node: Computed Includes35207 5500Node: Wrapper Headers38365 5501Node: System Headers40788 5502Node: Macros42389 5503Node: Object-like Macros43526 5504Node: Function-like Macros47116 5505Node: Macro Arguments48732 5506Node: Stringizing52871 5507Node: Concatenation56032 5508Node: Variadic Macros59129 5509Node: Predefined Macros64081 5510Node: Standard Predefined Macros64669 5511Node: Common Predefined Macros71001 5512Node: System-specific Predefined Macros92241 5513Node: C++ Named Operators94264 5514Node: Undefining and Redefining Macros95228 5515Node: Directives Within Macro Arguments97326 5516Node: Macro Pitfalls98267 5517Node: Misnesting98800 5518Node: Operator Precedence Problems99912 5519Node: Swallowing the Semicolon101778 5520Node: Duplication of Side Effects103801 5521Node: Self-Referential Macros105984 5522Node: Argument Prescan108393 5523Node: Newlines in Arguments112144 5524Node: Conditionals113095 5525Node: Conditional Uses114791 5526Node: Conditional Syntax116149 5527Node: Ifdef116549 5528Node: If119706 5529Node: Defined122010 5530Node: Else123403 5531Node: Elif123973 5532Node: __has_attribute125286 5533Node: __has_cpp_attribute126820 5534Node: __has_builtin127706 5535Node: __has_include128841 5536Node: Deleted Code130428 5537Node: Diagnostics131675 5538Node: Line Control133224 5539Node: Pragmas135502 5540Node: Other Directives139899 5541Node: Preprocessor Output140949 5542Node: Traditional Mode144102 5543Node: Traditional lexical analysis145239 5544Node: Traditional macros147742 5545Node: Traditional miscellany151539 5546Node: Traditional warnings152535 5547Node: Implementation Details154732 5548Node: Implementation-defined behavior155295 5549Ref: Identifier characters156045 5550Node: Implementation limits159093 5551Node: Obsolete Features161766 5552Node: Invocation164610 5553Ref: dashMF170645 5554Ref: fdollars-in-identifiers175224 5555Ref: Wtrigraphs189470 5556Node: Environment Variables191525 5557Node: GNU Free Documentation License195218 5558Node: Index of Directives220363 5559Node: Option Index222516 5560Node: Concept Index228545 5561 5562End Tag Table 5563