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