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