190075Sobrien\input texinfo 290075Sobrien@setfilename cpp.info 390075Sobrien@settitle The C Preprocessor 490075Sobrien@setchapternewpage off 590075Sobrien@c @smallbook 690075Sobrien@c @cropmarks 790075Sobrien@c @finalout 890075Sobrien 9169689Skan@include gcc-common.texi 10169689Skan 11117395Skan@copying 1290075Sobrien@c man begin COPYRIGHT 1390075SobrienCopyright @copyright{} 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 14169689Skan1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 1590075SobrienFree Software Foundation, Inc. 1690075Sobrien 1790075SobrienPermission is granted to copy, distribute and/or modify this document 1890075Sobrienunder the terms of the GNU Free Documentation License, Version 1.1 or 1990075Sobrienany later version published by the Free Software Foundation. A copy of 2090075Sobrienthe license is included in the 2190075Sobrien@c man end 2290075Sobriensection entitled ``GNU Free Documentation License''. 2390075Sobrien@ignore 2490075Sobrien@c man begin COPYRIGHT 2590075Sobrienman page gfdl(7). 2690075Sobrien@c man end 2790075Sobrien@end ignore 2890075Sobrien 2990075Sobrien@c man begin COPYRIGHT 3090075SobrienThis manual contains no Invariant Sections. The Front-Cover Texts are 3190075Sobrien(a) (see below), and the Back-Cover Texts are (b) (see below). 3290075Sobrien 3390075Sobrien(a) The FSF's Front-Cover Text is: 3490075Sobrien 3590075Sobrien A GNU Manual 3690075Sobrien 3790075Sobrien(b) The FSF's Back-Cover Text is: 3890075Sobrien 3990075Sobrien You have freedom to copy and modify this GNU Manual, like GNU 4090075Sobrien software. Copies published by the Free Software Foundation raise 4190075Sobrien funds for GNU development. 4290075Sobrien@c man end 43117395Skan@end copying 4490075Sobrien 4596263Sobrien@c Create a separate index for command line options. 4696263Sobrien@defcodeindex op 47117395Skan@syncodeindex vr op 4896263Sobrien 4996263Sobrien@c Used in cppopts.texi and cppenv.texi. 5096263Sobrien@set cppmanual 5196263Sobrien 5290075Sobrien@ifinfo 53169689Skan@dircategory Software development 5490075Sobrien@direntry 5590075Sobrien* Cpp: (cpp). The GNU C preprocessor. 5690075Sobrien@end direntry 5790075Sobrien@end ifinfo 5890075Sobrien 5990075Sobrien@titlepage 6090075Sobrien@title The C Preprocessor 61169689Skan@versionsubtitle 62169689Skan@author Richard M. Stallman, Zachary Weinberg 6390075Sobrien@page 6490075Sobrien@c There is a fill at the bottom of the page, so we need a filll to 6590075Sobrien@c override it. 6690075Sobrien@vskip 0pt plus 1filll 67117395Skan@insertcopying 6890075Sobrien@end titlepage 6990075Sobrien@contents 7090075Sobrien@page 7190075Sobrien 72117395Skan@ifnottex 7390075Sobrien@node Top 7490075Sobrien@top 75220755SdimThe C preprocessor implements the macro language used to transform C 76220755Sdimand C++ programs before they are compiled. It can also be useful on 77220755Sdimits own. 7890075Sobrien 7990075Sobrien@menu 8090075Sobrien* Overview:: 8190075Sobrien* Header Files:: 8290075Sobrien* Macros:: 8390075Sobrien* Conditionals:: 8490075Sobrien* Diagnostics:: 8590075Sobrien* Line Control:: 8690075Sobrien* Pragmas:: 8790075Sobrien* Other Directives:: 8890075Sobrien* Preprocessor Output:: 8990075Sobrien* Traditional Mode:: 9090075Sobrien* Implementation Details:: 9190075Sobrien* Invocation:: 9296263Sobrien* Environment Variables:: 9390075Sobrien* GNU Free Documentation License:: 94117395Skan* Index of Directives:: 9596263Sobrien* Option Index:: 9690075Sobrien* Concept Index:: 9790075Sobrien 9890075Sobrien@detailmenu 9990075Sobrien --- The Detailed Node Listing --- 10090075Sobrien 10190075SobrienOverview 10290075Sobrien 103132718Skan* Character sets:: 10490075Sobrien* Initial processing:: 10590075Sobrien* Tokenization:: 10690075Sobrien* The preprocessing language:: 10790075Sobrien 10890075SobrienHeader Files 10990075Sobrien 11090075Sobrien* Include Syntax:: 11190075Sobrien* Include Operation:: 11290075Sobrien* Search Path:: 11390075Sobrien* Once-Only Headers:: 11490075Sobrien* Computed Includes:: 11590075Sobrien* Wrapper Headers:: 11690075Sobrien* System Headers:: 11790075Sobrien 11890075SobrienMacros 11990075Sobrien 12090075Sobrien* Object-like Macros:: 12190075Sobrien* Function-like Macros:: 12290075Sobrien* Macro Arguments:: 12390075Sobrien* Stringification:: 12490075Sobrien* Concatenation:: 12590075Sobrien* Variadic Macros:: 12690075Sobrien* Predefined Macros:: 12790075Sobrien* Undefining and Redefining Macros:: 128117395Skan* Directives Within Macro Arguments:: 12990075Sobrien* Macro Pitfalls:: 13090075Sobrien 13190075SobrienPredefined Macros 13290075Sobrien 13390075Sobrien* Standard Predefined Macros:: 13490075Sobrien* Common Predefined Macros:: 13590075Sobrien* System-specific Predefined Macros:: 13690075Sobrien* C++ Named Operators:: 13790075Sobrien 13890075SobrienMacro Pitfalls 13990075Sobrien 14090075Sobrien* Misnesting:: 14190075Sobrien* Operator Precedence Problems:: 14290075Sobrien* Swallowing the Semicolon:: 14390075Sobrien* Duplication of Side Effects:: 14490075Sobrien* Self-Referential Macros:: 14590075Sobrien* Argument Prescan:: 14690075Sobrien* Newlines in Arguments:: 14790075Sobrien 14890075SobrienConditionals 14990075Sobrien 15090075Sobrien* Conditional Uses:: 15190075Sobrien* Conditional Syntax:: 15290075Sobrien* Deleted Code:: 15390075Sobrien 15490075SobrienConditional Syntax 15590075Sobrien 15690075Sobrien* Ifdef:: 15790075Sobrien* If:: 15890075Sobrien* Defined:: 15990075Sobrien* Else:: 16090075Sobrien* Elif:: 16190075Sobrien 16290075SobrienImplementation Details 16390075Sobrien 16490075Sobrien* Implementation-defined behavior:: 16590075Sobrien* Implementation limits:: 16690075Sobrien* Obsolete Features:: 16790075Sobrien* Differences from previous versions:: 16890075Sobrien 16990075SobrienObsolete Features 17090075Sobrien 17190075Sobrien* Assertions:: 17290075Sobrien* Obsolete once-only headers:: 17390075Sobrien 17490075Sobrien@end detailmenu 17590075Sobrien@end menu 17690075Sobrien 177117395Skan@insertcopying 17890075Sobrien@end ifnottex 17990075Sobrien 18090075Sobrien@node Overview 18190075Sobrien@chapter Overview 18290075Sobrien@c man begin DESCRIPTION 18390075SobrienThe C preprocessor, often known as @dfn{cpp}, is a @dfn{macro processor} 18490075Sobrienthat is used automatically by the C compiler to transform your program 18590075Sobrienbefore compilation. It is called a macro processor because it allows 18690075Sobrienyou to define @dfn{macros}, which are brief abbreviations for longer 18790075Sobrienconstructs. 18890075Sobrien 189220755SdimThe C preprocessor is intended to be used only with C and C++ source 190220755Sdimcode. In the past, it has been abused as a general text processor. It 191220755Sdimwill choke on input which does not obey C's lexical rules. For 192220755Sdimexample, apostrophes will be interpreted as the beginning of character 193220755Sdimconstants, and cause errors. Also, you cannot rely on it preserving 194220755Sdimcharacteristics of the input which are not significant to C-family 195220755Sdimlanguages. If a Makefile is preprocessed, all the hard tabs will be 196220755Sdimremoved, and the Makefile will not work. 19790075Sobrien 19890075SobrienHaving said that, you can often get away with using cpp on things which 19990075Sobrienare not C@. Other Algol-ish programming languages are often safe 200117395Skan(Pascal, Ada, etc.) So is assembly, with caution. @option{-traditional-cpp} 20190075Sobrienmode preserves more white space, and is otherwise more permissive. Many 20290075Sobrienof the problems can be avoided by writing C or C++ style comments 20390075Sobrieninstead of native language comments, and keeping macros simple. 20490075Sobrien 20590075SobrienWherever possible, you should use a preprocessor geared to the language 20690075Sobrienyou are writing in. Modern versions of the GNU assembler have macro 20790075Sobrienfacilities. Most high level programming languages have their own 20890075Sobrienconditional compilation and inclusion mechanism. If all else fails, 20990075Sobrientry a true general text processor, such as GNU M4. 21090075Sobrien 21190075SobrienC preprocessors vary in some details. This manual discusses the GNU C 21290075Sobrienpreprocessor, which provides a small superset of the features of ISO 21390075SobrienStandard C@. In its default mode, the GNU C preprocessor does not do a 21490075Sobrienfew things required by the standard. These are features which are 21590075Sobrienrarely, if ever, used, and may cause surprising changes to the meaning 21690075Sobrienof a program which does not expect them. To get strict ISO Standard C, 21790075Sobrienyou should use the @option{-std=c89} or @option{-std=c99} options, depending 21890075Sobrienon which version of the standard you want. To get all the mandatory 21990075Sobriendiagnostics, you must also use @option{-pedantic}. @xref{Invocation}. 220117395Skan 221117395SkanThis manual describes the behavior of the ISO preprocessor. To 222117395Skanminimize gratuitous differences, where the ISO preprocessor's 223117395Skanbehavior does not conflict with traditional semantics, the 224117395Skantraditional preprocessor should behave the same way. The various 225117395Skandifferences that do exist are detailed in the section @ref{Traditional 226117395SkanMode}. 227117395Skan 228117395SkanFor clarity, unless noted otherwise, references to @samp{CPP} in this 229169689Skanmanual refer to GNU CPP@. 23090075Sobrien@c man end 23190075Sobrien 23290075Sobrien@menu 233132718Skan* Character sets:: 23490075Sobrien* Initial processing:: 23590075Sobrien* Tokenization:: 23690075Sobrien* The preprocessing language:: 23790075Sobrien@end menu 23890075Sobrien 239132718Skan@node Character sets 240132718Skan@section Character sets 241132718Skan 242132718SkanSource code character set processing in C and related languages is 243132718Skanrather complicated. The C standard discusses two character sets, but 244132718Skanthere are really at least four. 245132718Skan 246132718SkanThe files input to CPP might be in any character set at all. CPP's 247132718Skanvery first action, before it even looks for line boundaries, is to 248132718Skanconvert the file into the character set it uses for internal 249132718Skanprocessing. That set is what the C standard calls the @dfn{source} 250132718Skancharacter set. It must be isomorphic with ISO 10646, also known as 251132718SkanUnicode. CPP uses the UTF-8 encoding of Unicode. 252132718Skan 253169689SkanThe character sets of the input files are specified using the 254169689Skan@option{-finput-charset=} option. 255132718Skan 256132718SkanAll preprocessing work (the subject of the rest of this manual) is 257132718Skancarried out in the source character set. If you request textual 258132718Skanoutput from the preprocessor with the @option{-E} option, it will be 259132718Skanin UTF-8. 260132718Skan 261132718SkanAfter preprocessing is complete, string and character constants are 262132718Skanconverted again, into the @dfn{execution} character set. This 263132718Skancharacter set is under control of the user; the default is UTF-8, 264132718Skanmatching the source character set. Wide string and character 265132718Skanconstants have their own character set, which is not called out 266132718Skanspecifically in the standard. Again, it is under control of the user. 267132718SkanThe default is UTF-16 or UTF-32, whichever fits in the target's 268132718Skan@code{wchar_t} type, in the target machine's byte 269132718Skanorder.@footnote{UTF-16 does not meet the requirements of the C 270132718Skanstandard for a wide character set, but the choice of 16-bit 271132718Skan@code{wchar_t} is enshrined in some system ABIs so we cannot fix 272132718Skanthis.} Octal and hexadecimal escape sequences do not undergo 273132718Skanconversion; @t{'\x12'} has the value 0x12 regardless of the currently 274132718Skanselected execution character set. All other escapes are replaced by 275132718Skanthe character in the source character set that they represent, then 276132718Skanconverted to the execution character set, just like unescaped 277132718Skancharacters. 278132718Skan 279169689SkanUnless the experimental @option{-fextended-identifiers} option is used, 280132718SkanGCC does not permit the use of characters outside the ASCII range, nor 281169689Skan@samp{\u} and @samp{\U} escapes, in identifiers. Even with that 282169689Skanoption, characters outside the ASCII range can only be specified with 283169689Skanthe @samp{\u} and @samp{\U} escapes, not used directly in identifiers. 284132718Skan 28590075Sobrien@node Initial processing 28690075Sobrien@section Initial processing 28790075Sobrien 28890075SobrienThe preprocessor performs a series of textual transformations on its 28990075Sobrieninput. These happen before all other processing. Conceptually, they 29090075Sobrienhappen in a rigid order, and the entire file is run through each 291117395Skantransformation before the next one begins. CPP actually does them 29290075Sobrienall at once, for performance reasons. These transformations correspond 29390075Sobrienroughly to the first three ``phases of translation'' described in the C 29490075Sobrienstandard. 29590075Sobrien 29690075Sobrien@enumerate 29790075Sobrien@item 29890075Sobrien@cindex line endings 29990075SobrienThe input file is read into memory and broken into lines. 30090075Sobrien 30190075SobrienDifferent systems use different conventions to indicate the end of a 30290075Sobrienline. GCC accepts the ASCII control sequences @kbd{LF}, @kbd{@w{CR 303132718SkanLF}} and @kbd{CR} as end-of-line markers. These are the canonical 304132718Skansequences used by Unix, DOS and VMS, and the classic Mac OS (before 305132718SkanOSX) respectively. You may therefore safely copy source code written 306132718Skanon any of those systems to a different one and use it without 307132718Skanconversion. (GCC may lose track of the current line number if a file 308132718Skandoesn't consistently use one convention, as sometimes happens when it 309132718Skanis edited on computers with different conventions that share a network 310132718Skanfile system.) 31190075Sobrien 31290075SobrienIf the last line of any input file lacks an end-of-line marker, the end 31390075Sobrienof the file is considered to implicitly supply one. The C standard says 31490075Sobrienthat this condition provokes undefined behavior, so GCC will emit a 31590075Sobrienwarning message. 31690075Sobrien 31790075Sobrien@item 31890075Sobrien@cindex trigraphs 319117395Skan@anchor{trigraphs}If trigraphs are enabled, they are replaced by their 320117395Skancorresponding single characters. By default GCC ignores trigraphs, 321117395Skanbut if you request a strictly conforming mode with the @option{-std} 322117395Skanoption, or you specify the @option{-trigraphs} option, then it 323117395Skanconverts them. 32490075Sobrien 32590075SobrienThese are nine three-character sequences, all starting with @samp{??}, 32690075Sobrienthat are defined by ISO C to stand for single characters. They permit 32790075Sobrienobsolete systems that lack some of C's punctuation to use C@. For 32890075Sobrienexample, @samp{??/} stands for @samp{\}, so @t{'??/n'} is a character 329117395Skanconstant for a newline. 33090075Sobrien 331132718SkanTrigraphs are not popular and many compilers implement them 332132718Skanincorrectly. Portable code should not rely on trigraphs being either 333132718Skanconverted or ignored. With @option{-Wtrigraphs} GCC will warn you 334132718Skanwhen a trigraph may change the meaning of your program if it were 335132718Skanconverted. @xref{Wtrigraphs}. 33690075Sobrien 337132718SkanIn a string constant, you can prevent a sequence of question marks 338132718Skanfrom being confused with a trigraph by inserting a backslash between 339132718Skanthe question marks, or by separating the string literal at the 340132718Skantrigraph and making use of string literal concatenation. @t{"(??\?)"} 341132718Skanis the string @samp{(???)}, not @samp{(?]}. Traditional C compilers 342132718Skando not recognize these idioms. 34390075Sobrien 34490075SobrienThe nine trigraphs and their replacements are 34590075Sobrien 346132718Skan@smallexample 34790075SobrienTrigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??- 34890075SobrienReplacement: [ ] @{ @} # \ ^ | ~ 349132718Skan@end smallexample 35090075Sobrien 35190075Sobrien@item 35290075Sobrien@cindex continued lines 35390075Sobrien@cindex backslash-newline 35490075SobrienContinued lines are merged into one long line. 35590075Sobrien 35690075SobrienA continued line is a line which ends with a backslash, @samp{\}. The 35790075Sobrienbackslash is removed and the following line is joined with the current 35890075Sobrienone. No space is inserted, so you may split a line anywhere, even in 35990075Sobrienthe middle of a word. (It is generally more readable to split lines 36090075Sobrienonly at white space.) 36190075Sobrien 36290075SobrienThe trailing backslash on a continued line is commonly referred to as a 36390075Sobrien@dfn{backslash-newline}. 36490075Sobrien 36590075SobrienIf there is white space between a backslash and the end of a line, that 36690075Sobrienis still a continued line. However, as this is usually the result of an 36790075Sobrienediting mistake, and many compilers will not accept it as a continued 36890075Sobrienline, GCC will warn you about it. 36990075Sobrien 37090075Sobrien@item 37190075Sobrien@cindex comments 37290075Sobrien@cindex line comments 37390075Sobrien@cindex block comments 37490075SobrienAll comments are replaced with single spaces. 37590075Sobrien 37690075SobrienThere are two kinds of comments. @dfn{Block comments} begin with 37790075Sobrien@samp{/*} and continue until the next @samp{*/}. Block comments do not 37890075Sobriennest: 37990075Sobrien 380132718Skan@smallexample 38190075Sobrien/* @r{this is} /* @r{one comment} */ @r{text outside comment} 382132718Skan@end smallexample 38390075Sobrien 38490075Sobrien@dfn{Line comments} begin with @samp{//} and continue to the end of the 38590075Sobriencurrent line. Line comments do not nest either, but it does not matter, 38690075Sobrienbecause they would end in the same place anyway. 38790075Sobrien 388132718Skan@smallexample 38990075Sobrien// @r{this is} // @r{one comment} 39090075Sobrien@r{text outside comment} 391132718Skan@end smallexample 39290075Sobrien@end enumerate 39390075Sobrien 39490075SobrienIt is safe to put line comments inside block comments, or vice versa. 39590075Sobrien 396132718Skan@smallexample 39790075Sobrien@group 39890075Sobrien/* @r{block comment} 39990075Sobrien // @r{contains line comment} 40090075Sobrien @r{yet more comment} 40190075Sobrien */ @r{outside comment} 40290075Sobrien 40390075Sobrien// @r{line comment} /* @r{contains block comment} */ 40490075Sobrien@end group 405132718Skan@end smallexample 40690075Sobrien 40790075SobrienBut beware of commenting out one end of a block comment with a line 40890075Sobriencomment. 40990075Sobrien 410132718Skan@smallexample 41190075Sobrien@group 41290075Sobrien // @r{l.c.} /* @r{block comment begins} 41390075Sobrien @r{oops! this isn't a comment anymore} */ 41490075Sobrien@end group 415132718Skan@end smallexample 41690075Sobrien 417132718SkanComments are not recognized within string literals. 418119256Skan@t{@w{"/* blah */"}} is the string constant @samp{@w{/* blah */}}, not 419119256Skanan empty string. 42090075Sobrien 42190075SobrienLine comments are not in the 1989 edition of the C standard, but they 42290075Sobrienare recognized by GCC as an extension. In C++ and in the 1999 edition 42390075Sobrienof the C standard, they are an official part of the language. 42490075Sobrien 42590075SobrienSince these transformations happen before all other processing, you can 42690075Sobriensplit a line mechanically with backslash-newline anywhere. You can 42790075Sobriencomment out the end of a line. You can continue a line comment onto the 42890075Sobriennext line with backslash-newline. You can even split @samp{/*}, 42990075Sobrien@samp{*/}, and @samp{//} onto multiple lines with backslash-newline. 43090075SobrienFor example: 43190075Sobrien 432132718Skan@smallexample 43390075Sobrien@group 43490075Sobrien/\ 43590075Sobrien* 43690075Sobrien*/ # /* 43790075Sobrien*/ defi\ 43890075Sobrienne FO\ 43990075SobrienO 10\ 44090075Sobrien20 44190075Sobrien@end group 442132718Skan@end smallexample 44390075Sobrien 44490075Sobrien@noindent 44590075Sobrienis equivalent to @code{@w{#define FOO 1020}}. All these tricks are 44690075Sobrienextremely confusing and should not be used in code intended to be 44790075Sobrienreadable. 44890075Sobrien 44990075SobrienThere is no way to prevent a backslash at the end of a line from being 450117395Skaninterpreted as a backslash-newline. This cannot affect any correct 451117395Skanprogram, however. 45290075Sobrien 45390075Sobrien@node Tokenization 45490075Sobrien@section Tokenization 45590075Sobrien 45690075Sobrien@cindex tokens 45790075Sobrien@cindex preprocessing tokens 45890075SobrienAfter the textual transformations are finished, the input file is 45990075Sobrienconverted into a sequence of @dfn{preprocessing tokens}. These mostly 46090075Sobriencorrespond to the syntactic tokens used by the C compiler, but there are 46190075Sobriena few differences. White space separates tokens; it is not itself a 46290075Sobrientoken of any kind. Tokens do not have to be separated by white space, 46390075Sobrienbut it is often necessary to avoid ambiguities. 46490075Sobrien 46590075SobrienWhen faced with a sequence of characters that has more than one possible 46690075Sobrientokenization, the preprocessor is greedy. It always makes each token, 46790075Sobrienstarting from the left, as big as possible before moving on to the next 46890075Sobrientoken. For instance, @code{a+++++b} is interpreted as 46990075Sobrien@code{@w{a ++ ++ + b}}, not as @code{@w{a ++ + ++ b}}, even though the 47090075Sobrienlatter tokenization could be part of a valid C program and the former 47190075Sobriencould not. 47290075Sobrien 47390075SobrienOnce the input file is broken into tokens, the token boundaries never 47490075Sobrienchange, except when the @samp{##} preprocessing operator is used to paste 47590075Sobrientokens together. @xref{Concatenation}. For example, 47690075Sobrien 477132718Skan@smallexample 47890075Sobrien@group 47990075Sobrien#define foo() bar 48090075Sobrienfoo()baz 48190075Sobrien @expansion{} bar baz 48290075Sobrien@emph{not} 48390075Sobrien @expansion{} barbaz 48490075Sobrien@end group 485132718Skan@end smallexample 48690075Sobrien 48790075SobrienThe compiler does not re-tokenize the preprocessor's output. Each 48890075Sobrienpreprocessing token becomes one compiler token. 48990075Sobrien 49090075Sobrien@cindex identifiers 49190075SobrienPreprocessing tokens fall into five broad classes: identifiers, 49290075Sobrienpreprocessing numbers, string literals, punctuators, and other. An 49390075Sobrien@dfn{identifier} is the same as an identifier in C: any sequence of 49490075Sobrienletters, digits, or underscores, which begins with a letter or 49590075Sobrienunderscore. Keywords of C have no significance to the preprocessor; 49690075Sobrienthey are ordinary identifiers. You can define a macro whose name is a 49790075Sobrienkeyword, for instance. The only identifier which can be considered a 49890075Sobrienpreprocessing keyword is @code{defined}. @xref{Defined}. 49990075Sobrien 50090075SobrienThis is mostly true of other languages which use the C preprocessor. 50190075SobrienHowever, a few of the keywords of C++ are significant even in the 50290075Sobrienpreprocessor. @xref{C++ Named Operators}. 50390075Sobrien 50490075SobrienIn the 1999 C standard, identifiers may contain letters which are not 505169689Skanpart of the ``basic source character set'', at the implementation's 50690075Sobriendiscretion (such as accented Latin letters, Greek letters, or Chinese 50790075Sobrienideograms). This may be done with an extended character set, or the 508169689Skan@samp{\u} and @samp{\U} escape sequences. The implementation of this 509169689Skanfeature in GCC is experimental; such characters are only accepted in 510169689Skanthe @samp{\u} and @samp{\U} forms and only if 511169689Skan@option{-fextended-identifiers} is used. 51290075Sobrien 51390075SobrienAs an extension, GCC treats @samp{$} as a letter. This is for 51490075Sobriencompatibility with some systems, such as VMS, where @samp{$} is commonly 51590075Sobrienused in system-defined function and object names. @samp{$} is not a 51690075Sobrienletter in strictly conforming mode, or if you specify the @option{-$} 51790075Sobrienoption. @xref{Invocation}. 51890075Sobrien 51990075Sobrien@cindex numbers 52090075Sobrien@cindex preprocessing numbers 52190075SobrienA @dfn{preprocessing number} has a rather bizarre definition. The 52290075Sobriencategory includes all the normal integer and floating point constants 52390075Sobrienone expects of C, but also a number of other things one might not 52490075Sobrieninitially recognize as a number. Formally, preprocessing numbers begin 52590075Sobrienwith an optional period, a required decimal digit, and then continue 52690075Sobrienwith any sequence of letters, digits, underscores, periods, and 52790075Sobrienexponents. Exponents are the two-character sequences @samp{e+}, 52890075Sobrien@samp{e-}, @samp{E+}, @samp{E-}, @samp{p+}, @samp{p-}, @samp{P+}, and 52990075Sobrien@samp{P-}. (The exponents that begin with @samp{p} or @samp{P} are new 53090075Sobriento C99. They are used for hexadecimal floating-point constants.) 53190075Sobrien 53290075SobrienThe purpose of this unusual definition is to isolate the preprocessor 53390075Sobrienfrom the full complexity of numeric constants. It does not have to 53490075Sobriendistinguish between lexically valid and invalid floating-point numbers, 53590075Sobrienwhich is complicated. The definition also permits you to split an 53690075Sobrienidentifier at any position and get exactly two tokens, which can then be 53790075Sobrienpasted back together with the @samp{##} operator. 53890075Sobrien 53990075SobrienIt's possible for preprocessing numbers to cause programs to be 54090075Sobrienmisinterpreted. For example, @code{0xE+12} is a preprocessing number 54190075Sobrienwhich does not translate to any valid numeric constant, therefore a 54290075Sobriensyntax error. It does not mean @code{@w{0xE + 12}}, which is what you 54390075Sobrienmight have intended. 54490075Sobrien 54590075Sobrien@cindex string literals 54690075Sobrien@cindex string constants 54790075Sobrien@cindex character constants 54890075Sobrien@cindex header file names 54990075Sobrien@c the @: prevents makeinfo from turning '' into ". 55090075Sobrien@dfn{String literals} are string constants, character constants, and 55190075Sobrienheader file names (the argument of @samp{#include}).@footnote{The C 55290075Sobrienstandard uses the term @dfn{string literal} to refer only to what we are 55390075Sobriencalling @dfn{string constants}.} String constants and character 55490075Sobrienconstants are straightforward: @t{"@dots{}"} or @t{'@dots{}'}. In 55590075Sobrieneither case embedded quotes should be escaped with a backslash: 55690075Sobrien@t{'\'@:'} is the character constant for @samp{'}. There is no limit on 55790075Sobrienthe length of a character constant, but the value of a character 55890075Sobrienconstant that contains more than one character is 55990075Sobrienimplementation-defined. @xref{Implementation Details}. 56090075Sobrien 56190075SobrienHeader file names either look like string constants, @t{"@dots{}"}, or are 56290075Sobrienwritten with angle brackets instead, @t{<@dots{}>}. In either case, 56390075Sobrienbackslash is an ordinary character. There is no way to escape the 56490075Sobrienclosing quote or angle bracket. The preprocessor looks for the header 56590075Sobrienfile in different places depending on which form you use. @xref{Include 56690075SobrienOperation}. 56790075Sobrien 568117395SkanNo string literal may extend past the end of a line. Older versions 569117395Skanof GCC accepted multi-line string constants. You may use continued 570117395Skanlines instead, or string constant concatenation. @xref{Differences 571117395Skanfrom previous versions}. 57290075Sobrien 57390075Sobrien@cindex punctuators 57490075Sobrien@cindex digraphs 57590075Sobrien@cindex alternative tokens 57690075Sobrien@dfn{Punctuators} are all the usual bits of punctuation which are 57790075Sobrienmeaningful to C and C++. All but three of the punctuation characters in 57890075SobrienASCII are C punctuators. The exceptions are @samp{@@}, @samp{$}, and 57990075Sobrien@samp{`}. In addition, all the two- and three-character operators are 58090075Sobrienpunctuators. There are also six @dfn{digraphs}, which the C++ standard 58190075Sobriencalls @dfn{alternative tokens}, which are merely alternate ways to spell 58290075Sobrienother punctuators. This is a second attempt to work around missing 58390075Sobrienpunctuation in obsolete systems. It has no negative side effects, 58490075Sobrienunlike trigraphs, but does not cover as much ground. The digraphs and 58590075Sobrientheir corresponding normal punctuators are: 58690075Sobrien 587132718Skan@smallexample 58890075SobrienDigraph: <% %> <: :> %: %:%: 58990075SobrienPunctuator: @{ @} [ ] # ## 590132718Skan@end smallexample 59190075Sobrien 59290075Sobrien@cindex other tokens 593169689SkanAny other single character is considered ``other''. It is passed on to 59490075Sobrienthe preprocessor's output unmolested. The C compiler will almost 59590075Sobriencertainly reject source code containing ``other'' tokens. In ASCII, the 59690075Sobrienonly other characters are @samp{@@}, @samp{$}, @samp{`}, and control 59790075Sobriencharacters other than NUL (all bits zero). (Note that @samp{$} is 59890075Sobriennormally considered a letter.) All characters with the high bit set 59990075Sobrien(numeric range 0x7F--0xFF) are also ``other'' in the present 60090075Sobrienimplementation. This will change when proper support for international 60190075Sobriencharacter sets is added to GCC@. 60290075Sobrien 60390075SobrienNUL is a special case because of the high probability that its 60490075Sobrienappearance is accidental, and because it may be invisible to the user 60590075Sobrien(many terminals do not display NUL at all). Within comments, NULs are 60690075Sobriensilently ignored, just as any other character would be. In running 60790075Sobrientext, NUL is considered white space. For example, these two directives 60890075Sobrienhave the same meaning. 60990075Sobrien 610132718Skan@smallexample 61190075Sobrien#define X^@@1 61290075Sobrien#define X 1 613132718Skan@end smallexample 61490075Sobrien 61590075Sobrien@noindent 61690075Sobrien(where @samp{^@@} is ASCII NUL)@. Within string or character constants, 61790075SobrienNULs are preserved. In the latter two cases the preprocessor emits a 61890075Sobrienwarning message. 61990075Sobrien 62090075Sobrien@node The preprocessing language 62190075Sobrien@section The preprocessing language 62290075Sobrien@cindex directives 62390075Sobrien@cindex preprocessing directives 62490075Sobrien@cindex directive line 62590075Sobrien@cindex directive name 62690075Sobrien 62790075SobrienAfter tokenization, the stream of tokens may simply be passed straight 62890075Sobriento the compiler's parser. However, if it contains any operations in the 62990075Sobrien@dfn{preprocessing language}, it will be transformed first. This stage 63090075Sobriencorresponds roughly to the standard's ``translation phase 4'' and is 63190075Sobrienwhat most people think of as the preprocessor's job. 63290075Sobrien 63390075SobrienThe preprocessing language consists of @dfn{directives} to be executed 63490075Sobrienand @dfn{macros} to be expanded. Its primary capabilities are: 63590075Sobrien 63690075Sobrien@itemize @bullet 63790075Sobrien@item 63890075SobrienInclusion of header files. These are files of declarations that can be 63990075Sobriensubstituted into your program. 64090075Sobrien 64190075Sobrien@item 64290075SobrienMacro expansion. You can define @dfn{macros}, which are abbreviations 64390075Sobrienfor arbitrary fragments of C code. The preprocessor will replace the 64490075Sobrienmacros with their definitions throughout the program. Some macros are 64590075Sobrienautomatically defined for you. 64690075Sobrien 64790075Sobrien@item 64890075SobrienConditional compilation. You can include or exclude parts of the 64990075Sobrienprogram according to various conditions. 65090075Sobrien 65190075Sobrien@item 65290075SobrienLine control. If you use a program to combine or rearrange source files 65390075Sobrieninto an intermediate file which is then compiled, you can use line 65490075Sobriencontrol to inform the compiler where each source line originally came 65590075Sobrienfrom. 65690075Sobrien 65790075Sobrien@item 65890075SobrienDiagnostics. You can detect problems at compile time and issue errors 65990075Sobrienor warnings. 66090075Sobrien@end itemize 66190075Sobrien 66290075SobrienThere are a few more, less useful, features. 66390075Sobrien 66490075SobrienExcept for expansion of predefined macros, all these operations are 66590075Sobrientriggered with @dfn{preprocessing directives}. Preprocessing directives 66690075Sobrienare lines in your program that start with @samp{#}. Whitespace is 66790075Sobrienallowed before and after the @samp{#}. The @samp{#} is followed by an 66890075Sobrienidentifier, the @dfn{directive name}. It specifies the operation to 66990075Sobrienperform. Directives are commonly referred to as @samp{#@var{name}} 67090075Sobrienwhere @var{name} is the directive name. For example, @samp{#define} is 67190075Sobrienthe directive that defines a macro. 67290075Sobrien 67390075SobrienThe @samp{#} which begins a directive cannot come from a macro 67490075Sobrienexpansion. Also, the directive name is not macro expanded. Thus, if 67590075Sobrien@code{foo} is defined as a macro expanding to @code{define}, that does 67690075Sobriennot make @samp{#foo} a valid preprocessing directive. 67790075Sobrien 67890075SobrienThe set of valid directive names is fixed. Programs cannot define new 67990075Sobrienpreprocessing directives. 68090075Sobrien 68190075SobrienSome directives require arguments; these make up the rest of the 68290075Sobriendirective line and must be separated from the directive name by 68390075Sobrienwhitespace. For example, @samp{#define} must be followed by a macro 68490075Sobrienname and the intended expansion of the macro. 68590075Sobrien 68690075SobrienA preprocessing directive cannot cover more than one line. The line 68790075Sobrienmay, however, be continued with backslash-newline, or by a block comment 68890075Sobrienwhich extends past the end of the line. In either case, when the 68990075Sobriendirective is processed, the continuations have already been merged with 69090075Sobrienthe first line to make one long line. 69190075Sobrien 69290075Sobrien@node Header Files 69390075Sobrien@chapter Header Files 69490075Sobrien 69590075Sobrien@cindex header file 69690075SobrienA header file is a file containing C declarations and macro definitions 69790075Sobrien(@pxref{Macros}) to be shared between several source files. You request 69890075Sobrienthe use of a header file in your program by @dfn{including} it, with the 69990075SobrienC preprocessing directive @samp{#include}. 70090075Sobrien 70190075SobrienHeader files serve two purposes. 70290075Sobrien 70390075Sobrien@itemize @bullet 70490075Sobrien@item 70590075Sobrien@cindex system header files 70690075SobrienSystem header files declare the interfaces to parts of the operating 70790075Sobriensystem. You include them in your program to supply the definitions and 70890075Sobriendeclarations you need to invoke system calls and libraries. 70990075Sobrien 71090075Sobrien@item 71190075SobrienYour own header files contain declarations for interfaces between the 71290075Sobriensource files of your program. Each time you have a group of related 71390075Sobriendeclarations and macro definitions all or most of which are needed in 71490075Sobrienseveral different source files, it is a good idea to create a header 71590075Sobrienfile for them. 71690075Sobrien@end itemize 71790075Sobrien 71890075SobrienIncluding a header file produces the same results as copying the header 71990075Sobrienfile into each source file that needs it. Such copying would be 72090075Sobrientime-consuming and error-prone. With a header file, the related 72190075Sobriendeclarations appear in only one place. If they need to be changed, they 72290075Sobriencan be changed in one place, and programs that include the header file 72390075Sobrienwill automatically use the new version when next recompiled. The header 72490075Sobrienfile eliminates the labor of finding and changing all the copies as well 72590075Sobrienas the risk that a failure to find one copy will result in 72690075Sobrieninconsistencies within a program. 72790075Sobrien 72890075SobrienIn C, the usual convention is to give header files names that end with 72990075Sobrien@file{.h}. It is most portable to use only letters, digits, dashes, and 73090075Sobrienunderscores in header file names, and at most one dot. 73190075Sobrien 73290075Sobrien@menu 73390075Sobrien* Include Syntax:: 73490075Sobrien* Include Operation:: 73590075Sobrien* Search Path:: 73690075Sobrien* Once-Only Headers:: 73790075Sobrien* Computed Includes:: 73890075Sobrien* Wrapper Headers:: 73990075Sobrien* System Headers:: 74090075Sobrien@end menu 74190075Sobrien 74290075Sobrien@node Include Syntax 74390075Sobrien@section Include Syntax 74490075Sobrien 74590075Sobrien@findex #include 74690075SobrienBoth user and system header files are included using the preprocessing 74790075Sobriendirective @samp{#include}. It has two variants: 74890075Sobrien 74990075Sobrien@table @code 75090075Sobrien@item #include <@var{file}> 75190075SobrienThis variant is used for system header files. It searches for a file 75290075Sobriennamed @var{file} in a standard list of system directories. You can prepend 75390075Sobriendirectories to this list with the @option{-I} option (@pxref{Invocation}). 75490075Sobrien 75590075Sobrien@item #include "@var{file}" 756169689SkanThis variant is used for header files of your own program. It 757169689Skansearches for a file named @var{file} first in the directory containing 758169689Skanthe current file, then in the quote directories and then the same 759169689Skandirectories used for @code{<@var{file}>}. You can prepend directories 760169689Skanto the list of quote directories with the @option{-iquote} option. 76190075Sobrien@end table 76290075Sobrien 76390075SobrienThe argument of @samp{#include}, whether delimited with quote marks or 76490075Sobrienangle brackets, behaves like a string constant in that comments are not 76590075Sobrienrecognized, and macro names are not expanded. Thus, @code{@w{#include 76690075Sobrien<x/*y>}} specifies inclusion of a system header file named @file{x/*y}. 76790075Sobrien 76890075SobrienHowever, if backslashes occur within @var{file}, they are considered 76990075Sobrienordinary text characters, not escape characters. None of the character 77090075Sobrienescape sequences appropriate to string constants in C are processed. 77190075SobrienThus, @code{@w{#include "x\n\\y"}} specifies a filename containing three 77290075Sobrienbackslashes. (Some systems interpret @samp{\} as a pathname separator. 77390075SobrienAll of these also interpret @samp{/} the same way. It is most portable 77490075Sobriento use only @samp{/}.) 77590075Sobrien 77690075SobrienIt is an error if there is anything (other than comments) on the line 77790075Sobrienafter the file name. 77890075Sobrien 77990075Sobrien@node Include Operation 78090075Sobrien@section Include Operation 78190075Sobrien 78290075SobrienThe @samp{#include} directive works by directing the C preprocessor to 78390075Sobrienscan the specified file as input before continuing with the rest of the 78490075Sobriencurrent file. The output from the preprocessor contains the output 78590075Sobrienalready generated, followed by the output resulting from the included 78690075Sobrienfile, followed by the output that comes from the text after the 78790075Sobrien@samp{#include} directive. For example, if you have a header file 78890075Sobrien@file{header.h} as follows, 78990075Sobrien 790132718Skan@smallexample 79190075Sobrienchar *test (void); 792132718Skan@end smallexample 79390075Sobrien 79490075Sobrien@noindent 79590075Sobrienand a main program called @file{program.c} that uses the header file, 79690075Sobrienlike this, 79790075Sobrien 798132718Skan@smallexample 79990075Sobrienint x; 80090075Sobrien#include "header.h" 80190075Sobrien 80290075Sobrienint 80390075Sobrienmain (void) 80490075Sobrien@{ 80590075Sobrien puts (test ()); 80690075Sobrien@} 807132718Skan@end smallexample 80890075Sobrien 80990075Sobrien@noindent 81090075Sobrienthe compiler will see the same token stream as it would if 81190075Sobrien@file{program.c} read 81290075Sobrien 813132718Skan@smallexample 81490075Sobrienint x; 81590075Sobrienchar *test (void); 81690075Sobrien 81790075Sobrienint 81890075Sobrienmain (void) 81990075Sobrien@{ 82090075Sobrien puts (test ()); 82190075Sobrien@} 822132718Skan@end smallexample 82390075Sobrien 82490075SobrienIncluded files are not limited to declarations and macro definitions; 82590075Sobrienthose are merely the typical uses. Any fragment of a C program can be 82690075Sobrienincluded from another file. The include file could even contain the 82790075Sobrienbeginning of a statement that is concluded in the containing file, or 82890075Sobrienthe end of a statement that was started in the including file. However, 829117395Skanan included file must consist of complete tokens. Comments and string 830117395Skanliterals which have not been closed by the end of an included file are 831117395Skaninvalid. For error recovery, they are considered to end at the end of 832117395Skanthe file. 83390075Sobrien 83490075SobrienTo avoid confusion, it is best if header files contain only complete 83590075Sobriensyntactic units---function declarations or definitions, type 83690075Sobriendeclarations, etc. 83790075Sobrien 83890075SobrienThe line following the @samp{#include} directive is always treated as a 83990075Sobrienseparate line by the C preprocessor, even if the included file lacks a 84090075Sobrienfinal newline. 84190075Sobrien 84290075Sobrien@node Search Path 84390075Sobrien@section Search Path 84490075Sobrien 84590075SobrienGCC looks in several different places for headers. On a normal Unix 84690075Sobriensystem, if you do not instruct it otherwise, it will look for headers 84790075Sobrienrequested with @code{@w{#include <@var{file}>}} in: 84890075Sobrien 849132718Skan@smallexample 85090075Sobrien/usr/local/include 851132718Skan@var{libdir}/gcc/@var{target}/@var{version}/include 85290075Sobrien/usr/@var{target}/include 85390075Sobrien/usr/include 854132718Skan@end smallexample 85590075Sobrien 85690075SobrienFor C++ programs, it will also look in @file{/usr/include/g++-v3}, 85790075Sobrienfirst. In the above, @var{target} is the canonical name of the system 85890075SobrienGCC was configured to compile code for; often but not always the same as 85990075Sobrienthe canonical name of the system it runs on. @var{version} is the 86090075Sobrienversion of GCC in use. 86190075Sobrien 86290075SobrienYou can add to this list with the @option{-I@var{dir}} command line 86390075Sobrienoption. All the directories named by @option{-I} are searched, in 864104752Skanleft-to-right order, @emph{before} the default directories. The only 865104752Skanexception is when @file{dir} is already searched by default. In 866104752Skanthis case, the option is ignored and the search order for system 867104752Skandirectories remains unchanged. 868104752Skan 869104752SkanDuplicate directories are removed from the quote and bracket search 870104752Skanchains before the two chains are merged to make the final search chain. 871104752SkanThus, it is possible for a directory to occur twice in the final search 872104752Skanchain if it was specified in both the quote and bracket chains. 873104752Skan 874104752SkanYou can prevent GCC from searching any of the default directories with 875104752Skanthe @option{-nostdinc} option. This is useful when you are compiling an 87690075Sobrienoperating system kernel or some other program that does not use the 87790075Sobrienstandard C library facilities, or the standard C library itself. 878104752Skan@option{-I} options are not ignored as described above when 879104752Skan@option{-nostdinc} is in effect. 88090075Sobrien 88190075SobrienGCC looks for headers requested with @code{@w{#include "@var{file}"}} 882169689Skanfirst in the directory containing the current file, then in the 883169689Skandirectories as specified by @option{-iquote} options, then in the same 884169689Skanplaces it would have looked for a header requested with angle 885169689Skanbrackets. For example, if @file{/usr/include/sys/stat.h} contains 88690075Sobrien@code{@w{#include "types.h"}}, GCC looks for @file{types.h} first in 88790075Sobrien@file{/usr/include/sys}, then in its usual search path. 88890075Sobrien 88990075Sobrien@samp{#line} (@pxref{Line Control}) does not change GCC's idea of the 89090075Sobriendirectory containing the current file. 89190075Sobrien 89290075SobrienYou may put @option{-I-} at any point in your list of @option{-I} options. 89390075SobrienThis has two effects. First, directories appearing before the 89490075Sobrien@option{-I-} in the list are searched only for headers requested with 89590075Sobrienquote marks. Directories after @option{-I-} are searched for all 89690075Sobrienheaders. Second, the directory containing the current file is not 89790075Sobriensearched for anything, unless it happens to be one of the directories 898169689Skannamed by an @option{-I} switch. @option{-I-} is deprecated, @option{-iquote} 899169689Skanshould be used instead. 90090075Sobrien 90190075Sobrien@option{-I. -I-} is not the same as no @option{-I} options at all, and does 90290075Sobriennot cause the same behavior for @samp{<>} includes that @samp{""} 90390075Sobrienincludes get with no special options. @option{-I.} searches the 90490075Sobriencompiler's current working directory for header files. That may or may 90590075Sobriennot be the same as the directory containing the current file. 90690075Sobrien 90790075SobrienIf you need to look for headers in a directory named @file{-}, write 90890075Sobrien@option{-I./-}. 90990075Sobrien 91090075SobrienThere are several more ways to adjust the header search path. They are 91190075Sobriengenerally less useful. @xref{Invocation}. 91290075Sobrien 91390075Sobrien@node Once-Only Headers 91490075Sobrien@section Once-Only Headers 91590075Sobrien@cindex repeated inclusion 91690075Sobrien@cindex including just once 91790075Sobrien@cindex wrapper @code{#ifndef} 91890075Sobrien 91990075SobrienIf a header file happens to be included twice, the compiler will process 92090075Sobrienits contents twice. This is very likely to cause an error, e.g.@: when the 92190075Sobriencompiler sees the same structure definition twice. Even if it does not, 92290075Sobrienit will certainly waste time. 92390075Sobrien 92490075SobrienThe standard way to prevent this is to enclose the entire real contents 92590075Sobrienof the file in a conditional, like this: 92690075Sobrien 927132718Skan@smallexample 92890075Sobrien@group 92990075Sobrien/* File foo. */ 93090075Sobrien#ifndef FILE_FOO_SEEN 93190075Sobrien#define FILE_FOO_SEEN 93290075Sobrien 93390075Sobrien@var{the entire file} 93490075Sobrien 93590075Sobrien#endif /* !FILE_FOO_SEEN */ 93690075Sobrien@end group 937132718Skan@end smallexample 93890075Sobrien 93990075SobrienThis construct is commonly known as a @dfn{wrapper #ifndef}. 94090075SobrienWhen the header is included again, the conditional will be false, 94190075Sobrienbecause @code{FILE_FOO_SEEN} is defined. The preprocessor will skip 94290075Sobrienover the entire contents of the file, and the compiler will not see it 94390075Sobrientwice. 94490075Sobrien 945117395SkanCPP optimizes even further. It remembers when a header file has a 94690075Sobrienwrapper @samp{#ifndef}. If a subsequent @samp{#include} specifies that 94790075Sobrienheader, and the macro in the @samp{#ifndef} is still defined, it does 94890075Sobriennot bother to rescan the file at all. 94990075Sobrien 95090075SobrienYou can put comments outside the wrapper. They will not interfere with 95190075Sobrienthis optimization. 95290075Sobrien 95390075Sobrien@cindex controlling macro 95490075Sobrien@cindex guard macro 95590075SobrienThe macro @code{FILE_FOO_SEEN} is called the @dfn{controlling macro} or 95690075Sobrien@dfn{guard macro}. In a user header file, the macro name should not 95790075Sobrienbegin with @samp{_}. In a system header file, it should begin with 95890075Sobrien@samp{__} to avoid conflicts with user programs. In any kind of header 95990075Sobrienfile, the macro name should contain the name of the file and some 96090075Sobrienadditional text, to avoid conflicts with other header files. 96190075Sobrien 96290075Sobrien@node Computed Includes 96390075Sobrien@section Computed Includes 96490075Sobrien@cindex computed includes 96590075Sobrien@cindex macros in include 96690075Sobrien 96790075SobrienSometimes it is necessary to select one of several different header 96890075Sobrienfiles to be included into your program. They might specify 96990075Sobrienconfiguration parameters to be used on different sorts of operating 97090075Sobriensystems, for instance. You could do this with a series of conditionals, 97190075Sobrien 972132718Skan@smallexample 97390075Sobrien#if SYSTEM_1 97490075Sobrien# include "system_1.h" 97590075Sobrien#elif SYSTEM_2 97690075Sobrien# include "system_2.h" 97790075Sobrien#elif SYSTEM_3 97890075Sobrien@dots{} 97990075Sobrien#endif 980132718Skan@end smallexample 98190075Sobrien 98290075SobrienThat rapidly becomes tedious. Instead, the preprocessor offers the 98390075Sobrienability to use a macro for the header name. This is called a 98490075Sobrien@dfn{computed include}. Instead of writing a header name as the direct 98590075Sobrienargument of @samp{#include}, you simply put a macro name there instead: 98690075Sobrien 987132718Skan@smallexample 98890075Sobrien#define SYSTEM_H "system_1.h" 98990075Sobrien@dots{} 99090075Sobrien#include SYSTEM_H 991132718Skan@end smallexample 99290075Sobrien 99390075Sobrien@noindent 99490075Sobrien@code{SYSTEM_H} will be expanded, and the preprocessor will look for 99590075Sobrien@file{system_1.h} as if the @samp{#include} had been written that way 99690075Sobrienoriginally. @code{SYSTEM_H} could be defined by your Makefile with a 99790075Sobrien@option{-D} option. 99890075Sobrien 99990075SobrienYou must be careful when you define the macro. @samp{#define} saves 100090075Sobrientokens, not text. The preprocessor has no way of knowing that the macro 100190075Sobrienwill be used as the argument of @samp{#include}, so it generates 100290075Sobrienordinary tokens, not a header name. This is unlikely to cause problems 100390075Sobrienif you use double-quote includes, which are close enough to string 100490075Sobrienconstants. If you use angle brackets, however, you may have trouble. 100590075Sobrien 100690075SobrienThe syntax of a computed include is actually a bit more general than the 100790075Sobrienabove. If the first non-whitespace character after @samp{#include} is 100890075Sobriennot @samp{"} or @samp{<}, then the entire line is macro-expanded 100990075Sobrienlike running text would be. 101090075Sobrien 101190075SobrienIf the line expands to a single string constant, the contents of that 101290075Sobrienstring constant are the file to be included. CPP does not re-examine the 101390075Sobrienstring for embedded quotes, but neither does it process backslash 101490075Sobrienescapes in the string. Therefore 101590075Sobrien 1016132718Skan@smallexample 101790075Sobrien#define HEADER "a\"b" 101890075Sobrien#include HEADER 1019132718Skan@end smallexample 102090075Sobrien 102190075Sobrien@noindent 102290075Sobrienlooks for a file named @file{a\"b}. CPP searches for the file according 102390075Sobriento the rules for double-quoted includes. 102490075Sobrien 102590075SobrienIf the line expands to a token stream beginning with a @samp{<} token 102690075Sobrienand including a @samp{>} token, then the tokens between the @samp{<} and 102790075Sobrienthe first @samp{>} are combined to form the filename to be included. 102890075SobrienAny whitespace between tokens is reduced to a single space; then any 102990075Sobrienspace after the initial @samp{<} is retained, but a trailing space 103090075Sobrienbefore the closing @samp{>} is ignored. CPP searches for the file 103190075Sobrienaccording to the rules for angle-bracket includes. 103290075Sobrien 103390075SobrienIn either case, if there are any tokens on the line after the file name, 103490075Sobrienan error occurs and the directive is not processed. It is also an error 103590075Sobrienif the result of expansion does not match either of the two expected 103690075Sobrienforms. 103790075Sobrien 103890075SobrienThese rules are implementation-defined behavior according to the C 103990075Sobrienstandard. To minimize the risk of different compilers interpreting your 104090075Sobriencomputed includes differently, we recommend you use only a single 104190075Sobrienobject-like macro which expands to a string constant. This will also 104290075Sobrienminimize confusion for people reading your program. 104390075Sobrien 104490075Sobrien@node Wrapper Headers 104590075Sobrien@section Wrapper Headers 104690075Sobrien@cindex wrapper headers 104790075Sobrien@cindex overriding a header file 104890075Sobrien@findex #include_next 104990075Sobrien 105090075SobrienSometimes it is necessary to adjust the contents of a system-provided 105190075Sobrienheader file without editing it directly. GCC's @command{fixincludes} 105290075Sobrienoperation does this, for example. One way to do that would be to create 105390075Sobriena new header file with the same name and insert it in the search path 105490075Sobrienbefore the original header. That works fine as long as you're willing 105590075Sobriento replace the old header entirely. But what if you want to refer to 105690075Sobrienthe old header from the new one? 105790075Sobrien 105890075SobrienYou cannot simply include the old header with @samp{#include}. That 105990075Sobrienwill start from the beginning, and find your new header again. If your 106090075Sobrienheader is not protected from multiple inclusion (@pxref{Once-Only 106190075SobrienHeaders}), it will recurse infinitely and cause a fatal error. 106290075Sobrien 106390075SobrienYou could include the old header with an absolute pathname: 1064132718Skan@smallexample 106590075Sobrien#include "/usr/include/old-header.h" 1066132718Skan@end smallexample 106790075Sobrien@noindent 106890075SobrienThis works, but is not clean; should the system headers ever move, you 106990075Sobrienwould have to edit the new headers to match. 107090075Sobrien 107190075SobrienThere is no way to solve this problem within the C standard, but you can 107290075Sobrienuse the GNU extension @samp{#include_next}. It means, ``Include the 1073169689Skan@emph{next} file with this name''. This directive works like 107490075Sobrien@samp{#include} except in searching for the specified file: it starts 107590075Sobriensearching the list of header file directories @emph{after} the directory 107690075Sobrienin which the current file was found. 107790075Sobrien 107890075SobrienSuppose you specify @option{-I /usr/local/include}, and the list of 107990075Sobriendirectories to search also includes @file{/usr/include}; and suppose 108090075Sobrienboth directories contain @file{signal.h}. Ordinary @code{@w{#include 108190075Sobrien<signal.h>}} finds the file under @file{/usr/local/include}. If that 108290075Sobrienfile contains @code{@w{#include_next <signal.h>}}, it starts searching 108390075Sobrienafter that directory, and finds the file in @file{/usr/include}. 108490075Sobrien 108590075Sobrien@samp{#include_next} does not distinguish between @code{<@var{file}>} 108690075Sobrienand @code{"@var{file}"} inclusion, nor does it check that the file you 108790075Sobrienspecify has the same name as the current file. It simply looks for the 108890075Sobrienfile named, starting with the directory in the search path after the one 108990075Sobrienwhere the current file was found. 109090075Sobrien 109190075SobrienThe use of @samp{#include_next} can lead to great confusion. We 109290075Sobrienrecommend it be used only when there is no other alternative. In 109390075Sobrienparticular, it should not be used in the headers belonging to a specific 109490075Sobrienprogram; it should be used only to make global corrections along the 109590075Sobrienlines of @command{fixincludes}. 109690075Sobrien 109790075Sobrien@node System Headers 109890075Sobrien@section System Headers 109990075Sobrien@cindex system header files 110090075Sobrien 110190075SobrienThe header files declaring interfaces to the operating system and 110290075Sobrienruntime libraries often cannot be written in strictly conforming C@. 110390075SobrienTherefore, GCC gives code found in @dfn{system headers} special 110490075Sobrientreatment. All warnings, other than those generated by @samp{#warning} 110590075Sobrien(@pxref{Diagnostics}), are suppressed while GCC is processing a system 110690075Sobrienheader. Macros defined in a system header are immune to a few warnings 110790075Sobrienwherever they are expanded. This immunity is granted on an ad-hoc 110890075Sobrienbasis, when we find that a warning generates lots of false positives 110990075Sobrienbecause of code in macros defined in system headers. 111090075Sobrien 111190075SobrienNormally, only the headers found in specific directories are considered 111290075Sobriensystem headers. These directories are determined when GCC is compiled. 111390075SobrienThere are, however, two ways to make normal headers into system headers. 111490075Sobrien 111590075SobrienThe @option{-isystem} command line option adds its argument to the list of 111690075Sobriendirectories to search for headers, just like @option{-I}. Any headers 111790075Sobrienfound in that directory will be considered system headers. 111890075Sobrien 111990075SobrienAll directories named by @option{-isystem} are searched @emph{after} all 112090075Sobriendirectories named by @option{-I}, no matter what their order was on the 112190075Sobriencommand line. If the same directory is named by both @option{-I} and 1122104752Skan@option{-isystem}, the @option{-I} option is ignored. GCC provides an 1123104752Skaninformative message when this occurs if @option{-v} is used. 112490075Sobrien 112590075Sobrien@findex #pragma GCC system_header 112690075SobrienThere is also a directive, @code{@w{#pragma GCC system_header}}, which 112790075Sobrientells GCC to consider the rest of the current include file a system 112890075Sobrienheader, no matter where it was found. Code that comes before the 112990075Sobrien@samp{#pragma} in the file will not be affected. @code{@w{#pragma GCC 113090075Sobriensystem_header}} has no effect in the primary source file. 113190075Sobrien 113290075SobrienOn very old systems, some of the pre-defined system header directories 113390075Sobrienget even more special treatment. GNU C++ considers code in headers 113490075Sobrienfound in those directories to be surrounded by an @code{@w{extern "C"}} 113590075Sobrienblock. There is no way to request this behavior with a @samp{#pragma}, 113690075Sobrienor from the command line. 113790075Sobrien 113890075Sobrien@node Macros 113990075Sobrien@chapter Macros 114090075Sobrien 114190075SobrienA @dfn{macro} is a fragment of code which has been given a name. 114290075SobrienWhenever the name is used, it is replaced by the contents of the macro. 114390075SobrienThere are two kinds of macros. They differ mostly in what they look 114490075Sobrienlike when they are used. @dfn{Object-like} macros resemble data objects 114590075Sobrienwhen used, @dfn{function-like} macros resemble function calls. 114690075Sobrien 114790075SobrienYou may define any valid identifier as a macro, even if it is a C 114890075Sobrienkeyword. The preprocessor does not know anything about keywords. This 114990075Sobriencan be useful if you wish to hide a keyword such as @code{const} from an 115090075Sobrienolder compiler that does not understand it. However, the preprocessor 115190075Sobrienoperator @code{defined} (@pxref{Defined}) can never be defined as a 115290075Sobrienmacro, and C++'s named operators (@pxref{C++ Named Operators}) cannot be 115390075Sobrienmacros when you are compiling C++. 115490075Sobrien 115590075Sobrien@menu 115690075Sobrien* Object-like Macros:: 115790075Sobrien* Function-like Macros:: 115890075Sobrien* Macro Arguments:: 115990075Sobrien* Stringification:: 116090075Sobrien* Concatenation:: 116190075Sobrien* Variadic Macros:: 116290075Sobrien* Predefined Macros:: 116390075Sobrien* Undefining and Redefining Macros:: 1164117395Skan* Directives Within Macro Arguments:: 116590075Sobrien* Macro Pitfalls:: 116690075Sobrien@end menu 116790075Sobrien 116890075Sobrien@node Object-like Macros 116990075Sobrien@section Object-like Macros 117090075Sobrien@cindex object-like macro 117190075Sobrien@cindex symbolic constants 117290075Sobrien@cindex manifest constants 117390075Sobrien 117490075SobrienAn @dfn{object-like macro} is a simple identifier which will be replaced 117590075Sobrienby a code fragment. It is called object-like because it looks like a 117690075Sobriendata object in code that uses it. They are most commonly used to give 117790075Sobriensymbolic names to numeric constants. 117890075Sobrien 117990075Sobrien@findex #define 118090075SobrienYou create macros with the @samp{#define} directive. @samp{#define} is 118190075Sobrienfollowed by the name of the macro and then the token sequence it should 118290075Sobrienbe an abbreviation for, which is variously referred to as the macro's 118390075Sobrien@dfn{body}, @dfn{expansion} or @dfn{replacement list}. For example, 118490075Sobrien 1185132718Skan@smallexample 118690075Sobrien#define BUFFER_SIZE 1024 1187132718Skan@end smallexample 118890075Sobrien 118990075Sobrien@noindent 119090075Sobriendefines a macro named @code{BUFFER_SIZE} as an abbreviation for the 119190075Sobrientoken @code{1024}. If somewhere after this @samp{#define} directive 119290075Sobrienthere comes a C statement of the form 119390075Sobrien 1194132718Skan@smallexample 119590075Sobrienfoo = (char *) malloc (BUFFER_SIZE); 1196132718Skan@end smallexample 119790075Sobrien 119890075Sobrien@noindent 119990075Sobrienthen the C preprocessor will recognize and @dfn{expand} the macro 120090075Sobrien@code{BUFFER_SIZE}. The C compiler will see the same tokens as it would 120190075Sobrienif you had written 120290075Sobrien 1203132718Skan@smallexample 120490075Sobrienfoo = (char *) malloc (1024); 1205132718Skan@end smallexample 120690075Sobrien 1207132718SkanBy convention, macro names are written in uppercase. Programs are 120890075Sobrieneasier to read when it is possible to tell at a glance which names are 120990075Sobrienmacros. 121090075Sobrien 121190075SobrienThe macro's body ends at the end of the @samp{#define} line. You may 121290075Sobriencontinue the definition onto multiple lines, if necessary, using 121390075Sobrienbackslash-newline. When the macro is expanded, however, it will all 121490075Sobriencome out on one line. For example, 121590075Sobrien 1216132718Skan@smallexample 121790075Sobrien#define NUMBERS 1, \ 121890075Sobrien 2, \ 121990075Sobrien 3 122090075Sobrienint x[] = @{ NUMBERS @}; 122190075Sobrien @expansion{} int x[] = @{ 1, 2, 3 @}; 1222132718Skan@end smallexample 122390075Sobrien 122490075Sobrien@noindent 122590075SobrienThe most common visible consequence of this is surprising line numbers 122690075Sobrienin error messages. 122790075Sobrien 122890075SobrienThere is no restriction on what can go in a macro body provided it 122990075Sobriendecomposes into valid preprocessing tokens. Parentheses need not 123090075Sobrienbalance, and the body need not resemble valid C code. (If it does not, 123190075Sobrienyou may get error messages from the C compiler when you use the macro.) 123290075Sobrien 123390075SobrienThe C preprocessor scans your program sequentially. Macro definitions 123490075Sobrientake effect at the place you write them. Therefore, the following input 123590075Sobriento the C preprocessor 123690075Sobrien 1237132718Skan@smallexample 123890075Sobrienfoo = X; 123990075Sobrien#define X 4 124090075Sobrienbar = X; 1241132718Skan@end smallexample 124290075Sobrien 124390075Sobrien@noindent 124490075Sobrienproduces 124590075Sobrien 1246132718Skan@smallexample 124790075Sobrienfoo = X; 124890075Sobrienbar = 4; 1249132718Skan@end smallexample 125090075Sobrien 125190075SobrienWhen the preprocessor expands a macro name, the macro's expansion 125290075Sobrienreplaces the macro invocation, then the expansion is examined for more 125390075Sobrienmacros to expand. For example, 125490075Sobrien 1255132718Skan@smallexample 125690075Sobrien@group 125790075Sobrien#define TABLESIZE BUFSIZE 125890075Sobrien#define BUFSIZE 1024 125990075SobrienTABLESIZE 126090075Sobrien @expansion{} BUFSIZE 126190075Sobrien @expansion{} 1024 126290075Sobrien@end group 1263132718Skan@end smallexample 126490075Sobrien 126590075Sobrien@noindent 126690075Sobrien@code{TABLESIZE} is expanded first to produce @code{BUFSIZE}, then that 126790075Sobrienmacro is expanded to produce the final result, @code{1024}. 126890075Sobrien 126990075SobrienNotice that @code{BUFSIZE} was not defined when @code{TABLESIZE} was 127090075Sobriendefined. The @samp{#define} for @code{TABLESIZE} uses exactly the 127190075Sobrienexpansion you specify---in this case, @code{BUFSIZE}---and does not 127290075Sobriencheck to see whether it too contains macro names. Only when you 127390075Sobrien@emph{use} @code{TABLESIZE} is the result of its expansion scanned for 127490075Sobrienmore macro names. 127590075Sobrien 127690075SobrienThis makes a difference if you change the definition of @code{BUFSIZE} 127790075Sobrienat some point in the source file. @code{TABLESIZE}, defined as shown, 127890075Sobrienwill always expand using the definition of @code{BUFSIZE} that is 127990075Sobriencurrently in effect: 128090075Sobrien 1281132718Skan@smallexample 128290075Sobrien#define BUFSIZE 1020 128390075Sobrien#define TABLESIZE BUFSIZE 128490075Sobrien#undef BUFSIZE 128590075Sobrien#define BUFSIZE 37 1286132718Skan@end smallexample 128790075Sobrien 128890075Sobrien@noindent 128990075SobrienNow @code{TABLESIZE} expands (in two stages) to @code{37}. 129090075Sobrien 129190075SobrienIf the expansion of a macro contains its own name, either directly or 129290075Sobrienvia intermediate macros, it is not expanded again when the expansion is 129390075Sobrienexamined for more macros. This prevents infinite recursion. 129490075Sobrien@xref{Self-Referential Macros}, for the precise details. 129590075Sobrien 129690075Sobrien@node Function-like Macros 129790075Sobrien@section Function-like Macros 129890075Sobrien@cindex function-like macros 129990075Sobrien 130090075SobrienYou can also define macros whose use looks like a function call. These 130190075Sobrienare called @dfn{function-like macros}. To define a function-like macro, 130290075Sobrienyou use the same @samp{#define} directive, but you put a pair of 130390075Sobrienparentheses immediately after the macro name. For example, 130490075Sobrien 1305132718Skan@smallexample 130690075Sobrien#define lang_init() c_init() 130790075Sobrienlang_init() 130890075Sobrien @expansion{} c_init() 1309132718Skan@end smallexample 131090075Sobrien 131190075SobrienA function-like macro is only expanded if its name appears with a pair 131290075Sobrienof parentheses after it. If you write just the name, it is left alone. 131390075SobrienThis can be useful when you have a function and a macro of the same 131490075Sobrienname, and you wish to use the function sometimes. 131590075Sobrien 1316132718Skan@smallexample 131790075Sobrienextern void foo(void); 1318169689Skan#define foo() /* @r{optimized inline version} */ 131990075Sobrien@dots{} 132090075Sobrien foo(); 132190075Sobrien funcptr = foo; 1322132718Skan@end smallexample 132390075Sobrien 132490075SobrienHere the call to @code{foo()} will use the macro, but the function 132590075Sobrienpointer will get the address of the real function. If the macro were to 132690075Sobrienbe expanded, it would cause a syntax error. 132790075Sobrien 132890075SobrienIf you put spaces between the macro name and the parentheses in the 132990075Sobrienmacro definition, that does not define a function-like macro, it defines 133090075Sobrienan object-like macro whose expansion happens to begin with a pair of 133190075Sobrienparentheses. 133290075Sobrien 1333132718Skan@smallexample 133490075Sobrien#define lang_init () c_init() 133590075Sobrienlang_init() 133690075Sobrien @expansion{} () c_init()() 1337132718Skan@end smallexample 133890075Sobrien 133990075SobrienThe first two pairs of parentheses in this expansion come from the 134090075Sobrienmacro. The third is the pair that was originally after the macro 134190075Sobrieninvocation. Since @code{lang_init} is an object-like macro, it does not 134290075Sobrienconsume those parentheses. 134390075Sobrien 134490075Sobrien@node Macro Arguments 134590075Sobrien@section Macro Arguments 134690075Sobrien@cindex arguments 134790075Sobrien@cindex macros with arguments 134890075Sobrien@cindex arguments in macro definitions 134990075Sobrien 135090075SobrienFunction-like macros can take @dfn{arguments}, just like true functions. 135190075SobrienTo define a macro that uses arguments, you insert @dfn{parameters} 135290075Sobrienbetween the pair of parentheses in the macro definition that make the 135390075Sobrienmacro function-like. The parameters must be valid C identifiers, 135490075Sobrienseparated by commas and optionally whitespace. 135590075Sobrien 135690075SobrienTo invoke a macro that takes arguments, you write the name of the macro 135790075Sobrienfollowed by a list of @dfn{actual arguments} in parentheses, separated 135890075Sobrienby commas. The invocation of the macro need not be restricted to a 135990075Sobriensingle logical line---it can cross as many lines in the source file as 136090075Sobrienyou wish. The number of arguments you give must match the number of 136190075Sobrienparameters in the macro definition. When the macro is expanded, each 136290075Sobrienuse of a parameter in its body is replaced by the tokens of the 136390075Sobriencorresponding argument. (You need not use all of the parameters in the 136490075Sobrienmacro body.) 136590075Sobrien 136690075SobrienAs an example, here is a macro that computes the minimum of two numeric 136790075Sobrienvalues, as it is defined in many C programs, and some uses. 136890075Sobrien 1369132718Skan@smallexample 137090075Sobrien#define min(X, Y) ((X) < (Y) ? (X) : (Y)) 137190075Sobrien x = min(a, b); @expansion{} x = ((a) < (b) ? (a) : (b)); 137290075Sobrien y = min(1, 2); @expansion{} y = ((1) < (2) ? (1) : (2)); 137390075Sobrien z = min(a + 28, *p); @expansion{} z = ((a + 28) < (*p) ? (a + 28) : (*p)); 1374132718Skan@end smallexample 137590075Sobrien 137690075Sobrien@noindent 137790075Sobrien(In this small example you can already see several of the dangers of 137890075Sobrienmacro arguments. @xref{Macro Pitfalls}, for detailed explanations.) 137990075Sobrien 138090075SobrienLeading and trailing whitespace in each argument is dropped, and all 138190075Sobrienwhitespace between the tokens of an argument is reduced to a single 138290075Sobrienspace. Parentheses within each argument must balance; a comma within 138390075Sobriensuch parentheses does not end the argument. However, there is no 138490075Sobrienrequirement for square brackets or braces to balance, and they do not 138590075Sobrienprevent a comma from separating arguments. Thus, 138690075Sobrien 1387132718Skan@smallexample 138890075Sobrienmacro (array[x = y, x + 1]) 1389132718Skan@end smallexample 139090075Sobrien 139190075Sobrien@noindent 139290075Sobrienpasses two arguments to @code{macro}: @code{array[x = y} and @code{x + 139390075Sobrien1]}. If you want to supply @code{array[x = y, x + 1]} as an argument, 139490075Sobrienyou can write it as @code{array[(x = y, x + 1)]}, which is equivalent C 139590075Sobriencode. 139690075Sobrien 139790075SobrienAll arguments to a macro are completely macro-expanded before they are 139890075Sobriensubstituted into the macro body. After substitution, the complete text 139990075Sobrienis scanned again for macros to expand, including the arguments. This rule 140090075Sobrienmay seem strange, but it is carefully designed so you need not worry 140190075Sobrienabout whether any function call is actually a macro invocation. You can 140290075Sobrienrun into trouble if you try to be too clever, though. @xref{Argument 140390075SobrienPrescan}, for detailed discussion. 140490075Sobrien 140590075SobrienFor example, @code{min (min (a, b), c)} is first expanded to 140690075Sobrien 1407132718Skan@smallexample 140890075Sobrien min (((a) < (b) ? (a) : (b)), (c)) 1409132718Skan@end smallexample 141090075Sobrien 141190075Sobrien@noindent 141290075Sobrienand then to 141390075Sobrien 1414132718Skan@smallexample 141590075Sobrien@group 141690075Sobrien((((a) < (b) ? (a) : (b))) < (c) 141790075Sobrien ? (((a) < (b) ? (a) : (b))) 141890075Sobrien : (c)) 141990075Sobrien@end group 1420132718Skan@end smallexample 142190075Sobrien 142290075Sobrien@noindent 142390075Sobrien(Line breaks shown here for clarity would not actually be generated.) 142490075Sobrien 142590075Sobrien@cindex empty macro arguments 142690075SobrienYou can leave macro arguments empty; this is not an error to the 142790075Sobrienpreprocessor (but many macros will then expand to invalid code). 142890075SobrienYou cannot leave out arguments entirely; if a macro takes two arguments, 142990075Sobrienthere must be exactly one comma at the top level of its argument list. 143090075SobrienHere are some silly examples using @code{min}: 143190075Sobrien 1432132718Skan@smallexample 143390075Sobrienmin(, b) @expansion{} (( ) < (b) ? ( ) : (b)) 143490075Sobrienmin(a, ) @expansion{} ((a ) < ( ) ? (a ) : ( )) 143590075Sobrienmin(,) @expansion{} (( ) < ( ) ? ( ) : ( )) 143690075Sobrienmin((,),) @expansion{} (((,)) < ( ) ? ((,)) : ( )) 143790075Sobrien 143890075Sobrienmin() @error{} macro "min" requires 2 arguments, but only 1 given 143990075Sobrienmin(,,) @error{} macro "min" passed 3 arguments, but takes just 2 1440132718Skan@end smallexample 144190075Sobrien 144290075SobrienWhitespace is not a preprocessing token, so if a macro @code{foo} takes 144390075Sobrienone argument, @code{@w{foo ()}} and @code{@w{foo ( )}} both supply it an 144490075Sobrienempty argument. Previous GNU preprocessor implementations and 144590075Sobriendocumentation were incorrect on this point, insisting that a 144690075Sobrienfunction-like macro that takes a single argument be passed a space if an 144790075Sobrienempty argument was required. 144890075Sobrien 144990075SobrienMacro parameters appearing inside string literals are not replaced by 145090075Sobrientheir corresponding actual arguments. 145190075Sobrien 1452132718Skan@smallexample 145390075Sobrien#define foo(x) x, "x" 145490075Sobrienfoo(bar) @expansion{} bar, "x" 1455132718Skan@end smallexample 145690075Sobrien 145790075Sobrien@node Stringification 145890075Sobrien@section Stringification 145990075Sobrien@cindex stringification 146090075Sobrien@cindex @samp{#} operator 146190075Sobrien 146290075SobrienSometimes you may want to convert a macro argument into a string 146390075Sobrienconstant. Parameters are not replaced inside string constants, but you 146490075Sobriencan use the @samp{#} preprocessing operator instead. When a macro 146590075Sobrienparameter is used with a leading @samp{#}, the preprocessor replaces it 146690075Sobrienwith the literal text of the actual argument, converted to a string 146790075Sobrienconstant. Unlike normal parameter replacement, the argument is not 146890075Sobrienmacro-expanded first. This is called @dfn{stringification}. 146990075Sobrien 147090075SobrienThere is no way to combine an argument with surrounding text and 147190075Sobrienstringify it all together. Instead, you can write a series of adjacent 147290075Sobrienstring constants and stringified arguments. The preprocessor will 147390075Sobrienreplace the stringified arguments with string constants. The C 147490075Sobriencompiler will then combine all the adjacent string constants into one 147590075Sobrienlong string. 147690075Sobrien 147790075SobrienHere is an example of a macro definition that uses stringification: 147890075Sobrien 1479132718Skan@smallexample 148090075Sobrien@group 148190075Sobrien#define WARN_IF(EXP) \ 148290075Sobriendo @{ if (EXP) \ 148390075Sobrien fprintf (stderr, "Warning: " #EXP "\n"); @} \ 148490075Sobrienwhile (0) 148590075SobrienWARN_IF (x == 0); 148690075Sobrien @expansion{} do @{ if (x == 0) 148790075Sobrien fprintf (stderr, "Warning: " "x == 0" "\n"); @} while (0); 148890075Sobrien@end group 1489132718Skan@end smallexample 149090075Sobrien 149190075Sobrien@noindent 149290075SobrienThe argument for @code{EXP} is substituted once, as-is, into the 149390075Sobrien@code{if} statement, and once, stringified, into the argument to 149490075Sobrien@code{fprintf}. If @code{x} were a macro, it would be expanded in the 149590075Sobrien@code{if} statement, but not in the string. 149690075Sobrien 149790075SobrienThe @code{do} and @code{while (0)} are a kludge to make it possible to 149890075Sobrienwrite @code{WARN_IF (@var{arg});}, which the resemblance of 149990075Sobrien@code{WARN_IF} to a function would make C programmers want to do; see 150090075Sobrien@ref{Swallowing the Semicolon}. 150190075Sobrien 150290075SobrienStringification in C involves more than putting double-quote characters 150390075Sobrienaround the fragment. The preprocessor backslash-escapes the quotes 150490075Sobriensurrounding embedded string constants, and all backslashes within string and 150590075Sobriencharacter constants, in order to get a valid C string constant with the 150690075Sobrienproper contents. Thus, stringifying @code{@w{p = "foo\n";}} results in 150790075Sobrien@t{@w{"p = \"foo\\n\";"}}. However, backslashes that are not inside string 150890075Sobrienor character constants are not duplicated: @samp{\n} by itself 150990075Sobrienstringifies to @t{"\n"}. 151090075Sobrien 151190075SobrienAll leading and trailing whitespace in text being stringified is 151290075Sobrienignored. Any sequence of whitespace in the middle of the text is 151390075Sobrienconverted to a single space in the stringified result. Comments are 151490075Sobrienreplaced by whitespace long before stringification happens, so they 151590075Sobriennever appear in stringified text. 151690075Sobrien 151790075SobrienThere is no way to convert a macro argument into a character constant. 151890075Sobrien 151990075SobrienIf you want to stringify the result of expansion of a macro argument, 152090075Sobrienyou have to use two levels of macros. 152190075Sobrien 1522132718Skan@smallexample 152390075Sobrien#define xstr(s) str(s) 152490075Sobrien#define str(s) #s 152590075Sobrien#define foo 4 152690075Sobrienstr (foo) 152790075Sobrien @expansion{} "foo" 152890075Sobrienxstr (foo) 152990075Sobrien @expansion{} xstr (4) 153090075Sobrien @expansion{} str (4) 153190075Sobrien @expansion{} "4" 1532132718Skan@end smallexample 153390075Sobrien 153490075Sobrien@code{s} is stringified when it is used in @code{str}, so it is not 153590075Sobrienmacro-expanded first. But @code{s} is an ordinary argument to 153690075Sobrien@code{xstr}, so it is completely macro-expanded before @code{xstr} 153790075Sobrienitself is expanded (@pxref{Argument Prescan}). Therefore, by the time 153890075Sobrien@code{str} gets to its argument, it has already been macro-expanded. 153990075Sobrien 154090075Sobrien@node Concatenation 154190075Sobrien@section Concatenation 154290075Sobrien@cindex concatenation 154390075Sobrien@cindex token pasting 154490075Sobrien@cindex token concatenation 154590075Sobrien@cindex @samp{##} operator 154690075Sobrien 154790075SobrienIt is often useful to merge two tokens into one while expanding macros. 154890075SobrienThis is called @dfn{token pasting} or @dfn{token concatenation}. The 154990075Sobrien@samp{##} preprocessing operator performs token pasting. When a macro 155090075Sobrienis expanded, the two tokens on either side of each @samp{##} operator 155190075Sobrienare combined into a single token, which then replaces the @samp{##} and 155290075Sobrienthe two original tokens in the macro expansion. Usually both will be 155390075Sobrienidentifiers, or one will be an identifier and the other a preprocessing 155490075Sobriennumber. When pasted, they make a longer identifier. This isn't the 155590075Sobrienonly valid case. It is also possible to concatenate two numbers (or a 155690075Sobriennumber and a name, such as @code{1.5} and @code{e3}) into a number. 155790075SobrienAlso, multi-character operators such as @code{+=} can be formed by 155890075Sobrientoken pasting. 155990075Sobrien 156090075SobrienHowever, two tokens that don't together form a valid token cannot be 156190075Sobrienpasted together. For example, you cannot concatenate @code{x} with 156290075Sobrien@code{+} in either order. If you try, the preprocessor issues a warning 156390075Sobrienand emits the two tokens. Whether it puts white space between the 156490075Sobrientokens is undefined. It is common to find unnecessary uses of @samp{##} 156590075Sobrienin complex macros. If you get this warning, it is likely that you can 156690075Sobriensimply remove the @samp{##}. 156790075Sobrien 156890075SobrienBoth the tokens combined by @samp{##} could come from the macro body, 156990075Sobrienbut you could just as well write them as one token in the first place. 157090075SobrienToken pasting is most useful when one or both of the tokens comes from a 157190075Sobrienmacro argument. If either of the tokens next to an @samp{##} is a 157290075Sobrienparameter name, it is replaced by its actual argument before @samp{##} 157390075Sobrienexecutes. As with stringification, the actual argument is not 157490075Sobrienmacro-expanded first. If the argument is empty, that @samp{##} has no 157590075Sobrieneffect. 157690075Sobrien 157790075SobrienKeep in mind that the C preprocessor converts comments to whitespace 157890075Sobrienbefore macros are even considered. Therefore, you cannot create a 157990075Sobriencomment by concatenating @samp{/} and @samp{*}. You can put as much 158090075Sobrienwhitespace between @samp{##} and its operands as you like, including 158190075Sobriencomments, and you can put comments in arguments that will be 158290075Sobrienconcatenated. However, it is an error if @samp{##} appears at either 158390075Sobrienend of a macro body. 158490075Sobrien 158590075SobrienConsider a C program that interprets named commands. There probably 158690075Sobrienneeds to be a table of commands, perhaps an array of structures declared 158790075Sobrienas follows: 158890075Sobrien 1589132718Skan@smallexample 159090075Sobrien@group 159190075Sobrienstruct command 159290075Sobrien@{ 159390075Sobrien char *name; 159490075Sobrien void (*function) (void); 159590075Sobrien@}; 159690075Sobrien@end group 159790075Sobrien 159890075Sobrien@group 159990075Sobrienstruct command commands[] = 160090075Sobrien@{ 160190075Sobrien @{ "quit", quit_command @}, 160290075Sobrien @{ "help", help_command @}, 160390075Sobrien @dots{} 160490075Sobrien@}; 160590075Sobrien@end group 1606132718Skan@end smallexample 160790075Sobrien 160890075SobrienIt would be cleaner not to have to give each command name twice, once in 160990075Sobrienthe string constant and once in the function name. A macro which takes the 161090075Sobrienname of a command as an argument can make this unnecessary. The string 161190075Sobrienconstant can be created with stringification, and the function name by 161290075Sobrienconcatenating the argument with @samp{_command}. Here is how it is done: 161390075Sobrien 1614132718Skan@smallexample 161590075Sobrien#define COMMAND(NAME) @{ #NAME, NAME ## _command @} 161690075Sobrien 161790075Sobrienstruct command commands[] = 161890075Sobrien@{ 161990075Sobrien COMMAND (quit), 162090075Sobrien COMMAND (help), 162190075Sobrien @dots{} 162290075Sobrien@}; 1623132718Skan@end smallexample 162490075Sobrien 162590075Sobrien@node Variadic Macros 162690075Sobrien@section Variadic Macros 162790075Sobrien@cindex variable number of arguments 162890075Sobrien@cindex macros with variable arguments 162990075Sobrien@cindex variadic macros 163090075Sobrien 163190075SobrienA macro can be declared to accept a variable number of arguments much as 163290075Sobriena function can. The syntax for defining the macro is similar to that of 163390075Sobriena function. Here is an example: 163490075Sobrien 1635132718Skan@smallexample 163690075Sobrien#define eprintf(@dots{}) fprintf (stderr, __VA_ARGS__) 1637132718Skan@end smallexample 163890075Sobrien 163990075SobrienThis kind of macro is called @dfn{variadic}. When the macro is invoked, 164090075Sobrienall the tokens in its argument list after the last named argument (this 164190075Sobrienmacro has none), including any commas, become the @dfn{variable 164290075Sobrienargument}. This sequence of tokens replaces the identifier 164390075Sobrien@code{@w{__VA_ARGS__}} in the macro body wherever it appears. Thus, we 164490075Sobrienhave this expansion: 164590075Sobrien 1646132718Skan@smallexample 164790075Sobrieneprintf ("%s:%d: ", input_file, lineno) 164890075Sobrien @expansion{} fprintf (stderr, "%s:%d: ", input_file, lineno) 1649132718Skan@end smallexample 165090075Sobrien 165190075SobrienThe variable argument is completely macro-expanded before it is inserted 165290075Sobrieninto the macro expansion, just like an ordinary argument. You may use 165390075Sobrienthe @samp{#} and @samp{##} operators to stringify the variable argument 165490075Sobrienor to paste its leading or trailing token with another token. (But see 165590075Sobrienbelow for an important special case for @samp{##}.) 165690075Sobrien 165790075SobrienIf your macro is complicated, you may want a more descriptive name for 1658117395Skanthe variable argument than @code{@w{__VA_ARGS__}}. CPP permits 165990075Sobrienthis, as an extension. You may write an argument name immediately 166090075Sobrienbefore the @samp{@dots{}}; that name is used for the variable argument. 166190075SobrienThe @code{eprintf} macro above could be written 166290075Sobrien 1663132718Skan@smallexample 166490075Sobrien#define eprintf(args@dots{}) fprintf (stderr, args) 1665132718Skan@end smallexample 166690075Sobrien 166790075Sobrien@noindent 1668117395Skanusing this extension. You cannot use @code{@w{__VA_ARGS__}} and this 166990075Sobrienextension in the same macro. 167090075Sobrien 167190075SobrienYou can have named arguments as well as variable arguments in a variadic 167290075Sobrienmacro. We could define @code{eprintf} like this, instead: 167390075Sobrien 1674132718Skan@smallexample 167590075Sobrien#define eprintf(format, @dots{}) fprintf (stderr, format, __VA_ARGS__) 1676132718Skan@end smallexample 167790075Sobrien 167890075Sobrien@noindent 167990075SobrienThis formulation looks more descriptive, but unfortunately it is less 168090075Sobrienflexible: you must now supply at least one argument after the format 168190075Sobrienstring. In standard C, you cannot omit the comma separating the named 168290075Sobrienargument from the variable arguments. Furthermore, if you leave the 168390075Sobrienvariable argument empty, you will get a syntax error, because 168490075Sobrienthere will be an extra comma after the format string. 168590075Sobrien 1686132718Skan@smallexample 168790075Sobrieneprintf("success!\n", ); 168890075Sobrien @expansion{} fprintf(stderr, "success!\n", ); 1689132718Skan@end smallexample 169090075Sobrien 169190075SobrienGNU CPP has a pair of extensions which deal with this problem. First, 169290075Sobrienyou are allowed to leave the variable argument out entirely: 169390075Sobrien 1694132718Skan@smallexample 169590075Sobrieneprintf ("success!\n") 169690075Sobrien @expansion{} fprintf(stderr, "success!\n", ); 1697132718Skan@end smallexample 169890075Sobrien 169990075Sobrien@noindent 170090075SobrienSecond, the @samp{##} token paste operator has a special meaning when 170190075Sobrienplaced between a comma and a variable argument. If you write 170290075Sobrien 1703132718Skan@smallexample 170490075Sobrien#define eprintf(format, @dots{}) fprintf (stderr, format, ##__VA_ARGS__) 1705132718Skan@end smallexample 170690075Sobrien 170790075Sobrien@noindent 170890075Sobrienand the variable argument is left out when the @code{eprintf} macro is 170990075Sobrienused, then the comma before the @samp{##} will be deleted. This does 171090075Sobrien@emph{not} happen if you pass an empty argument, nor does it happen if 171190075Sobrienthe token preceding @samp{##} is anything other than a comma. 171290075Sobrien 1713132718Skan@smallexample 171490075Sobrieneprintf ("success!\n") 171590075Sobrien @expansion{} fprintf(stderr, "success!\n"); 1716132718Skan@end smallexample 171790075Sobrien 1718102780Skan@noindent 1719102780SkanThe above explanation is ambiguous about the case where the only macro 1720102780Skanparameter is a variable arguments parameter, as it is meaningless to 1721102780Skantry to distinguish whether no argument at all is an empty argument or 1722102780Skana missing argument. In this case the C99 standard is clear that the 1723102780Skancomma must remain, however the existing GCC extension used to swallow 1724102780Skanthe comma. So CPP retains the comma when conforming to a specific C 1725102780Skanstandard, and drops it otherwise. 1726102780Skan 172790075SobrienC99 mandates that the only place the identifier @code{@w{__VA_ARGS__}} 172890075Sobriencan appear is in the replacement list of a variadic macro. It may not 172990075Sobrienbe used as a macro name, macro argument name, or within a different type 173090075Sobrienof macro. It may also be forbidden in open text; the standard is 173190075Sobrienambiguous. We recommend you avoid using it except for its defined 173290075Sobrienpurpose. 173390075Sobrien 173490075SobrienVariadic macros are a new feature in C99. GNU CPP has supported them 173590075Sobrienfor a long time, but only with a named variable argument 173690075Sobrien(@samp{args@dots{}}, not @samp{@dots{}} and @code{@w{__VA_ARGS__}}). If you are 173790075Sobrienconcerned with portability to previous versions of GCC, you should use 173890075Sobrienonly named variable arguments. On the other hand, if you are concerned 173990075Sobrienwith portability to other conforming implementations of C99, you should 174090075Sobrienuse only @code{@w{__VA_ARGS__}}. 174190075Sobrien 1742117395SkanPrevious versions of CPP implemented the comma-deletion extension 174390075Sobrienmuch more generally. We have restricted it in this release to minimize 174490075Sobrienthe differences from C99. To get the same effect with both this and 174590075Sobrienprevious versions of GCC, the token preceding the special @samp{##} must 174690075Sobrienbe a comma, and there must be white space between that comma and 174790075Sobrienwhatever comes immediately before it: 174890075Sobrien 1749132718Skan@smallexample 175090075Sobrien#define eprintf(format, args@dots{}) fprintf (stderr, format , ##args) 1751132718Skan@end smallexample 175290075Sobrien 175390075Sobrien@noindent 175490075Sobrien@xref{Differences from previous versions}, for the gory details. 175590075Sobrien 175690075Sobrien@node Predefined Macros 175790075Sobrien@section Predefined Macros 175890075Sobrien 175990075Sobrien@cindex predefined macros 176090075SobrienSeveral object-like macros are predefined; you use them without 176190075Sobriensupplying their definitions. They fall into three classes: standard, 176290075Sobriencommon, and system-specific. 176390075Sobrien 176490075SobrienIn C++, there is a fourth category, the named operators. They act like 176590075Sobrienpredefined macros, but you cannot undefine them. 176690075Sobrien 176790075Sobrien@menu 176890075Sobrien* Standard Predefined Macros:: 176990075Sobrien* Common Predefined Macros:: 177090075Sobrien* System-specific Predefined Macros:: 177190075Sobrien* C++ Named Operators:: 177290075Sobrien@end menu 177390075Sobrien 177490075Sobrien@node Standard Predefined Macros 177590075Sobrien@subsection Standard Predefined Macros 177690075Sobrien@cindex standard predefined macros. 177790075Sobrien 1778119256SkanThe standard predefined macros are specified by the relevant 177990075Sobrienlanguage standards, so they are available with all compilers that 178090075Sobrienimplement those standards. Older compilers may not provide all of 178190075Sobrienthem. Their names all start with double underscores. 178290075Sobrien 178390075Sobrien@table @code 178490075Sobrien@item __FILE__ 178590075SobrienThis macro expands to the name of the current input file, in the form of 178690075Sobriena C string constant. This is the path by which the preprocessor opened 178790075Sobrienthe file, not the short name specified in @samp{#include} or as the 178890075Sobrieninput file name argument. For example, 178990075Sobrien@code{"/usr/local/include/myheader.h"} is a possible expansion of this 179090075Sobrienmacro. 179190075Sobrien 179290075Sobrien@item __LINE__ 179390075SobrienThis macro expands to the current input line number, in the form of a 179490075Sobriendecimal integer constant. While we call it a predefined macro, it's 179590075Sobriena pretty strange macro, since its ``definition'' changes with each 179690075Sobriennew line of source code. 179790075Sobrien@end table 179890075Sobrien 179990075Sobrien@code{__FILE__} and @code{__LINE__} are useful in generating an error 180090075Sobrienmessage to report an inconsistency detected by the program; the message 180190075Sobriencan state the source line at which the inconsistency was detected. For 180290075Sobrienexample, 180390075Sobrien 1804132718Skan@smallexample 180590075Sobrienfprintf (stderr, "Internal error: " 180690075Sobrien "negative string length " 180790075Sobrien "%d at %s, line %d.", 180890075Sobrien length, __FILE__, __LINE__); 1809132718Skan@end smallexample 181090075Sobrien 181190075SobrienAn @samp{#include} directive changes the expansions of @code{__FILE__} 181290075Sobrienand @code{__LINE__} to correspond to the included file. At the end of 181390075Sobrienthat file, when processing resumes on the input file that contained 181490075Sobrienthe @samp{#include} directive, the expansions of @code{__FILE__} and 181590075Sobrien@code{__LINE__} revert to the values they had before the 181690075Sobrien@samp{#include} (but @code{__LINE__} is then incremented by one as 181790075Sobrienprocessing moves to the line after the @samp{#include}). 181890075Sobrien 181990075SobrienA @samp{#line} directive changes @code{__LINE__}, and may change 182090075Sobrien@code{__FILE__} as well. @xref{Line Control}. 182190075Sobrien 182290075SobrienC99 introduces @code{__func__}, and GCC has provided @code{__FUNCTION__} 182390075Sobrienfor a long time. Both of these are strings containing the name of the 182490075Sobriencurrent function (there are slight semantic differences; see the GCC 182590075Sobrienmanual). Neither of them is a macro; the preprocessor does not know the 182690075Sobrienname of the current function. They tend to be useful in conjunction 182790075Sobrienwith @code{__FILE__} and @code{__LINE__}, though. 182890075Sobrien 182990075Sobrien@table @code 183090075Sobrien 183190075Sobrien@item __DATE__ 183290075SobrienThis macro expands to a string constant that describes the date on which 183390075Sobrienthe preprocessor is being run. The string constant contains eleven 183490075Sobriencharacters and looks like @code{@w{"Feb 12 1996"}}. If the day of the 183590075Sobrienmonth is less than 10, it is padded with a space on the left. 183690075Sobrien 1837117395SkanIf GCC cannot determine the current date, it will emit a warning message 1838117395Skan(once per compilation) and @code{__DATE__} will expand to 1839117395Skan@code{@w{"??? ?? ????"}}. 1840117395Skan 184190075Sobrien@item __TIME__ 184290075SobrienThis macro expands to a string constant that describes the time at 184390075Sobrienwhich the preprocessor is being run. The string constant contains 184490075Sobrieneight characters and looks like @code{"23:59:01"}. 184590075Sobrien 1846117395SkanIf GCC cannot determine the current time, it will emit a warning message 1847117395Skan(once per compilation) and @code{__TIME__} will expand to 1848117395Skan@code{"??:??:??"}. 1849117395Skan 185090075Sobrien@item __STDC__ 185190075SobrienIn normal operation, this macro expands to the constant 1, to signify 185290075Sobrienthat this compiler conforms to ISO Standard C@. If GNU CPP is used with 185390075Sobriena compiler other than GCC, this is not necessarily true; however, the 1854117395Skanpreprocessor always conforms to the standard unless the 1855117395Skan@option{-traditional-cpp} option is used. 185690075Sobrien 1857117395SkanThis macro is not defined if the @option{-traditional-cpp} option is used. 185890075Sobrien 185990075SobrienOn some hosts, the system compiler uses a different convention, where 186090075Sobrien@code{__STDC__} is normally 0, but is 1 if the user specifies strict 1861117395Skanconformance to the C Standard. CPP follows the host convention when 186290075Sobrienprocessing system header files, but when processing user files 186390075Sobrien@code{__STDC__} is always 1. This has been reported to cause problems; 186490075Sobrienfor instance, some versions of Solaris provide X Windows headers that 1865104752Skanexpect @code{__STDC__} to be either undefined or 1. @xref{Invocation}. 186690075Sobrien 186790075Sobrien@item __STDC_VERSION__ 186890075SobrienThis macro expands to the C Standard's version number, a long integer 186990075Sobrienconstant of the form @code{@var{yyyy}@var{mm}L} where @var{yyyy} and 187090075Sobrien@var{mm} are the year and month of the Standard version. This signifies 187190075Sobrienwhich version of the C Standard the compiler conforms to. Like 187290075Sobrien@code{__STDC__}, this is not necessarily accurate for the entire 187390075Sobrienimplementation, unless GNU CPP is being used with GCC@. 187490075Sobrien 187590075SobrienThe value @code{199409L} signifies the 1989 C standard as amended in 187690075Sobrien1994, which is the current default; the value @code{199901L} signifies 187790075Sobrienthe 1999 revision of the C standard. Support for the 1999 revision is 187890075Sobriennot yet complete. 187990075Sobrien 1880117395SkanThis macro is not defined if the @option{-traditional-cpp} option is 1881220755Sdimused, nor when compiling C++. 188290075Sobrien 188390075Sobrien@item __STDC_HOSTED__ 188490075SobrienThis macro is defined, with value 1, if the compiler's target is a 188590075Sobrien@dfn{hosted environment}. A hosted environment has the complete 188690075Sobrienfacilities of the standard C library available. 188790075Sobrien 188890075Sobrien@item __cplusplus 188990075SobrienThis macro is defined when the C++ compiler is in use. You can use 189090075Sobrien@code{__cplusplus} to test whether a header is compiled by a C compiler 189190075Sobrienor a C++ compiler. This macro is similar to @code{__STDC_VERSION__}, in 189290075Sobrienthat it expands to a version number. A fully conforming implementation 189390075Sobrienof the 1998 C++ standard will define this macro to @code{199711L}. The 189490075SobrienGNU C++ compiler is not yet fully conforming, so it uses @code{1} 1895132718Skaninstead. It is hoped to complete the implementation of standard C++ 1896132718Skanin the near future. 189790075Sobrien 1898119256Skan@item __ASSEMBLER__ 1899119256SkanThis macro is defined with value 1 when preprocessing assembly 1900119256Skanlanguage. 1901119256Skan 190290075Sobrien@end table 190390075Sobrien 190490075Sobrien@node Common Predefined Macros 190590075Sobrien@subsection Common Predefined Macros 190690075Sobrien@cindex common predefined macros 190790075Sobrien 190890075SobrienThe common predefined macros are GNU C extensions. They are available 190990075Sobrienwith the same meanings regardless of the machine or operating system on 191090075Sobrienwhich you are using GNU C@. Their names all start with double 191190075Sobrienunderscores. 191290075Sobrien 191390075Sobrien@table @code 191490075Sobrien 191590075Sobrien@item __GNUC__ 191690075Sobrien@itemx __GNUC_MINOR__ 191790075Sobrien@itemx __GNUC_PATCHLEVEL__ 191890075SobrienThese macros are defined by all GNU compilers that use the C 1919220755Sdimpreprocessor: C and C++. Their values are the major version, minor 1920220755Sdimversion, and patch level of the compiler, as integer constants. For 1921220755Sdimexample, GCC 3.2.1 will define @code{__GNUC__} to 3, 1922169689Skan@code{__GNUC_MINOR__} to 2, and @code{__GNUC_PATCHLEVEL__} to 1. These 1923169689Skanmacros are also defined if you invoke the preprocessor directly. 192490075Sobrien 192590075Sobrien@code{__GNUC_PATCHLEVEL__} is new to GCC 3.0; it is also present in the 192690075Sobrienwidely-used development snapshots leading up to 3.0 (which identify 192790075Sobrienthemselves as GCC 2.96 or 2.97, depending on which snapshot you have). 192890075Sobrien 192990075SobrienIf all you need to know is whether or not your program is being compiled 1930169689Skanby GCC, or a non-GCC compiler that claims to accept the GNU C dialects, 1931169689Skanyou can simply test @code{__GNUC__}. If you need to write code 193290075Sobrienwhich depends on a specific version, you must be more careful. Each 193390075Sobrientime the minor version is increased, the patch level is reset to zero; 193490075Sobrieneach time the major version is increased (which happens rarely), the 193590075Sobrienminor version and patch level are reset. If you wish to use the 193690075Sobrienpredefined macros directly in the conditional, you will need to write it 193790075Sobrienlike this: 193890075Sobrien 1939132718Skan@smallexample 194090075Sobrien/* @r{Test for GCC > 3.2.0} */ 194190075Sobrien#if __GNUC__ > 3 || \ 194290075Sobrien (__GNUC__ == 3 && (__GNUC_MINOR__ > 2 || \ 194390075Sobrien (__GNUC_MINOR__ == 2 && \ 194490075Sobrien __GNUC_PATCHLEVEL__ > 0)) 1945132718Skan@end smallexample 194690075Sobrien 194790075Sobrien@noindent 194890075SobrienAnother approach is to use the predefined macros to 194990075Sobriencalculate a single number, then compare that against a threshold: 195090075Sobrien 1951132718Skan@smallexample 195290075Sobrien#define GCC_VERSION (__GNUC__ * 10000 \ 195390075Sobrien + __GNUC_MINOR__ * 100 \ 195490075Sobrien + __GNUC_PATCHLEVEL__) 195590075Sobrien@dots{} 195690075Sobrien/* @r{Test for GCC > 3.2.0} */ 195790075Sobrien#if GCC_VERSION > 30200 1958132718Skan@end smallexample 195990075Sobrien 196090075Sobrien@noindent 196190075SobrienMany people find this form easier to understand. 196290075Sobrien 196390075Sobrien@item __GNUG__ 196490075SobrienThe GNU C++ compiler defines this. Testing it is equivalent to 196590075Sobrientesting @code{@w{(__GNUC__ && __cplusplus)}}. 196690075Sobrien 196790075Sobrien@item __STRICT_ANSI__ 196890075SobrienGCC defines this macro if and only if the @option{-ansi} switch, or a 196990075Sobrien@option{-std} switch specifying strict conformance to some version of ISO C, 197090075Sobrienwas specified when GCC was invoked. It is defined to @samp{1}. 197190075SobrienThis macro exists primarily to direct GNU libc's header files to 197290075Sobrienrestrict their definitions to the minimal set found in the 1989 C 197390075Sobrienstandard. 197490075Sobrien 197590075Sobrien@item __BASE_FILE__ 197690075SobrienThis macro expands to the name of the main input file, in the form 197790075Sobrienof a C string constant. This is the source file that was specified 197890075Sobrienon the command line of the preprocessor or C compiler. 197990075Sobrien 198090075Sobrien@item __INCLUDE_LEVEL__ 198190075SobrienThis macro expands to a decimal integer constant that represents the 198290075Sobriendepth of nesting in include files. The value of this macro is 198390075Sobrienincremented on every @samp{#include} directive and decremented at the 198490075Sobrienend of every included file. It starts out at 0, it's value within the 198590075Sobrienbase file specified on the command line. 198690075Sobrien 1987119256Skan@item __ELF__ 1988119256SkanThis macro is defined if the target uses the ELF object format. 1989119256Skan 199090075Sobrien@item __VERSION__ 199190075SobrienThis macro expands to a string constant which describes the version of 199290075Sobrienthe compiler in use. You should not rely on its contents having any 199390075Sobrienparticular form, but it can be counted on to contain at least the 199490075Sobrienrelease number. 199590075Sobrien 199690075Sobrien@item __OPTIMIZE__ 199790075Sobrien@itemx __OPTIMIZE_SIZE__ 199890075Sobrien@itemx __NO_INLINE__ 199990075SobrienThese macros describe the compilation mode. @code{__OPTIMIZE__} is 200090075Sobriendefined in all optimizing compilations. @code{__OPTIMIZE_SIZE__} is 200190075Sobriendefined if the compiler is optimizing for size, not speed. 200290075Sobrien@code{__NO_INLINE__} is defined if no functions will be inlined into 200390075Sobrientheir callers (when not optimizing, or when inlining has been 200490075Sobrienspecifically disabled by @option{-fno-inline}). 200590075Sobrien 200690075SobrienThese macros cause certain GNU header files to provide optimized 200790075Sobriendefinitions, using macros or inline functions, of system library 200890075Sobrienfunctions. You should not use these macros in any way unless you make 200990075Sobriensure that programs will execute with the same effect whether or not they 201090075Sobrienare defined. If they are defined, their value is 1. 201190075Sobrien 2012169689Skan@item __GNUC_GNU_INLINE__ 2013169689SkanGCC defines this macro if functions declared @code{inline} will be 2014169689Skanhandled in GCC's traditional gnu89 mode. In this mode an @code{extern 2015169689Skaninline} function will never be compiled as a standalone function, and 2016169689Skanan @code{inline} function which is neither @code{extern} nor 2017169689Skan@code{static} will always be compiled as a standalone function. 2018169689Skan 2019169689Skan@item __GNUC_STDC_INLINE__ 2020169689SkanGCC defines this macro if functions declared @code{inline} will be 2021169689Skanhandled according to the ISO C99 standard. In this mode an 2022169689Skan@code{extern inline} function will always be compiled as a standalone 2023169689Skanexternally visible function, and an @code{inline} function which is 2024169689Skanneither @code{extern} nor @code{static} will never be compiled as a 2025169689Skanstandalone function. 2026169689Skan 2027169689SkanIf this macro is defined, GCC supports the @code{gnu_inline} function 2028169689Skanattribute as a way to always get the gnu89 behaviour. Support for 2029169689Skanthis and @code{__GNUC_GNU_INLINE__} was added in GCC 4.1.3. If 2030169689Skanneither macro is defined, an older version of GCC is being used: 2031169689Skan@code{inline} functions will be compiled in gnu89 mode, and the 2032169689Skan@code{gnu_inline} function attribute will not be recognized. 2033169689Skan 203490075Sobrien@item __CHAR_UNSIGNED__ 203590075SobrienGCC defines this macro if and only if the data type @code{char} is 203690075Sobrienunsigned on the target machine. It exists to cause the standard header 203790075Sobrienfile @file{limits.h} to work correctly. You should not use this macro 203890075Sobrienyourself; instead, refer to the standard macros defined in @file{limits.h}. 203990075Sobrien 2040117395Skan@item __WCHAR_UNSIGNED__ 2041117395SkanLike @code{__CHAR_UNSIGNED__}, this macro is defined if and only if the 2042117395Skandata type @code{wchar_t} is unsigned and the front-end is in C++ mode. 2043117395Skan 204490075Sobrien@item __REGISTER_PREFIX__ 204590075SobrienThis macro expands to a single token (not a string constant) which is 204690075Sobrienthe prefix applied to CPU register names in assembly language for this 204790075Sobrientarget. You can use it to write assembly that is usable in multiple 204890075Sobrienenvironments. For example, in the @code{m68k-aout} environment it 204990075Sobrienexpands to nothing, but in the @code{m68k-coff} environment it expands 205090075Sobriento a single @samp{%}. 205190075Sobrien 205290075Sobrien@item __USER_LABEL_PREFIX__ 205390075SobrienThis macro expands to a single token which is the prefix applied to 205490075Sobrienuser labels (symbols visible to C code) in assembly. For example, in 205590075Sobrienthe @code{m68k-aout} environment it expands to an @samp{_}, but in the 205690075Sobrien@code{m68k-coff} environment it expands to nothing. 205790075Sobrien 205890075SobrienThis macro will have the correct definition even if 205990075Sobrien@option{-f(no-)underscores} is in use, but it will not be correct if 206090075Sobrientarget-specific options that adjust this prefix are used (e.g.@: the 206190075SobrienOSF/rose @option{-mno-underscores} option). 206290075Sobrien 206390075Sobrien@item __SIZE_TYPE__ 206490075Sobrien@itemx __PTRDIFF_TYPE__ 206590075Sobrien@itemx __WCHAR_TYPE__ 206690075Sobrien@itemx __WINT_TYPE__ 2067169689Skan@itemx __INTMAX_TYPE__ 2068169689Skan@itemx __UINTMAX_TYPE__ 206990075SobrienThese macros are defined to the correct underlying types for the 2070169689Skan@code{size_t}, @code{ptrdiff_t}, @code{wchar_t}, @code{wint_t}, 2071169689Skan@code{intmax_t}, and @code{uintmax_t} 207290075Sobrientypedefs, respectively. They exist to make the standard header files 207390075Sobrien@file{stddef.h} and @file{wchar.h} work correctly. You should not use 207490075Sobrienthese macros directly; instead, include the appropriate headers and use 207590075Sobrienthe typedefs. 207690075Sobrien 2077117395Skan@item __CHAR_BIT__ 2078117395SkanDefined to the number of bits used in the representation of the 2079117395Skan@code{char} data type. It exists to make the standard header given 2080117395Skannumerical limits work correctly. You should not use 2081117395Skanthis macro directly; instead, include the appropriate headers. 2082117395Skan 2083117395Skan@item __SCHAR_MAX__ 2084117395Skan@itemx __WCHAR_MAX__ 2085117395Skan@itemx __SHRT_MAX__ 2086117395Skan@itemx __INT_MAX__ 2087117395Skan@itemx __LONG_MAX__ 2088117395Skan@itemx __LONG_LONG_MAX__ 2089169689Skan@itemx __INTMAX_MAX__ 2090132718SkanDefined to the maximum value of the @code{signed char}, @code{wchar_t}, 2091117395Skan@code{signed short}, 2092169689Skan@code{signed int}, @code{signed long}, @code{signed long long}, and 2093169689Skan@code{intmax_t} types 2094117395Skanrespectively. They exist to make the standard header given numerical limits 2095117395Skanwork correctly. You should not use these macros directly; instead, include 2096117395Skanthe appropriate headers. 2097117395Skan 2098169689Skan@item __DEPRECATED 2099169689SkanThis macro is defined, with value 1, when compiling a C++ source file 2100169689Skanwith warnings about deprecated constructs enabled. These warnings are 2101169689Skanenabled by default, but can be disabled with @option{-Wno-deprecated}. 2102169689Skan 2103169689Skan@item __EXCEPTIONS 2104169689SkanThis macro is defined, with value 1, when compiling a C++ source file 2105169689Skanwith exceptions enabled. If @option{-fno-exceptions} was used when 2106169689Skancompiling the file, then this macro will not be defined. 2107169689Skan 210890075Sobrien@item __USING_SJLJ_EXCEPTIONS__ 210990075SobrienThis macro is defined, with value 1, if the compiler uses the old 211090075Sobrienmechanism based on @code{setjmp} and @code{longjmp} for exception 211190075Sobrienhandling. 2112117395Skan 2113169689Skan@item __GXX_WEAK__ 2114169689SkanThis macro is defined when compiling a C++ source file. It has the 2115169689Skanvalue 1 if the compiler will use weak symbols, COMDAT sections, or 2116169689Skanother similar techniques to collapse symbols with ``vague linkage'' 2117169689Skanthat are defined in multiple translation units. If the compiler will 2118169689Skannot collapse such symbols, this macro is defined with value 0. In 2119169689Skangeneral, user code should not need to make use of this macro; the 2120169689Skanpurpose of this macro is to ease implementation of the C++ runtime 2121169689Skanlibrary provided with G++. 2122169689Skan 2123119256Skan@item __LP64__ 2124132718Skan@itemx _LP64 2125119256SkanThese macros are defined, with value 1, if (and only if) the compilation 2126119256Skanis for a target where @code{long int} and pointer both use 64-bits and 2127119256Skan@code{int} uses 32-bit. 2128169689Skan 2129169689Skan@item __SSP__ 2130169689SkanThis macro is defined, with value 1, when @option{-fstack-protector} is in 2131169689Skanuse. 2132169689Skan 2133169689Skan@item __SSP_ALL__ 2134169689SkanThis macro is defined, with value 2, when @option{-fstack-protector-all} is 2135169689Skanin use. 2136169689Skan 2137169689Skan@item __TIMESTAMP__ 2138169689SkanThis macro expands to a string constant that describes the date and time 2139169689Skanof the last modification of the current source file. The string constant 2140169689Skancontains abbreviated day of the week, month, day of the month, time in 2141169689Skanhh:mm:ss form, year and looks like @code{@w{"Sun Sep 16 01:03:52 1973"}}. 2142169689SkanIf the day of the month is less than 10, it is padded with a space on the left. 2143169689Skan 2144169689SkanIf GCC cannot determine the current date, it will emit a warning message 2145169689Skan(once per compilation) and @code{__TIMESTAMP__} will expand to 2146169689Skan@code{@w{"??? ??? ?? ??:??:?? ????"}}. 2147169689Skan 214890075Sobrien@end table 214990075Sobrien 215090075Sobrien@node System-specific Predefined Macros 215190075Sobrien@subsection System-specific Predefined Macros 215290075Sobrien 215390075Sobrien@cindex system-specific predefined macros 215490075Sobrien@cindex predefined macros, system-specific 215590075Sobrien@cindex reserved namespace 215690075Sobrien 215790075SobrienThe C preprocessor normally predefines several macros that indicate what 215890075Sobrientype of system and machine is in use. They are obviously different on 215990075Sobrieneach target supported by GCC@. This manual, being for all systems and 216090075Sobrienmachines, cannot tell you what their names are, but you can use 216190075Sobrien@command{cpp -dM} to see them all. @xref{Invocation}. All system-specific 216290075Sobrienpredefined macros expand to the constant 1, so you can test them with 216390075Sobrieneither @samp{#ifdef} or @samp{#if}. 216490075Sobrien 216590075SobrienThe C standard requires that all system-specific macros be part of the 216690075Sobrien@dfn{reserved namespace}. All names which begin with two underscores, 216790075Sobrienor an underscore and a capital letter, are reserved for the compiler and 216890075Sobrienlibrary to use as they wish. However, historically system-specific 216990075Sobrienmacros have had names with no special prefix; for instance, it is common 217090075Sobriento find @code{unix} defined on Unix systems. For all such macros, GCC 217190075Sobrienprovides a parallel macro with two underscores added at the beginning 217290075Sobrienand the end. If @code{unix} is defined, @code{__unix__} will be defined 217390075Sobrientoo. There will never be more than two underscores; the parallel of 217490075Sobrien@code{_mips} is @code{__mips__}. 217590075Sobrien 217690075SobrienWhen the @option{-ansi} option, or any @option{-std} option that 217790075Sobrienrequests strict conformance, is given to the compiler, all the 217890075Sobriensystem-specific predefined macros outside the reserved namespace are 217990075Sobriensuppressed. The parallel macros, inside the reserved namespace, remain 218090075Sobriendefined. 218190075Sobrien 218290075SobrienWe are slowly phasing out all predefined macros which are outside the 218390075Sobrienreserved namespace. You should never use them in new programs, and we 218490075Sobrienencourage you to correct older code to use the parallel macros whenever 218590075Sobrienyou find it. We don't recommend you use the system-specific macros that 218690075Sobrienare in the reserved namespace, either. It is better in the long run to 218790075Sobriencheck specifically for features you need, using a tool such as 218890075Sobrien@command{autoconf}. 218990075Sobrien 219090075Sobrien@node C++ Named Operators 219190075Sobrien@subsection C++ Named Operators 219290075Sobrien@cindex named operators 219390075Sobrien@cindex C++ named operators 219490075Sobrien@cindex iso646.h 219590075Sobrien 219690075SobrienIn C++, there are eleven keywords which are simply alternate spellings 219790075Sobrienof operators normally written with punctuation. These keywords are 219890075Sobrientreated as such even in the preprocessor. They function as operators in 219990075Sobrien@samp{#if}, and they cannot be defined as macros or poisoned. In C, you 220090075Sobriencan request that those keywords take their C++ meaning by including 220190075Sobrien@file{iso646.h}. That header defines each one as a normal object-like 220290075Sobrienmacro expanding to the appropriate punctuator. 220390075Sobrien 220490075SobrienThese are the named operators and their corresponding punctuators: 220590075Sobrien 220690075Sobrien@multitable {Named Operator} {Punctuator} 220790075Sobrien@item Named Operator @tab Punctuator 220890075Sobrien@item @code{and} @tab @code{&&} 220990075Sobrien@item @code{and_eq} @tab @code{&=} 221090075Sobrien@item @code{bitand} @tab @code{&} 221190075Sobrien@item @code{bitor} @tab @code{|} 221290075Sobrien@item @code{compl} @tab @code{~} 221390075Sobrien@item @code{not} @tab @code{!} 221490075Sobrien@item @code{not_eq} @tab @code{!=} 221590075Sobrien@item @code{or} @tab @code{||} 221690075Sobrien@item @code{or_eq} @tab @code{|=} 221790075Sobrien@item @code{xor} @tab @code{^} 221890075Sobrien@item @code{xor_eq} @tab @code{^=} 221990075Sobrien@end multitable 222090075Sobrien 222190075Sobrien@node Undefining and Redefining Macros 222290075Sobrien@section Undefining and Redefining Macros 222390075Sobrien@cindex undefining macros 222490075Sobrien@cindex redefining macros 222590075Sobrien@findex #undef 222690075Sobrien 222790075SobrienIf a macro ceases to be useful, it may be @dfn{undefined} with the 222890075Sobrien@samp{#undef} directive. @samp{#undef} takes a single argument, the 222990075Sobrienname of the macro to undefine. You use the bare macro name, even if the 223090075Sobrienmacro is function-like. It is an error if anything appears on the line 223190075Sobrienafter the macro name. @samp{#undef} has no effect if the name is not a 223290075Sobrienmacro. 223390075Sobrien 2234132718Skan@smallexample 223590075Sobrien#define FOO 4 223690075Sobrienx = FOO; @expansion{} x = 4; 223790075Sobrien#undef FOO 223890075Sobrienx = FOO; @expansion{} x = FOO; 2239132718Skan@end smallexample 224090075Sobrien 224190075SobrienOnce a macro has been undefined, that identifier may be @dfn{redefined} 224290075Sobrienas a macro by a subsequent @samp{#define} directive. The new definition 224390075Sobrienneed not have any resemblance to the old definition. 224490075Sobrien 224590075SobrienHowever, if an identifier which is currently a macro is redefined, then 224690075Sobrienthe new definition must be @dfn{effectively the same} as the old one. 224790075SobrienTwo macro definitions are effectively the same if: 224890075Sobrien@itemize @bullet 224990075Sobrien@item Both are the same type of macro (object- or function-like). 225090075Sobrien@item All the tokens of the replacement list are the same. 225190075Sobrien@item If there are any parameters, they are the same. 225290075Sobrien@item Whitespace appears in the same places in both. It need not be 225390075Sobrienexactly the same amount of whitespace, though. Remember that comments 225490075Sobriencount as whitespace. 225590075Sobrien@end itemize 225690075Sobrien 225790075Sobrien@noindent 225890075SobrienThese definitions are effectively the same: 2259132718Skan@smallexample 226090075Sobrien#define FOUR (2 + 2) 226190075Sobrien#define FOUR (2 + 2) 2262169689Skan#define FOUR (2 /* @r{two} */ + 2) 2263132718Skan@end smallexample 226490075Sobrien@noindent 226590075Sobrienbut these are not: 2266132718Skan@smallexample 226790075Sobrien#define FOUR (2 + 2) 226890075Sobrien#define FOUR ( 2+2 ) 226990075Sobrien#define FOUR (2 * 2) 227090075Sobrien#define FOUR(score,and,seven,years,ago) (2 + 2) 2271132718Skan@end smallexample 227290075Sobrien 227390075SobrienIf a macro is redefined with a definition that is not effectively the 227490075Sobriensame as the old one, the preprocessor issues a warning and changes the 227590075Sobrienmacro to use the new definition. If the new definition is effectively 227690075Sobrienthe same, the redefinition is silently ignored. This allows, for 227790075Sobrieninstance, two different headers to define a common macro. The 227890075Sobrienpreprocessor will only complain if the definitions do not match. 227990075Sobrien 2280117395Skan@node Directives Within Macro Arguments 2281117395Skan@section Directives Within Macro Arguments 2282117395Skan@cindex macro arguments and directives 2283117395Skan 2284117395SkanOccasionally it is convenient to use preprocessor directives within 2285117395Skanthe arguments of a macro. The C and C++ standards declare that 2286117395Skanbehavior in these cases is undefined. 2287117395Skan 2288117395SkanVersions of CPP prior to 3.2 would reject such constructs with an 2289117395Skanerror message. This was the only syntactic difference between normal 2290117395Skanfunctions and function-like macros, so it seemed attractive to remove 2291117395Skanthis limitation, and people would often be surprised that they could 2292117395Skannot use macros in this way. Moreover, sometimes people would use 2293117395Skanconditional compilation in the argument list to a normal library 2294117395Skanfunction like @samp{printf}, only to find that after a library upgrade 2295117395Skan@samp{printf} had changed to be a function-like macro, and their code 2296117395Skanwould no longer compile. So from version 3.2 we changed CPP to 2297117395Skansuccessfully process arbitrary directives within macro arguments in 2298117395Skanexactly the same way as it would have processed the directive were the 2299117395Skanfunction-like macro invocation not present. 2300117395Skan 2301117395SkanIf, within a macro invocation, that macro is redefined, then the new 2302117395Skandefinition takes effect in time for argument pre-expansion, but the 2303117395Skanoriginal definition is still used for argument replacement. Here is a 2304117395Skanpathological example: 2305117395Skan 2306117395Skan@smallexample 2307117395Skan#define f(x) x x 2308117395Skanf (1 2309117395Skan#undef f 2310117395Skan#define f 2 2311117395Skanf) 2312117395Skan@end smallexample 2313117395Skan 2314117395Skan@noindent 2315117395Skanwhich expands to 2316117395Skan 2317117395Skan@smallexample 2318117395Skan1 2 1 2 2319117395Skan@end smallexample 2320117395Skan 2321117395Skan@noindent 2322117395Skanwith the semantics described above. 2323117395Skan 232490075Sobrien@node Macro Pitfalls 232590075Sobrien@section Macro Pitfalls 232690075Sobrien@cindex problems with macros 232790075Sobrien@cindex pitfalls of macros 232890075Sobrien 232990075SobrienIn this section we describe some special rules that apply to macros and 233090075Sobrienmacro expansion, and point out certain cases in which the rules have 233190075Sobriencounter-intuitive consequences that you must watch out for. 233290075Sobrien 233390075Sobrien@menu 233490075Sobrien* Misnesting:: 233590075Sobrien* Operator Precedence Problems:: 233690075Sobrien* Swallowing the Semicolon:: 233790075Sobrien* Duplication of Side Effects:: 233890075Sobrien* Self-Referential Macros:: 233990075Sobrien* Argument Prescan:: 234090075Sobrien* Newlines in Arguments:: 234190075Sobrien@end menu 234290075Sobrien 234390075Sobrien@node Misnesting 234490075Sobrien@subsection Misnesting 234590075Sobrien 234690075SobrienWhen a macro is called with arguments, the arguments are substituted 234790075Sobrieninto the macro body and the result is checked, together with the rest of 234890075Sobrienthe input file, for more macro calls. It is possible to piece together 234990075Sobriena macro call coming partially from the macro body and partially from the 235090075Sobrienarguments. For example, 235190075Sobrien 2352132718Skan@smallexample 235390075Sobrien#define twice(x) (2*(x)) 235490075Sobrien#define call_with_1(x) x(1) 235590075Sobriencall_with_1 (twice) 235690075Sobrien @expansion{} twice(1) 235790075Sobrien @expansion{} (2*(1)) 2358132718Skan@end smallexample 235990075Sobrien 236090075SobrienMacro definitions do not have to have balanced parentheses. By writing 236190075Sobrienan unbalanced open parenthesis in a macro body, it is possible to create 236290075Sobriena macro call that begins inside the macro body but ends outside of it. 236390075SobrienFor example, 236490075Sobrien 2365132718Skan@smallexample 236690075Sobrien#define strange(file) fprintf (file, "%s %d", 236790075Sobrien@dots{} 236890075Sobrienstrange(stderr) p, 35) 236990075Sobrien @expansion{} fprintf (stderr, "%s %d", p, 35) 2370132718Skan@end smallexample 237190075Sobrien 237290075SobrienThe ability to piece together a macro call can be useful, but the use of 237390075Sobrienunbalanced open parentheses in a macro body is just confusing, and 237490075Sobrienshould be avoided. 237590075Sobrien 237690075Sobrien@node Operator Precedence Problems 237790075Sobrien@subsection Operator Precedence Problems 237890075Sobrien@cindex parentheses in macro bodies 237990075Sobrien 238090075SobrienYou may have noticed that in most of the macro definition examples shown 238190075Sobrienabove, each occurrence of a macro argument name had parentheses around 238290075Sobrienit. In addition, another pair of parentheses usually surround the 238390075Sobrienentire macro definition. Here is why it is best to write macros that 238490075Sobrienway. 238590075Sobrien 238690075SobrienSuppose you define a macro as follows, 238790075Sobrien 2388132718Skan@smallexample 238990075Sobrien#define ceil_div(x, y) (x + y - 1) / y 2390132718Skan@end smallexample 239190075Sobrien 239290075Sobrien@noindent 239390075Sobrienwhose purpose is to divide, rounding up. (One use for this operation is 239490075Sobriento compute how many @code{int} objects are needed to hold a certain 239590075Sobriennumber of @code{char} objects.) Then suppose it is used as follows: 239690075Sobrien 2397132718Skan@smallexample 239890075Sobriena = ceil_div (b & c, sizeof (int)); 239990075Sobrien @expansion{} a = (b & c + sizeof (int) - 1) / sizeof (int); 2400132718Skan@end smallexample 240190075Sobrien 240290075Sobrien@noindent 240390075SobrienThis does not do what is intended. The operator-precedence rules of 240490075SobrienC make it equivalent to this: 240590075Sobrien 2406132718Skan@smallexample 240790075Sobriena = (b & (c + sizeof (int) - 1)) / sizeof (int); 2408132718Skan@end smallexample 240990075Sobrien 241090075Sobrien@noindent 241190075SobrienWhat we want is this: 241290075Sobrien 2413132718Skan@smallexample 241490075Sobriena = ((b & c) + sizeof (int) - 1)) / sizeof (int); 2415132718Skan@end smallexample 241690075Sobrien 241790075Sobrien@noindent 241890075SobrienDefining the macro as 241990075Sobrien 2420132718Skan@smallexample 242190075Sobrien#define ceil_div(x, y) ((x) + (y) - 1) / (y) 2422132718Skan@end smallexample 242390075Sobrien 242490075Sobrien@noindent 242590075Sobrienprovides the desired result. 242690075Sobrien 242790075SobrienUnintended grouping can result in another way. Consider @code{sizeof 242890075Sobrienceil_div(1, 2)}. That has the appearance of a C expression that would 242990075Sobriencompute the size of the type of @code{ceil_div (1, 2)}, but in fact it 243090075Sobrienmeans something very different. Here is what it expands to: 243190075Sobrien 2432132718Skan@smallexample 243390075Sobriensizeof ((1) + (2) - 1) / (2) 2434132718Skan@end smallexample 243590075Sobrien 243690075Sobrien@noindent 243790075SobrienThis would take the size of an integer and divide it by two. The 243890075Sobrienprecedence rules have put the division outside the @code{sizeof} when it 243990075Sobrienwas intended to be inside. 244090075Sobrien 244190075SobrienParentheses around the entire macro definition prevent such problems. 244290075SobrienHere, then, is the recommended way to define @code{ceil_div}: 244390075Sobrien 2444132718Skan@smallexample 244590075Sobrien#define ceil_div(x, y) (((x) + (y) - 1) / (y)) 2446132718Skan@end smallexample 244790075Sobrien 244890075Sobrien@node Swallowing the Semicolon 244990075Sobrien@subsection Swallowing the Semicolon 245090075Sobrien@cindex semicolons (after macro calls) 245190075Sobrien 245290075SobrienOften it is desirable to define a macro that expands into a compound 245390075Sobrienstatement. Consider, for example, the following macro, that advances a 245490075Sobrienpointer (the argument @code{p} says where to find it) across whitespace 245590075Sobriencharacters: 245690075Sobrien 2457132718Skan@smallexample 245890075Sobrien#define SKIP_SPACES(p, limit) \ 245990075Sobrien@{ char *lim = (limit); \ 246090075Sobrien while (p < lim) @{ \ 246190075Sobrien if (*p++ != ' ') @{ \ 246290075Sobrien p--; break; @}@}@} 2463132718Skan@end smallexample 246490075Sobrien 246590075Sobrien@noindent 246690075SobrienHere backslash-newline is used to split the macro definition, which must 246790075Sobrienbe a single logical line, so that it resembles the way such code would 246890075Sobrienbe laid out if not part of a macro definition. 246990075Sobrien 247090075SobrienA call to this macro might be @code{SKIP_SPACES (p, lim)}. Strictly 247190075Sobrienspeaking, the call expands to a compound statement, which is a complete 247290075Sobrienstatement with no need for a semicolon to end it. However, since it 247390075Sobrienlooks like a function call, it minimizes confusion if you can use it 247490075Sobrienlike a function call, writing a semicolon afterward, as in 247590075Sobrien@code{SKIP_SPACES (p, lim);} 247690075Sobrien 247790075SobrienThis can cause trouble before @code{else} statements, because the 247890075Sobriensemicolon is actually a null statement. Suppose you write 247990075Sobrien 2480132718Skan@smallexample 248190075Sobrienif (*p != 0) 248290075Sobrien SKIP_SPACES (p, lim); 248390075Sobrienelse @dots{} 2484132718Skan@end smallexample 248590075Sobrien 248690075Sobrien@noindent 248790075SobrienThe presence of two statements---the compound statement and a null 248890075Sobrienstatement---in between the @code{if} condition and the @code{else} 248990075Sobrienmakes invalid C code. 249090075Sobrien 249190075SobrienThe definition of the macro @code{SKIP_SPACES} can be altered to solve 249290075Sobrienthis problem, using a @code{do @dots{} while} statement. Here is how: 249390075Sobrien 2494132718Skan@smallexample 249590075Sobrien#define SKIP_SPACES(p, limit) \ 249690075Sobriendo @{ char *lim = (limit); \ 249790075Sobrien while (p < lim) @{ \ 249890075Sobrien if (*p++ != ' ') @{ \ 249990075Sobrien p--; break; @}@}@} \ 250090075Sobrienwhile (0) 2501132718Skan@end smallexample 250290075Sobrien 250390075SobrienNow @code{SKIP_SPACES (p, lim);} expands into 250490075Sobrien 2505132718Skan@smallexample 250690075Sobriendo @{@dots{}@} while (0); 2507132718Skan@end smallexample 250890075Sobrien 250990075Sobrien@noindent 251090075Sobrienwhich is one statement. The loop executes exactly once; most compilers 251190075Sobriengenerate no extra code for it. 251290075Sobrien 251390075Sobrien@node Duplication of Side Effects 251490075Sobrien@subsection Duplication of Side Effects 251590075Sobrien 251690075Sobrien@cindex side effects (in macro arguments) 251790075Sobrien@cindex unsafe macros 251890075SobrienMany C programs define a macro @code{min}, for ``minimum'', like this: 251990075Sobrien 2520132718Skan@smallexample 252190075Sobrien#define min(X, Y) ((X) < (Y) ? (X) : (Y)) 2522132718Skan@end smallexample 252390075Sobrien 252490075SobrienWhen you use this macro with an argument containing a side effect, 252590075Sobrienas shown here, 252690075Sobrien 2527132718Skan@smallexample 252890075Sobriennext = min (x + y, foo (z)); 2529132718Skan@end smallexample 253090075Sobrien 253190075Sobrien@noindent 253290075Sobrienit expands as follows: 253390075Sobrien 2534132718Skan@smallexample 253590075Sobriennext = ((x + y) < (foo (z)) ? (x + y) : (foo (z))); 2536132718Skan@end smallexample 253790075Sobrien 253890075Sobrien@noindent 253990075Sobrienwhere @code{x + y} has been substituted for @code{X} and @code{foo (z)} 254090075Sobrienfor @code{Y}. 254190075Sobrien 254290075SobrienThe function @code{foo} is used only once in the statement as it appears 254390075Sobrienin the program, but the expression @code{foo (z)} has been substituted 254490075Sobrientwice into the macro expansion. As a result, @code{foo} might be called 254590075Sobrientwo times when the statement is executed. If it has side effects or if 254690075Sobrienit takes a long time to compute, the results might not be what you 254790075Sobrienintended. We say that @code{min} is an @dfn{unsafe} macro. 254890075Sobrien 254990075SobrienThe best solution to this problem is to define @code{min} in a way that 255090075Sobriencomputes the value of @code{foo (z)} only once. The C language offers 255190075Sobrienno standard way to do this, but it can be done with GNU extensions as 255290075Sobrienfollows: 255390075Sobrien 2554132718Skan@smallexample 255590075Sobrien#define min(X, Y) \ 255690075Sobrien(@{ typeof (X) x_ = (X); \ 255790075Sobrien typeof (Y) y_ = (Y); \ 255890075Sobrien (x_ < y_) ? x_ : y_; @}) 2559132718Skan@end smallexample 256090075Sobrien 256190075SobrienThe @samp{(@{ @dots{} @})} notation produces a compound statement that 256290075Sobrienacts as an expression. Its value is the value of its last statement. 256390075SobrienThis permits us to define local variables and assign each argument to 256490075Sobrienone. The local variables have underscores after their names to reduce 256590075Sobrienthe risk of conflict with an identifier of wider scope (it is impossible 256690075Sobriento avoid this entirely). Now each argument is evaluated exactly once. 256790075Sobrien 256890075SobrienIf you do not wish to use GNU C extensions, the only solution is to be 256990075Sobriencareful when @emph{using} the macro @code{min}. For example, you can 257090075Sobriencalculate the value of @code{foo (z)}, save it in a variable, and use 257190075Sobrienthat variable in @code{min}: 257290075Sobrien 2573132718Skan@smallexample 257490075Sobrien@group 257590075Sobrien#define min(X, Y) ((X) < (Y) ? (X) : (Y)) 257690075Sobrien@dots{} 257790075Sobrien@{ 257890075Sobrien int tem = foo (z); 257990075Sobrien next = min (x + y, tem); 258090075Sobrien@} 258190075Sobrien@end group 2582132718Skan@end smallexample 258390075Sobrien 258490075Sobrien@noindent 258590075Sobrien(where we assume that @code{foo} returns type @code{int}). 258690075Sobrien 258790075Sobrien@node Self-Referential Macros 258890075Sobrien@subsection Self-Referential Macros 258990075Sobrien@cindex self-reference 259090075Sobrien 259190075SobrienA @dfn{self-referential} macro is one whose name appears in its 259290075Sobriendefinition. Recall that all macro definitions are rescanned for more 259390075Sobrienmacros to replace. If the self-reference were considered a use of the 259490075Sobrienmacro, it would produce an infinitely large expansion. To prevent this, 259590075Sobrienthe self-reference is not considered a macro call. It is passed into 2596132718Skanthe preprocessor output unchanged. Consider an example: 259790075Sobrien 2598132718Skan@smallexample 259990075Sobrien#define foo (4 + foo) 2600132718Skan@end smallexample 260190075Sobrien 260290075Sobrien@noindent 260390075Sobrienwhere @code{foo} is also a variable in your program. 260490075Sobrien 260590075SobrienFollowing the ordinary rules, each reference to @code{foo} will expand 260690075Sobrieninto @code{(4 + foo)}; then this will be rescanned and will expand into 260790075Sobrien@code{(4 + (4 + foo))}; and so on until the computer runs out of memory. 260890075Sobrien 260990075SobrienThe self-reference rule cuts this process short after one step, at 261090075Sobrien@code{(4 + foo)}. Therefore, this macro definition has the possibly 261190075Sobrienuseful effect of causing the program to add 4 to the value of @code{foo} 261290075Sobrienwherever @code{foo} is referred to. 261390075Sobrien 261490075SobrienIn most cases, it is a bad idea to take advantage of this feature. A 261590075Sobrienperson reading the program who sees that @code{foo} is a variable will 261690075Sobriennot expect that it is a macro as well. The reader will come across the 261790075Sobrienidentifier @code{foo} in the program and think its value should be that 261890075Sobrienof the variable @code{foo}, whereas in fact the value is four greater. 261990075Sobrien 262090075SobrienOne common, useful use of self-reference is to create a macro which 262190075Sobrienexpands to itself. If you write 262290075Sobrien 2623132718Skan@smallexample 262490075Sobrien#define EPERM EPERM 2625132718Skan@end smallexample 262690075Sobrien 262790075Sobrien@noindent 262890075Sobrienthen the macro @code{EPERM} expands to @code{EPERM}. Effectively, it is 262990075Sobrienleft alone by the preprocessor whenever it's used in running text. You 263090075Sobriencan tell that it's a macro with @samp{#ifdef}. You might do this if you 263190075Sobrienwant to define numeric constants with an @code{enum}, but have 263290075Sobrien@samp{#ifdef} be true for each constant. 263390075Sobrien 263490075SobrienIf a macro @code{x} expands to use a macro @code{y}, and the expansion of 263590075Sobrien@code{y} refers to the macro @code{x}, that is an @dfn{indirect 263690075Sobrienself-reference} of @code{x}. @code{x} is not expanded in this case 263790075Sobrieneither. Thus, if we have 263890075Sobrien 2639132718Skan@smallexample 264090075Sobrien#define x (4 + y) 264190075Sobrien#define y (2 * x) 2642132718Skan@end smallexample 264390075Sobrien 264490075Sobrien@noindent 264590075Sobrienthen @code{x} and @code{y} expand as follows: 264690075Sobrien 2647132718Skan@smallexample 264890075Sobrien@group 264990075Sobrienx @expansion{} (4 + y) 265090075Sobrien @expansion{} (4 + (2 * x)) 265190075Sobrien 265290075Sobrieny @expansion{} (2 * x) 265390075Sobrien @expansion{} (2 * (4 + y)) 265490075Sobrien@end group 2655132718Skan@end smallexample 265690075Sobrien 265790075Sobrien@noindent 265890075SobrienEach macro is expanded when it appears in the definition of the other 265990075Sobrienmacro, but not when it indirectly appears in its own definition. 266090075Sobrien 266190075Sobrien@node Argument Prescan 266290075Sobrien@subsection Argument Prescan 266390075Sobrien@cindex expansion of arguments 266490075Sobrien@cindex macro argument expansion 266590075Sobrien@cindex prescan of macro arguments 266690075Sobrien 266790075SobrienMacro arguments are completely macro-expanded before they are 266890075Sobriensubstituted into a macro body, unless they are stringified or pasted 266990075Sobrienwith other tokens. After substitution, the entire macro body, including 267090075Sobrienthe substituted arguments, is scanned again for macros to be expanded. 267190075SobrienThe result is that the arguments are scanned @emph{twice} to expand 267290075Sobrienmacro calls in them. 267390075Sobrien 267490075SobrienMost of the time, this has no effect. If the argument contained any 267590075Sobrienmacro calls, they are expanded during the first scan. The result 267690075Sobrientherefore contains no macro calls, so the second scan does not change 267790075Sobrienit. If the argument were substituted as given, with no prescan, the 267890075Sobriensingle remaining scan would find the same macro calls and produce the 267990075Sobriensame results. 268090075Sobrien 268190075SobrienYou might expect the double scan to change the results when a 268290075Sobrienself-referential macro is used in an argument of another macro 268390075Sobrien(@pxref{Self-Referential Macros}): the self-referential macro would be 268490075Sobrienexpanded once in the first scan, and a second time in the second scan. 268590075SobrienHowever, this is not what happens. The self-references that do not 268690075Sobrienexpand in the first scan are marked so that they will not expand in the 268790075Sobriensecond scan either. 268890075Sobrien 268990075SobrienYou might wonder, ``Why mention the prescan, if it makes no difference? 269090075SobrienAnd why not skip it and make the preprocessor faster?'' The answer is 269190075Sobrienthat the prescan does make a difference in three special cases: 269290075Sobrien 269390075Sobrien@itemize @bullet 269490075Sobrien@item 269590075SobrienNested calls to a macro. 269690075Sobrien 269790075SobrienWe say that @dfn{nested} calls to a macro occur when a macro's argument 269890075Sobriencontains a call to that very macro. For example, if @code{f} is a macro 269990075Sobrienthat expects one argument, @code{f (f (1))} is a nested pair of calls to 270090075Sobrien@code{f}. The desired expansion is made by expanding @code{f (1)} and 270190075Sobriensubstituting that into the definition of @code{f}. The prescan causes 270290075Sobrienthe expected result to happen. Without the prescan, @code{f (1)} itself 270390075Sobrienwould be substituted as an argument, and the inner use of @code{f} would 270490075Sobrienappear during the main scan as an indirect self-reference and would not 270590075Sobrienbe expanded. 270690075Sobrien 270790075Sobrien@item 270890075SobrienMacros that call other macros that stringify or concatenate. 270990075Sobrien 271090075SobrienIf an argument is stringified or concatenated, the prescan does not 271190075Sobrienoccur. If you @emph{want} to expand a macro, then stringify or 271290075Sobrienconcatenate its expansion, you can do that by causing one macro to call 271390075Sobrienanother macro that does the stringification or concatenation. For 271490075Sobrieninstance, if you have 271590075Sobrien 2716132718Skan@smallexample 271790075Sobrien#define AFTERX(x) X_ ## x 271890075Sobrien#define XAFTERX(x) AFTERX(x) 271990075Sobrien#define TABLESIZE 1024 272090075Sobrien#define BUFSIZE TABLESIZE 2721132718Skan@end smallexample 272290075Sobrien 272390075Sobrienthen @code{AFTERX(BUFSIZE)} expands to @code{X_BUFSIZE}, and 272490075Sobrien@code{XAFTERX(BUFSIZE)} expands to @code{X_1024}. (Not to 272590075Sobrien@code{X_TABLESIZE}. Prescan always does a complete expansion.) 272690075Sobrien 272790075Sobrien@item 272890075SobrienMacros used in arguments, whose expansions contain unshielded commas. 272990075Sobrien 273090075SobrienThis can cause a macro expanded on the second scan to be called with the 273190075Sobrienwrong number of arguments. Here is an example: 273290075Sobrien 2733132718Skan@smallexample 273490075Sobrien#define foo a,b 273590075Sobrien#define bar(x) lose(x) 273690075Sobrien#define lose(x) (1 + (x)) 2737132718Skan@end smallexample 273890075Sobrien 273990075SobrienWe would like @code{bar(foo)} to turn into @code{(1 + (foo))}, which 274090075Sobrienwould then turn into @code{(1 + (a,b))}. Instead, @code{bar(foo)} 274190075Sobrienexpands into @code{lose(a,b)}, and you get an error because @code{lose} 274290075Sobrienrequires a single argument. In this case, the problem is easily solved 274390075Sobrienby the same parentheses that ought to be used to prevent misnesting of 274490075Sobrienarithmetic operations: 274590075Sobrien 2746132718Skan@smallexample 274790075Sobrien#define foo (a,b) 274890075Sobrien@exdent or 274990075Sobrien#define bar(x) lose((x)) 2750132718Skan@end smallexample 275190075Sobrien 275290075SobrienThe extra pair of parentheses prevents the comma in @code{foo}'s 275390075Sobriendefinition from being interpreted as an argument separator. 275490075Sobrien 275590075Sobrien@end itemize 275690075Sobrien 275790075Sobrien@node Newlines in Arguments 275890075Sobrien@subsection Newlines in Arguments 275990075Sobrien@cindex newlines in macro arguments 276090075Sobrien 276190075SobrienThe invocation of a function-like macro can extend over many logical 276290075Sobrienlines. However, in the present implementation, the entire expansion 276390075Sobriencomes out on one line. Thus line numbers emitted by the compiler or 276490075Sobriendebugger refer to the line the invocation started on, which might be 276590075Sobriendifferent to the line containing the argument causing the problem. 276690075Sobrien 276790075SobrienHere is an example illustrating this: 276890075Sobrien 2769132718Skan@smallexample 277090075Sobrien#define ignore_second_arg(a,b,c) a; c 277190075Sobrien 277290075Sobrienignore_second_arg (foo (), 277390075Sobrien ignored (), 277490075Sobrien syntax error); 2775132718Skan@end smallexample 277690075Sobrien 277790075Sobrien@noindent 277890075SobrienThe syntax error triggered by the tokens @code{syntax error} results in 277990075Sobrienan error message citing line three---the line of ignore_second_arg--- 278090075Sobrieneven though the problematic code comes from line five. 278190075Sobrien 278290075SobrienWe consider this a bug, and intend to fix it in the near future. 278390075Sobrien 278490075Sobrien@node Conditionals 278590075Sobrien@chapter Conditionals 278690075Sobrien@cindex conditionals 278790075Sobrien 278890075SobrienA @dfn{conditional} is a directive that instructs the preprocessor to 278990075Sobrienselect whether or not to include a chunk of code in the final token 279090075Sobrienstream passed to the compiler. Preprocessor conditionals can test 279190075Sobrienarithmetic expressions, or whether a name is defined as a macro, or both 279290075Sobriensimultaneously using the special @code{defined} operator. 279390075Sobrien 279490075SobrienA conditional in the C preprocessor resembles in some ways an @code{if} 279590075Sobrienstatement in C, but it is important to understand the difference between 279690075Sobrienthem. The condition in an @code{if} statement is tested during the 279790075Sobrienexecution of your program. Its purpose is to allow your program to 279890075Sobrienbehave differently from run to run, depending on the data it is 279990075Sobrienoperating on. The condition in a preprocessing conditional directive is 280090075Sobrientested when your program is compiled. Its purpose is to allow different 280190075Sobriencode to be included in the program depending on the situation at the 280290075Sobrientime of compilation. 280390075Sobrien 280490075SobrienHowever, the distinction is becoming less clear. Modern compilers often 280590075Sobriendo test @code{if} statements when a program is compiled, if their 280690075Sobrienconditions are known not to vary at run time, and eliminate code which 280790075Sobriencan never be executed. If you can count on your compiler to do this, 280890075Sobrienyou may find that your program is more readable if you use @code{if} 280990075Sobrienstatements with constant conditions (perhaps determined by macros). Of 281090075Sobriencourse, you can only use this to exclude code, not type definitions or 281190075Sobrienother preprocessing directives, and you can only do it if the code 281290075Sobrienremains syntactically valid when it is not to be used. 281390075Sobrien 281490075SobrienGCC version 3 eliminates this kind of never-executed code even when 281590075Sobriennot optimizing. Older versions did it only when optimizing. 281690075Sobrien 281790075Sobrien@menu 281890075Sobrien* Conditional Uses:: 281990075Sobrien* Conditional Syntax:: 282090075Sobrien* Deleted Code:: 282190075Sobrien@end menu 282290075Sobrien 282390075Sobrien@node Conditional Uses 282490075Sobrien@section Conditional Uses 282590075Sobrien 282690075SobrienThere are three general reasons to use a conditional. 282790075Sobrien 282890075Sobrien@itemize @bullet 282990075Sobrien@item 283090075SobrienA program may need to use different code depending on the machine or 283190075Sobrienoperating system it is to run on. In some cases the code for one 283290075Sobrienoperating system may be erroneous on another operating system; for 283390075Sobrienexample, it might refer to data types or constants that do not exist on 283490075Sobrienthe other system. When this happens, it is not enough to avoid 283590075Sobrienexecuting the invalid code. Its mere presence will cause the compiler 283690075Sobriento reject the program. With a preprocessing conditional, the offending 283790075Sobriencode can be effectively excised from the program when it is not valid. 283890075Sobrien 283990075Sobrien@item 284090075SobrienYou may want to be able to compile the same source file into two 284190075Sobriendifferent programs. One version might make frequent time-consuming 284290075Sobrienconsistency checks on its intermediate data, or print the values of 284390075Sobrienthose data for debugging, and the other not. 284490075Sobrien 284590075Sobrien@item 284690075SobrienA conditional whose condition is always false is one way to exclude code 284790075Sobrienfrom the program but keep it as a sort of comment for future reference. 284890075Sobrien@end itemize 284990075Sobrien 285090075SobrienSimple programs that do not need system-specific logic or complex 285190075Sobriendebugging hooks generally will not need to use preprocessing 285290075Sobrienconditionals. 285390075Sobrien 285490075Sobrien@node Conditional Syntax 285590075Sobrien@section Conditional Syntax 285690075Sobrien 285790075Sobrien@findex #if 285890075SobrienA conditional in the C preprocessor begins with a @dfn{conditional 285990075Sobriendirective}: @samp{#if}, @samp{#ifdef} or @samp{#ifndef}. 286090075Sobrien 286190075Sobrien@menu 286290075Sobrien* Ifdef:: 286390075Sobrien* If:: 286490075Sobrien* Defined:: 286590075Sobrien* Else:: 286690075Sobrien* Elif:: 286790075Sobrien@end menu 286890075Sobrien 286990075Sobrien@node Ifdef 287090075Sobrien@subsection Ifdef 287190075Sobrien@findex #ifdef 287290075Sobrien@findex #endif 287390075Sobrien 287490075SobrienThe simplest sort of conditional is 287590075Sobrien 2876132718Skan@smallexample 287790075Sobrien@group 287890075Sobrien#ifdef @var{MACRO} 287990075Sobrien 288090075Sobrien@var{controlled text} 288190075Sobrien 288290075Sobrien#endif /* @var{MACRO} */ 288390075Sobrien@end group 2884132718Skan@end smallexample 288590075Sobrien 288690075Sobrien@cindex conditional group 288790075SobrienThis block is called a @dfn{conditional group}. @var{controlled text} 288890075Sobrienwill be included in the output of the preprocessor if and only if 288990075Sobrien@var{MACRO} is defined. We say that the conditional @dfn{succeeds} if 289090075Sobrien@var{MACRO} is defined, @dfn{fails} if it is not. 289190075Sobrien 289290075SobrienThe @var{controlled text} inside of a conditional can include 289390075Sobrienpreprocessing directives. They are executed only if the conditional 289490075Sobriensucceeds. You can nest conditional groups inside other conditional 289590075Sobriengroups, but they must be completely nested. In other words, 289690075Sobrien@samp{#endif} always matches the nearest @samp{#ifdef} (or 289790075Sobrien@samp{#ifndef}, or @samp{#if}). Also, you cannot start a conditional 289890075Sobriengroup in one file and end it in another. 289990075Sobrien 290090075SobrienEven if a conditional fails, the @var{controlled text} inside it is 290190075Sobrienstill run through initial transformations and tokenization. Therefore, 290290075Sobrienit must all be lexically valid C@. Normally the only way this matters is 290390075Sobrienthat all comments and string literals inside a failing conditional group 290490075Sobrienmust still be properly ended. 290590075Sobrien 290690075SobrienThe comment following the @samp{#endif} is not required, but it is a 290790075Sobriengood practice if there is a lot of @var{controlled text}, because it 290890075Sobrienhelps people match the @samp{#endif} to the corresponding @samp{#ifdef}. 290990075SobrienOlder programs sometimes put @var{MACRO} directly after the 291090075Sobrien@samp{#endif} without enclosing it in a comment. This is invalid code 2911117395Skanaccording to the C standard. CPP accepts it with a warning. It 291290075Sobriennever affects which @samp{#ifndef} the @samp{#endif} matches. 291390075Sobrien 291490075Sobrien@findex #ifndef 291590075SobrienSometimes you wish to use some code if a macro is @emph{not} defined. 291690075SobrienYou can do this by writing @samp{#ifndef} instead of @samp{#ifdef}. 291790075SobrienOne common use of @samp{#ifndef} is to include code only the first 291890075Sobrientime a header file is included. @xref{Once-Only Headers}. 291990075Sobrien 292090075SobrienMacro definitions can vary between compilations for several reasons. 292190075SobrienHere are some samples. 292290075Sobrien 292390075Sobrien@itemize @bullet 292490075Sobrien@item 292590075SobrienSome macros are predefined on each kind of machine 292690075Sobrien(@pxref{System-specific Predefined Macros}). This allows you to provide 292790075Sobriencode specially tuned for a particular machine. 292890075Sobrien 292990075Sobrien@item 293090075SobrienSystem header files define more macros, associated with the features 293190075Sobrienthey implement. You can test these macros with conditionals to avoid 293290075Sobrienusing a system feature on a machine where it is not implemented. 293390075Sobrien 293490075Sobrien@item 293590075SobrienMacros can be defined or undefined with the @option{-D} and @option{-U} 293690075Sobriencommand line options when you compile the program. You can arrange to 293790075Sobriencompile the same source file into two different programs by choosing a 293890075Sobrienmacro name to specify which program you want, writing conditionals to 293990075Sobrientest whether or how this macro is defined, and then controlling the 294090075Sobrienstate of the macro with command line options, perhaps set in the 294190075SobrienMakefile. @xref{Invocation}. 294290075Sobrien 294390075Sobrien@item 294490075SobrienYour program might have a special header file (often called 294590075Sobrien@file{config.h}) that is adjusted when the program is compiled. It can 294690075Sobriendefine or not define macros depending on the features of the system and 294790075Sobrienthe desired capabilities of the program. The adjustment can be 294890075Sobrienautomated by a tool such as @command{autoconf}, or done by hand. 294990075Sobrien@end itemize 295090075Sobrien 295190075Sobrien@node If 295290075Sobrien@subsection If 295390075Sobrien 295490075SobrienThe @samp{#if} directive allows you to test the value of an arithmetic 295590075Sobrienexpression, rather than the mere existence of one macro. Its syntax is 295690075Sobrien 2957132718Skan@smallexample 295890075Sobrien@group 295990075Sobrien#if @var{expression} 296090075Sobrien 296190075Sobrien@var{controlled text} 296290075Sobrien 296390075Sobrien#endif /* @var{expression} */ 296490075Sobrien@end group 2965132718Skan@end smallexample 296690075Sobrien 296790075Sobrien@var{expression} is a C expression of integer type, subject to stringent 296890075Sobrienrestrictions. It may contain 296990075Sobrien 297090075Sobrien@itemize @bullet 297190075Sobrien@item 297290075SobrienInteger constants. 297390075Sobrien 297490075Sobrien@item 297590075SobrienCharacter constants, which are interpreted as they would be in normal 297690075Sobriencode. 297790075Sobrien 297890075Sobrien@item 297990075SobrienArithmetic operators for addition, subtraction, multiplication, 298090075Sobriendivision, bitwise operations, shifts, comparisons, and logical 298190075Sobrienoperations (@code{&&} and @code{||}). The latter two obey the usual 298290075Sobrienshort-circuiting rules of standard C@. 298390075Sobrien 298490075Sobrien@item 298590075SobrienMacros. All macros in the expression are expanded before actual 298690075Sobriencomputation of the expression's value begins. 298790075Sobrien 298890075Sobrien@item 298990075SobrienUses of the @code{defined} operator, which lets you check whether macros 299090075Sobrienare defined in the middle of an @samp{#if}. 299190075Sobrien 299290075Sobrien@item 299390075SobrienIdentifiers that are not macros, which are all considered to be the 299490075Sobriennumber zero. This allows you to write @code{@w{#if MACRO}} instead of 299590075Sobrien@code{@w{#ifdef MACRO}}, if you know that MACRO, when defined, will 299690075Sobrienalways have a nonzero value. Function-like macros used without their 299790075Sobrienfunction call parentheses are also treated as zero. 299890075Sobrien 299990075SobrienIn some contexts this shortcut is undesirable. The @option{-Wundef} 300090075Sobrienoption causes GCC to warn whenever it encounters an identifier which is 300190075Sobriennot a macro in an @samp{#if}. 300290075Sobrien@end itemize 300390075Sobrien 300490075SobrienThe preprocessor does not know anything about types in the language. 300590075SobrienTherefore, @code{sizeof} operators are not recognized in @samp{#if}, and 300690075Sobrienneither are @code{enum} constants. They will be taken as identifiers 300790075Sobrienwhich are not macros, and replaced by zero. In the case of 300890075Sobrien@code{sizeof}, this is likely to cause the expression to be invalid. 300990075Sobrien 301090075SobrienThe preprocessor calculates the value of @var{expression}. It carries 301190075Sobrienout all calculations in the widest integer type known to the compiler; 301290075Sobrienon most machines supported by GCC this is 64 bits. This is not the same 301390075Sobrienrule as the compiler uses to calculate the value of a constant 301490075Sobrienexpression, and may give different results in some cases. If the value 301590075Sobriencomes out to be nonzero, the @samp{#if} succeeds and the @var{controlled 301690075Sobrientext} is included; otherwise it is skipped. 301790075Sobrien 301890075Sobrien@node Defined 301990075Sobrien@subsection Defined 302090075Sobrien 302190075Sobrien@cindex @code{defined} 302290075SobrienThe special operator @code{defined} is used in @samp{#if} and 302390075Sobrien@samp{#elif} expressions to test whether a certain name is defined as a 302490075Sobrienmacro. @code{defined @var{name}} and @code{defined (@var{name})} are 302590075Sobrienboth expressions whose value is 1 if @var{name} is defined as a macro at 302690075Sobrienthe current point in the program, and 0 otherwise. Thus, @code{@w{#if 302790075Sobriendefined MACRO}} is precisely equivalent to @code{@w{#ifdef MACRO}}. 302890075Sobrien 302990075Sobrien@code{defined} is useful when you wish to test more than one macro for 303090075Sobrienexistence at once. For example, 303190075Sobrien 3032132718Skan@smallexample 303390075Sobrien#if defined (__vax__) || defined (__ns16000__) 3034132718Skan@end smallexample 303590075Sobrien 303690075Sobrien@noindent 303790075Sobrienwould succeed if either of the names @code{__vax__} or 303890075Sobrien@code{__ns16000__} is defined as a macro. 303990075Sobrien 304090075SobrienConditionals written like this: 304190075Sobrien 3042132718Skan@smallexample 304390075Sobrien#if defined BUFSIZE && BUFSIZE >= 1024 3044132718Skan@end smallexample 304590075Sobrien 304690075Sobrien@noindent 304790075Sobriencan generally be simplified to just @code{@w{#if BUFSIZE >= 1024}}, 304890075Sobriensince if @code{BUFSIZE} is not defined, it will be interpreted as having 304990075Sobrienthe value zero. 305090075Sobrien 305190075SobrienIf the @code{defined} operator appears as a result of a macro expansion, 305290075Sobrienthe C standard says the behavior is undefined. GNU cpp treats it as a 305390075Sobriengenuine @code{defined} operator and evaluates it normally. It will warn 305490075Sobrienwherever your code uses this feature if you use the command-line option 305590075Sobrien@option{-pedantic}, since other compilers may handle it differently. 305690075Sobrien 305790075Sobrien@node Else 305890075Sobrien@subsection Else 305990075Sobrien 306090075Sobrien@findex #else 306190075SobrienThe @samp{#else} directive can be added to a conditional to provide 306290075Sobrienalternative text to be used if the condition fails. This is what it 306390075Sobrienlooks like: 306490075Sobrien 3065132718Skan@smallexample 306690075Sobrien@group 306790075Sobrien#if @var{expression} 306890075Sobrien@var{text-if-true} 306990075Sobrien#else /* Not @var{expression} */ 307090075Sobrien@var{text-if-false} 307190075Sobrien#endif /* Not @var{expression} */ 307290075Sobrien@end group 3073132718Skan@end smallexample 307490075Sobrien 307590075Sobrien@noindent 307690075SobrienIf @var{expression} is nonzero, the @var{text-if-true} is included and 307790075Sobrienthe @var{text-if-false} is skipped. If @var{expression} is zero, the 307890075Sobrienopposite happens. 307990075Sobrien 308090075SobrienYou can use @samp{#else} with @samp{#ifdef} and @samp{#ifndef}, too. 308190075Sobrien 308290075Sobrien@node Elif 308390075Sobrien@subsection Elif 308490075Sobrien 308590075Sobrien@findex #elif 308690075SobrienOne common case of nested conditionals is used to check for more than two 308790075Sobrienpossible alternatives. For example, you might have 308890075Sobrien 3089132718Skan@smallexample 309090075Sobrien#if X == 1 309190075Sobrien@dots{} 309290075Sobrien#else /* X != 1 */ 309390075Sobrien#if X == 2 309490075Sobrien@dots{} 309590075Sobrien#else /* X != 2 */ 309690075Sobrien@dots{} 309790075Sobrien#endif /* X != 2 */ 309890075Sobrien#endif /* X != 1 */ 3099132718Skan@end smallexample 310090075Sobrien 310190075SobrienAnother conditional directive, @samp{#elif}, allows this to be 310290075Sobrienabbreviated as follows: 310390075Sobrien 3104132718Skan@smallexample 310590075Sobrien#if X == 1 310690075Sobrien@dots{} 310790075Sobrien#elif X == 2 310890075Sobrien@dots{} 310990075Sobrien#else /* X != 2 and X != 1*/ 311090075Sobrien@dots{} 311190075Sobrien#endif /* X != 2 and X != 1*/ 3112132718Skan@end smallexample 311390075Sobrien 311490075Sobrien@samp{#elif} stands for ``else if''. Like @samp{#else}, it goes in the 311590075Sobrienmiddle of a conditional group and subdivides it; it does not require a 311690075Sobrienmatching @samp{#endif} of its own. Like @samp{#if}, the @samp{#elif} 311790075Sobriendirective includes an expression to be tested. The text following the 311890075Sobrien@samp{#elif} is processed only if the original @samp{#if}-condition 311990075Sobrienfailed and the @samp{#elif} condition succeeds. 312090075Sobrien 312190075SobrienMore than one @samp{#elif} can go in the same conditional group. Then 312290075Sobrienthe text after each @samp{#elif} is processed only if the @samp{#elif} 312390075Sobriencondition succeeds after the original @samp{#if} and all previous 312490075Sobrien@samp{#elif} directives within it have failed. 312590075Sobrien 312690075Sobrien@samp{#else} is allowed after any number of @samp{#elif} directives, but 312790075Sobrien@samp{#elif} may not follow @samp{#else}. 312890075Sobrien 312990075Sobrien@node Deleted Code 313090075Sobrien@section Deleted Code 313190075Sobrien@cindex commenting out code 313290075Sobrien 313390075SobrienIf you replace or delete a part of the program but want to keep the old 313490075Sobriencode around for future reference, you often cannot simply comment it 313590075Sobrienout. Block comments do not nest, so the first comment inside the old 313690075Sobriencode will end the commenting-out. The probable result is a flood of 313790075Sobriensyntax errors. 313890075Sobrien 313990075SobrienOne way to avoid this problem is to use an always-false conditional 314090075Sobrieninstead. For instance, put @code{#if 0} before the deleted code and 314190075Sobrien@code{#endif} after it. This works even if the code being turned 314290075Sobrienoff contains conditionals, but they must be entire conditionals 314390075Sobrien(balanced @samp{#if} and @samp{#endif}). 314490075Sobrien 314590075SobrienSome people use @code{#ifdef notdef} instead. This is risky, because 314690075Sobrien@code{notdef} might be accidentally defined as a macro, and then the 314790075Sobrienconditional would succeed. @code{#if 0} can be counted on to fail. 314890075Sobrien 314990075SobrienDo not use @code{#if 0} for comments which are not C code. Use a real 315090075Sobriencomment, instead. The interior of @code{#if 0} must consist of complete 315190075Sobrientokens; in particular, single-quote characters must balance. Comments 315290075Sobrienoften contain unbalanced single-quote characters (known in English as 315390075Sobrienapostrophes). These confuse @code{#if 0}. They don't confuse 315490075Sobrien@samp{/*}. 315590075Sobrien 315690075Sobrien@node Diagnostics 315790075Sobrien@chapter Diagnostics 315890075Sobrien@cindex diagnostic 315990075Sobrien@cindex reporting errors 316090075Sobrien@cindex reporting warnings 316190075Sobrien 316290075Sobrien@findex #error 316390075SobrienThe directive @samp{#error} causes the preprocessor to report a fatal 316490075Sobrienerror. The tokens forming the rest of the line following @samp{#error} 316590075Sobrienare used as the error message. 316690075Sobrien 316790075SobrienYou would use @samp{#error} inside of a conditional that detects a 316890075Sobriencombination of parameters which you know the program does not properly 316990075Sobriensupport. For example, if you know that the program will not run 317090075Sobrienproperly on a VAX, you might write 317190075Sobrien 3172132718Skan@smallexample 317390075Sobrien@group 317490075Sobrien#ifdef __vax__ 317590075Sobrien#error "Won't work on VAXen. See comments at get_last_object." 317690075Sobrien#endif 317790075Sobrien@end group 3178132718Skan@end smallexample 317990075Sobrien 318090075SobrienIf you have several configuration parameters that must be set up by 318190075Sobrienthe installation in a consistent way, you can use conditionals to detect 318290075Sobrienan inconsistency and report it with @samp{#error}. For example, 318390075Sobrien 3184132718Skan@smallexample 318590075Sobrien#if !defined(UNALIGNED_INT_ASM_OP) && defined(DWARF2_DEBUGGING_INFO) 318690075Sobrien#error "DWARF2_DEBUGGING_INFO requires UNALIGNED_INT_ASM_OP." 318790075Sobrien#endif 3188132718Skan@end smallexample 318990075Sobrien 319090075Sobrien@findex #warning 319190075SobrienThe directive @samp{#warning} is like @samp{#error}, but causes the 319290075Sobrienpreprocessor to issue a warning and continue preprocessing. The tokens 319390075Sobrienfollowing @samp{#warning} are used as the warning message. 319490075Sobrien 319590075SobrienYou might use @samp{#warning} in obsolete header files, with a message 319690075Sobriendirecting the user to the header file which should be used instead. 319790075Sobrien 319890075SobrienNeither @samp{#error} nor @samp{#warning} macro-expands its argument. 319990075SobrienInternal whitespace sequences are each replaced with a single space. 320090075SobrienThe line must consist of complete tokens. It is wisest to make the 320190075Sobrienargument of these directives be a single string constant; this avoids 320290075Sobrienproblems with apostrophes and the like. 320390075Sobrien 320490075Sobrien@node Line Control 320590075Sobrien@chapter Line Control 320690075Sobrien@cindex line control 320790075Sobrien 320890075SobrienThe C preprocessor informs the C compiler of the location in your source 320990075Sobriencode where each token came from. Presently, this is just the file name 321090075Sobrienand line number. All the tokens resulting from macro expansion are 321190075Sobrienreported as having appeared on the line of the source file where the 321290075Sobrienoutermost macro was used. We intend to be more accurate in the future. 321390075Sobrien 321490075SobrienIf you write a program which generates source code, such as the 321590075Sobrien@command{bison} parser generator, you may want to adjust the preprocessor's 321690075Sobriennotion of the current file name and line number by hand. Parts of the 321790075Sobrienoutput from @command{bison} are generated from scratch, other parts come 321890075Sobrienfrom a standard parser file. The rest are copied verbatim from 321990075Sobrien@command{bison}'s input. You would like compiler error messages and 322090075Sobriensymbolic debuggers to be able to refer to @code{bison}'s input file. 322190075Sobrien 322290075Sobrien@findex #line 322390075Sobrien@command{bison} or any such program can arrange this by writing 322490075Sobrien@samp{#line} directives into the output file. @samp{#line} is a 322590075Sobriendirective that specifies the original line number and source file name 322690075Sobrienfor subsequent input in the current preprocessor input file. 322790075Sobrien@samp{#line} has three variants: 322890075Sobrien 322990075Sobrien@table @code 323090075Sobrien@item #line @var{linenum} 323190075Sobrien@var{linenum} is a non-negative decimal integer constant. It specifies 323290075Sobrienthe line number which should be reported for the following line of 323390075Sobrieninput. Subsequent lines are counted from @var{linenum}. 323490075Sobrien 323590075Sobrien@item #line @var{linenum} @var{filename} 323690075Sobrien@var{linenum} is the same as for the first form, and has the same 323790075Sobrieneffect. In addition, @var{filename} is a string constant. The 323890075Sobrienfollowing line and all subsequent lines are reported to come from the 323990075Sobrienfile it specifies, until something else happens to change that. 324096263Sobrien@var{filename} is interpreted according to the normal rules for a string 324196263Sobrienconstant: backslash escapes are interpreted. This is different from 324296263Sobrien@samp{#include}. 324390075Sobrien 3244117395SkanPrevious versions of CPP did not interpret escapes in @samp{#line}; 324596263Sobrienwe have changed it because the standard requires they be interpreted, 324696263Sobrienand most other compilers do. 324796263Sobrien 324890075Sobrien@item #line @var{anything else} 324990075Sobrien@var{anything else} is checked for macro calls, which are expanded. 325090075SobrienThe result should match one of the above two forms. 325190075Sobrien@end table 325290075Sobrien 325390075Sobrien@samp{#line} directives alter the results of the @code{__FILE__} and 325490075Sobrien@code{__LINE__} predefined macros from that point on. @xref{Standard 325590075SobrienPredefined Macros}. They do not have any effect on @samp{#include}'s 325696263Sobrienidea of the directory containing the current file. This is a change 325796263Sobrienfrom GCC 2.95. Previously, a file reading 325890075Sobrien 325996263Sobrien@smallexample 326096263Sobrien#line 1 "../src/gram.y" 326196263Sobrien#include "gram.h" 326296263Sobrien@end smallexample 326396263Sobrien 326496263Sobrienwould search for @file{gram.h} in @file{../src}, then the @option{-I} 326596263Sobrienchain; the directory containing the physical source file would not be 326696263Sobriensearched. In GCC 3.0 and later, the @samp{#include} is not affected by 326796263Sobrienthe presence of a @samp{#line} referring to a different directory. 326896263Sobrien 326996263SobrienWe made this change because the old behavior caused problems when 327096263Sobriengenerated source files were transported between machines. For instance, 327196263Sobrienit is common practice to ship generated parsers with a source release, 327296263Sobrienso that people building the distribution do not need to have yacc or 327396263SobrienBison installed. These files frequently have @samp{#line} directives 327496263Sobrienreferring to the directory tree of the system where the distribution was 327596263Sobriencreated. If GCC tries to search for headers in those directories, the 327696263Sobrienbuild is likely to fail. 327796263Sobrien 327896263SobrienThe new behavior can cause failures too, if the generated file is not 327996263Sobrienin the same directory as its source and it attempts to include a header 328096263Sobrienwhich would be visible searching from the directory containing the 328196263Sobriensource file. However, this problem is easily solved with an additional 328296263Sobrien@option{-I} switch on the command line. The failures caused by the old 328396263Sobriensemantics could sometimes be corrected only by editing the generated 328496263Sobrienfiles, which is difficult and error-prone. 328596263Sobrien 328690075Sobrien@node Pragmas 328790075Sobrien@chapter Pragmas 328890075Sobrien 328990075SobrienThe @samp{#pragma} directive is the method specified by the C standard 329090075Sobrienfor providing additional information to the compiler, beyond what is 329190075Sobrienconveyed in the language itself. Three forms of this directive 329290075Sobrien(commonly known as @dfn{pragmas}) are specified by the 1999 C standard. 329390075SobrienA C compiler is free to attach any meaning it likes to other pragmas. 329490075Sobrien 329590075SobrienGCC has historically preferred to use extensions to the syntax of the 329690075Sobrienlanguage, such as @code{__attribute__}, for this purpose. However, GCC 329790075Sobriendoes define a few pragmas of its own. These mostly have effects on the 329890075Sobrienentire translation unit or source file. 329990075Sobrien 330090075SobrienIn GCC version 3, all GNU-defined, supported pragmas have been given a 330190075Sobrien@code{GCC} prefix. This is in line with the @code{STDC} prefix on all 330290075Sobrienpragmas defined by C99. For backward compatibility, pragmas which were 330390075Sobrienrecognized by previous versions are still recognized without the 330490075Sobrien@code{GCC} prefix, but that usage is deprecated. Some older pragmas are 330590075Sobriendeprecated in their entirety. They are not recognized with the 330690075Sobrien@code{GCC} prefix. @xref{Obsolete Features}. 330790075Sobrien 330890075Sobrien@cindex @code{_Pragma} 330990075SobrienC99 introduces the @code{@w{_Pragma}} operator. This feature addresses a 331090075Sobrienmajor problem with @samp{#pragma}: being a directive, it cannot be 331190075Sobrienproduced as the result of macro expansion. @code{@w{_Pragma}} is an 331290075Sobrienoperator, much like @code{sizeof} or @code{defined}, and can be embedded 331390075Sobrienin a macro. 331490075Sobrien 331590075SobrienIts syntax is @code{@w{_Pragma (@var{string-literal})}}, where 331690075Sobrien@var{string-literal} can be either a normal or wide-character string 331790075Sobrienliteral. It is destringized, by replacing all @samp{\\} with a single 331890075Sobrien@samp{\} and all @samp{\"} with a @samp{"}. The result is then 331990075Sobrienprocessed as if it had appeared as the right hand side of a 332090075Sobrien@samp{#pragma} directive. For example, 332190075Sobrien 3322132718Skan@smallexample 332390075Sobrien_Pragma ("GCC dependency \"parse.y\"") 3324132718Skan@end smallexample 332590075Sobrien 332690075Sobrien@noindent 332790075Sobrienhas the same effect as @code{#pragma GCC dependency "parse.y"}. The 332890075Sobriensame effect could be achieved using macros, for example 332990075Sobrien 3330132718Skan@smallexample 333190075Sobrien#define DO_PRAGMA(x) _Pragma (#x) 333290075SobrienDO_PRAGMA (GCC dependency "parse.y") 3333132718Skan@end smallexample 333490075Sobrien 333590075SobrienThe standard is unclear on where a @code{_Pragma} operator can appear. 333690075SobrienThe preprocessor does not accept it within a preprocessing conditional 333790075Sobriendirective like @samp{#if}. To be safe, you are probably best keeping it 333890075Sobrienout of directives other than @samp{#define}, and putting it on a line of 333990075Sobrienits own. 334090075Sobrien 334190075SobrienThis manual documents the pragmas which are meaningful to the 334290075Sobrienpreprocessor itself. Other pragmas are meaningful to the C or C++ 334390075Sobriencompilers. They are documented in the GCC manual. 334490075Sobrien 334590075Sobrien@ftable @code 334690075Sobrien@item #pragma GCC dependency 334790075Sobrien@code{#pragma GCC dependency} allows you to check the relative dates of 334890075Sobrienthe current file and another file. If the other file is more recent than 334990075Sobrienthe current file, a warning is issued. This is useful if the current 335090075Sobrienfile is derived from the other file, and should be regenerated. The 335190075Sobrienother file is searched for using the normal include search path. 335290075SobrienOptional trailing text can be used to give more information in the 335390075Sobrienwarning message. 335490075Sobrien 3355132718Skan@smallexample 335690075Sobrien#pragma GCC dependency "parse.y" 335790075Sobrien#pragma GCC dependency "/usr/include/time.h" rerun fixincludes 3358132718Skan@end smallexample 335990075Sobrien 336090075Sobrien@item #pragma GCC poison 336190075SobrienSometimes, there is an identifier that you want to remove completely 336290075Sobrienfrom your program, and make sure that it never creeps back in. To 336390075Sobrienenforce this, you can @dfn{poison} the identifier with this pragma. 336490075Sobrien@code{#pragma GCC poison} is followed by a list of identifiers to 336590075Sobrienpoison. If any of those identifiers appears anywhere in the source 336690075Sobrienafter the directive, it is a hard error. For example, 336790075Sobrien 3368132718Skan@smallexample 336990075Sobrien#pragma GCC poison printf sprintf fprintf 337090075Sobriensprintf(some_string, "hello"); 3371132718Skan@end smallexample 337290075Sobrien 337390075Sobrien@noindent 337490075Sobrienwill produce an error. 337590075Sobrien 337690075SobrienIf a poisoned identifier appears as part of the expansion of a macro 337790075Sobrienwhich was defined before the identifier was poisoned, it will @emph{not} 337890075Sobriencause an error. This lets you poison an identifier without worrying 337990075Sobrienabout system headers defining macros that use it. 338090075Sobrien 338190075SobrienFor example, 338290075Sobrien 3383132718Skan@smallexample 338490075Sobrien#define strrchr rindex 338590075Sobrien#pragma GCC poison rindex 338690075Sobrienstrrchr(some_string, 'h'); 3387132718Skan@end smallexample 338890075Sobrien 338990075Sobrien@noindent 339090075Sobrienwill not produce an error. 339190075Sobrien 339290075Sobrien@item #pragma GCC system_header 339390075SobrienThis pragma takes no arguments. It causes the rest of the code in the 339490075Sobriencurrent file to be treated as if it came from a system header. 339590075Sobrien@xref{System Headers}. 339690075Sobrien 339790075Sobrien@end ftable 339890075Sobrien 339990075Sobrien@node Other Directives 340090075Sobrien@chapter Other Directives 340190075Sobrien 340290075Sobrien@findex #ident 3403169689Skan@findex #sccs 340490075SobrienThe @samp{#ident} directive takes one argument, a string constant. On 340590075Sobriensome systems, that string constant is copied into a special segment of 3406169689Skanthe object file. On other systems, the directive is ignored. The 3407169689Skan@samp{#sccs} directive is a synonym for @samp{#ident}. 340890075Sobrien 3409169689SkanThese directives are not part of the C standard, but they are not 3410169689Skanofficial GNU extensions either. What historical information we have 3411169689Skanbeen able to find, suggests they originated with System V@. 341290075Sobrien 341390075Sobrien@cindex null directive 341490075SobrienThe @dfn{null directive} consists of a @samp{#} followed by a newline, 341590075Sobrienwith only whitespace (including comments) in between. A null directive 341690075Sobrienis understood as a preprocessing directive but has no effect on the 341790075Sobrienpreprocessor output. The primary significance of the existence of the 341890075Sobriennull directive is that an input line consisting of just a @samp{#} will 341990075Sobrienproduce no output, rather than a line of output containing just a 342090075Sobrien@samp{#}. Supposedly some old C programs contain such lines. 342190075Sobrien 342290075Sobrien@node Preprocessor Output 342390075Sobrien@chapter Preprocessor Output 342490075Sobrien 3425220755SdimWhen the C preprocessor is used with the C or C++ compilers, it is 3426220755Sdimintegrated into the compiler and communicates a stream of binary tokens 3427220755Sdimdirectly to the compiler's parser. However, it can also be used in the 3428220755Sdimmore conventional standalone mode, where it produces textual output. 342990075Sobrien@c FIXME: Document the library interface. 343090075Sobrien 343190075Sobrien@cindex output format 343290075SobrienThe output from the C preprocessor looks much like the input, except 343390075Sobrienthat all preprocessing directive lines have been replaced with blank 343490075Sobrienlines and all comments with spaces. Long runs of blank lines are 343590075Sobriendiscarded. 343690075Sobrien 343790075SobrienThe ISO standard specifies that it is implementation defined whether a 343890075Sobrienpreprocessor preserves whitespace between tokens, or replaces it with 343990075Sobriene.g.@: a single space. In GNU CPP, whitespace between tokens is collapsed 344090075Sobriento become a single space, with the exception that the first token on a 344190075Sobriennon-directive line is preceded with sufficient spaces that it appears in 344290075Sobrienthe same column in the preprocessed output that it appeared in the 344390075Sobrienoriginal source file. This is so the output is easy to read. 344490075Sobrien@xref{Differences from previous versions}. CPP does not insert any 344590075Sobrienwhitespace where there was none in the original source, except where 344690075Sobriennecessary to prevent an accidental token paste. 344790075Sobrien 344890075Sobrien@cindex linemarkers 344990075SobrienSource file name and line number information is conveyed by lines 345090075Sobrienof the form 345190075Sobrien 3452132718Skan@smallexample 345390075Sobrien# @var{linenum} @var{filename} @var{flags} 3454132718Skan@end smallexample 345590075Sobrien 345690075Sobrien@noindent 345790075SobrienThese are called @dfn{linemarkers}. They are inserted as needed into 345890075Sobrienthe output (but never within a string or character constant). They mean 345990075Sobrienthat the following line originated in file @var{filename} at line 346096263Sobrien@var{linenum}. @var{filename} will never contain any non-printing 346196263Sobriencharacters; they are replaced with octal escape sequences. 346290075Sobrien 346390075SobrienAfter the file name comes zero or more flags, which are @samp{1}, 346490075Sobrien@samp{2}, @samp{3}, or @samp{4}. If there are multiple flags, spaces 346590075Sobrienseparate them. Here is what the flags mean: 346690075Sobrien 346790075Sobrien@table @samp 346890075Sobrien@item 1 346990075SobrienThis indicates the start of a new file. 347090075Sobrien@item 2 347190075SobrienThis indicates returning to a file (after having included another file). 347290075Sobrien@item 3 347390075SobrienThis indicates that the following text comes from a system header file, 347490075Sobrienso certain warnings should be suppressed. 347590075Sobrien@item 4 347690075SobrienThis indicates that the following text should be treated as being 347790075Sobrienwrapped in an implicit @code{extern "C"} block. 347890075Sobrien@c maybe cross reference NO_IMPLICIT_EXTERN_C 347990075Sobrien@end table 348090075Sobrien 348190075SobrienAs an extension, the preprocessor accepts linemarkers in non-assembler 348290075Sobrieninput files. They are treated like the corresponding @samp{#line} 348390075Sobriendirective, (@pxref{Line Control}), except that trailing flags are 348490075Sobrienpermitted, and are interpreted with the meanings described above. If 348590075Sobrienmultiple flags are given, they must be in ascending order. 348690075Sobrien 348790075SobrienSome directives may be duplicated in the output of the preprocessor. 348890075SobrienThese are @samp{#ident} (always), @samp{#pragma} (only if the 348990075Sobrienpreprocessor does not handle the pragma itself), and @samp{#define} and 349090075Sobrien@samp{#undef} (with certain debugging options). If this happens, the 349190075Sobrien@samp{#} of the directive will always be in the first column, and there 349290075Sobrienwill be no space between the @samp{#} and the directive name. If macro 349390075Sobrienexpansion happens to generate tokens which might be mistaken for a 349490075Sobrienduplicated directive, a space will be inserted between the @samp{#} and 349590075Sobrienthe directive name. 349690075Sobrien 349790075Sobrien@node Traditional Mode 349890075Sobrien@chapter Traditional Mode 349990075Sobrien 350090075SobrienTraditional (pre-standard) C preprocessing is rather different from 350190075Sobrienthe preprocessing specified by the standard. When GCC is given the 3502117395Skan@option{-traditional-cpp} option, it attempts to emulate a traditional 3503117395Skanpreprocessor. 350490075Sobrien 3505117395SkanGCC versions 3.2 and later only support traditional mode semantics in 3506117395Skanthe preprocessor, and not in the compiler front ends. This chapter 3507117395Skanoutlines the traditional preprocessor semantics we implemented. 350890075Sobrien 3509117395SkanThe implementation does not correspond precisely to the behavior of 3510117395Skanearlier versions of GCC, nor to any true traditional preprocessor. 3511117395SkanAfter all, inconsistencies among traditional implementations were a 3512117395Skanmajor motivation for C standardization. However, we intend that it 3513117395Skanshould be compatible with true traditional preprocessors in all ways 3514117395Skanthat actually matter. 351590075Sobrien 3516117395Skan@menu 3517117395Skan* Traditional lexical analysis:: 3518117395Skan* Traditional macros:: 3519117395Skan* Traditional miscellany:: 3520117395Skan* Traditional warnings:: 3521117395Skan@end menu 352290075Sobrien 3523117395Skan@node Traditional lexical analysis 3524117395Skan@section Traditional lexical analysis 352590075Sobrien 3526117395SkanThe traditional preprocessor does not decompose its input into tokens 3527117395Skanthe same way a standards-conforming preprocessor does. The input is 3528117395Skansimply treated as a stream of text with minimal internal form. 352990075Sobrien 3530117395SkanThis implementation does not treat trigraphs (@pxref{trigraphs}) 3531117395Skanspecially since they were an invention of the standards committee. It 3532117395Skanhandles arbitrarily-positioned escaped newlines properly and splices 3533117395Skanthe lines as you would expect; many traditional preprocessors did not 3534117395Skando this. 353590075Sobrien 3536117395SkanThe form of horizontal whitespace in the input file is preserved in 3537117395Skanthe output. In particular, hard tabs remain hard tabs. This can be 3538117395Skanuseful if, for example, you are preprocessing a Makefile. 353990075Sobrien 3540117395SkanTraditional CPP only recognizes C-style block comments, and treats the 3541117395Skan@samp{/*} sequence as introducing a comment only if it lies outside 3542117395Skanquoted text. Quoted text is introduced by the usual single and double 3543117395Skanquotes, and also by an initial @samp{<} in a @code{#include} 3544117395Skandirective. 354590075Sobrien 3546117395SkanTraditionally, comments are completely removed and are not replaced 3547117395Skanwith a space. Since a traditional compiler does its own tokenization 3548117395Skanof the output of the preprocessor, this means that comments can 3549117395Skaneffectively be used as token paste operators. However, comments 3550117395Skanbehave like separators for text handled by the preprocessor itself, 3551117395Skansince it doesn't re-lex its input. For example, in 355290075Sobrien 3553117395Skan@smallexample 3554117395Skan#if foo/**/bar 3555117395Skan@end smallexample 3556117395Skan 3557117395Skan@noindent 3558117395Skan@samp{foo} and @samp{bar} are distinct identifiers and expanded 3559117395Skanseparately if they happen to be macros. In other words, this 3560117395Skandirective is equivalent to 3561117395Skan 3562117395Skan@smallexample 3563117395Skan#if foo bar 3564117395Skan@end smallexample 3565117395Skan 3566117395Skan@noindent 3567117395Skanrather than 3568117395Skan 3569117395Skan@smallexample 3570117395Skan#if foobar 3571117395Skan@end smallexample 3572117395Skan 3573117395SkanGenerally speaking, in traditional mode an opening quote need not have 3574117395Skana matching closing quote. In particular, a macro may be defined with 3575117395Skanreplacement text that contains an unmatched quote. Of course, if you 3576117395Skanattempt to compile preprocessed output containing an unmatched quote 3577117395Skanyou will get a syntax error. 3578117395Skan 3579117395SkanHowever, all preprocessing directives other than @code{#define} 3580117395Skanrequire matching quotes. For example: 3581117395Skan 3582117395Skan@smallexample 3583117395Skan#define m This macro's fine and has an unmatched quote 3584117395Skan"/* This is not a comment. */ 3585169689Skan/* @r{This is a comment. The following #include directive 3586169689Skan is ill-formed.} */ 3587117395Skan#include <stdio.h 3588117395Skan@end smallexample 3589117395Skan 3590117395SkanJust as for the ISO preprocessor, what would be a closing quote can be 3591117395Skanescaped with a backslash to prevent the quoted text from closing. 3592117395Skan 3593117395Skan@node Traditional macros 3594117395Skan@section Traditional macros 3595117395Skan 3596117395SkanThe major difference between traditional and ISO macros is that the 3597117395Skanformer expand to text rather than to a token sequence. CPP removes 3598117395Skanall leading and trailing horizontal whitespace from a macro's 3599117395Skanreplacement text before storing it, but preserves the form of internal 3600117395Skanwhitespace. 3601117395Skan 3602117395SkanOne consequence is that it is legitimate for the replacement text to 3603169689Skancontain an unmatched quote (@pxref{Traditional lexical analysis}). An 3604117395Skanunclosed string or character constant continues into the text 3605117395Skanfollowing the macro call. Similarly, the text at the end of a macro's 3606117395Skanexpansion can run together with the text after the macro invocation to 3607117395Skanproduce a single token. 3608117395Skan 3609117395SkanNormally comments are removed from the replacement text after the 3610117395Skanmacro is expanded, but if the @option{-CC} option is passed on the 3611117395Skancommand line comments are preserved. (In fact, the current 3612117395Skanimplementation removes comments even before saving the macro 3613117395Skanreplacement text, but it careful to do it in such a way that the 3614117395Skanobserved effect is identical even in the function-like macro case.) 3615117395Skan 3616117395SkanThe ISO stringification operator @samp{#} and token paste operator 3617117395Skan@samp{##} have no special meaning. As explained later, an effect 3618117395Skansimilar to these operators can be obtained in a different way. Macro 3619117395Skannames that are embedded in quotes, either from the main file or after 3620117395Skanmacro replacement, do not expand. 3621117395Skan 3622117395SkanCPP replaces an unquoted object-like macro name with its replacement 3623117395Skantext, and then rescans it for further macros to replace. Unlike 3624117395Skanstandard macro expansion, traditional macro expansion has no provision 3625117395Skanto prevent recursion. If an object-like macro appears unquoted in its 3626117395Skanreplacement text, it will be replaced again during the rescan pass, 3627117395Skanand so on @emph{ad infinitum}. GCC detects when it is expanding 3628117395Skanrecursive macros, emits an error message, and continues after the 3629117395Skanoffending macro invocation. 3630117395Skan 3631117395Skan@smallexample 3632117395Skan#define PLUS + 3633117395Skan#define INC(x) PLUS+x 3634117395SkanINC(foo); 3635117395Skan @expansion{} ++foo; 3636117395Skan@end smallexample 3637117395Skan 3638117395SkanFunction-like macros are similar in form but quite different in 3639117395Skanbehavior to their ISO counterparts. Their arguments are contained 3640117395Skanwithin parentheses, are comma-separated, and can cross physical lines. 3641117395SkanCommas within nested parentheses are not treated as argument 3642117395Skanseparators. Similarly, a quote in an argument cannot be left 3643117395Skanunclosed; a following comma or parenthesis that comes before the 3644117395Skanclosing quote is treated like any other character. There is no 3645117395Skanfacility for handling variadic macros. 3646117395Skan 3647117395SkanThis implementation removes all comments from macro arguments, unless 3648117395Skanthe @option{-C} option is given. The form of all other horizontal 3649117395Skanwhitespace in arguments is preserved, including leading and trailing 3650117395Skanwhitespace. In particular 3651117395Skan 3652117395Skan@smallexample 3653117395Skanf( ) 3654117395Skan@end smallexample 3655117395Skan 3656117395Skan@noindent 3657117395Skanis treated as an invocation of the macro @samp{f} with a single 3658117395Skanargument consisting of a single space. If you want to invoke a 3659117395Skanfunction-like macro that takes no arguments, you must not leave any 3660117395Skanwhitespace between the parentheses. 3661117395Skan 3662117395SkanIf a macro argument crosses a new line, the new line is replaced with 3663117395Skana space when forming the argument. If the previous line contained an 3664117395Skanunterminated quote, the following line inherits the quoted state. 3665117395Skan 3666117395SkanTraditional preprocessors replace parameters in the replacement text 3667117395Skanwith their arguments regardless of whether the parameters are within 3668117395Skanquotes or not. This provides a way to stringize arguments. For 3669117395Skanexample 3670117395Skan 3671117395Skan@smallexample 3672117395Skan#define str(x) "x" 3673169689Skanstr(/* @r{A comment} */some text ) 3674117395Skan @expansion{} "some text " 3675117395Skan@end smallexample 3676117395Skan 3677117395Skan@noindent 3678117395SkanNote that the comment is removed, but that the trailing space is 3679117395Skanpreserved. Here is an example of using a comment to effect token 3680117395Skanpasting. 3681117395Skan 3682117395Skan@smallexample 3683117395Skan#define suffix(x) foo_/**/x 3684117395Skansuffix(bar) 3685117395Skan @expansion{} foo_bar 3686117395Skan@end smallexample 3687117395Skan 3688117395Skan@node Traditional miscellany 3689117395Skan@section Traditional miscellany 3690117395Skan 3691117395SkanHere are some things to be aware of when using the traditional 3692117395Skanpreprocessor. 3693117395Skan 3694117395Skan@itemize @bullet 369590075Sobrien@item 3696117395SkanPreprocessing directives are recognized only when their leading 3697117395Skan@samp{#} appears in the first column. There can be no whitespace 3698117395Skanbetween the beginning of the line and the @samp{#}, but whitespace can 3699117395Skanfollow the @samp{#}. 370090075Sobrien 370190075Sobrien@item 3702117395SkanA true traditional C preprocessor does not recognize @samp{#error} or 3703117395Skan@samp{#pragma}, and may not recognize @samp{#elif}. CPP supports all 3704117395Skanthe directives in traditional mode that it supports in ISO mode, 3705117395Skanincluding extensions, with the exception that the effects of 3706117395Skan@samp{#pragma GCC poison} are undefined. 370790075Sobrien 370890075Sobrien@item 3709117395Skan__STDC__ is not defined. 371090075Sobrien 371190075Sobrien@item 3712117395SkanIf you use digraphs the behavior is undefined. 371390075Sobrien 371490075Sobrien@item 3715117395SkanIf a line that looks like a directive appears within macro arguments, 3716117395Skanthe behavior is undefined. 371790075Sobrien 371890075Sobrien@end itemize 371990075Sobrien 3720117395Skan@node Traditional warnings 3721117395Skan@section Traditional warnings 372290075SobrienYou can request warnings about features that did not exist, or worked 372390075Sobriendifferently, in traditional C with the @option{-Wtraditional} option. 3724117395SkanGCC does not warn about features of ISO C which you must use when you 3725117395Skanare using a conforming compiler, such as the @samp{#} and @samp{##} 372690075Sobrienoperators. 372790075Sobrien 372890075SobrienPresently @option{-Wtraditional} warns about: 372990075Sobrien 373090075Sobrien@itemize @bullet 373190075Sobrien@item 373290075SobrienMacro parameters that appear within string literals in the macro body. 373390075SobrienIn traditional C macro replacement takes place within string literals, 373490075Sobrienbut does not in ISO C@. 373590075Sobrien 373690075Sobrien@item 373790075SobrienIn traditional C, some preprocessor directives did not exist. 373890075SobrienTraditional preprocessors would only consider a line to be a directive 373990075Sobrienif the @samp{#} appeared in column 1 on the line. Therefore 374090075Sobrien@option{-Wtraditional} warns about directives that traditional C 374190075Sobrienunderstands but would ignore because the @samp{#} does not appear as the 374290075Sobrienfirst character on the line. It also suggests you hide directives like 374390075Sobrien@samp{#pragma} not understood by traditional C by indenting them. Some 374490075Sobrientraditional implementations would not recognize @samp{#elif}, so it 374590075Sobriensuggests avoiding it altogether. 374690075Sobrien 374790075Sobrien@item 3748117395SkanA function-like macro that appears without an argument list. In some 3749117395Skantraditional preprocessors this was an error. In ISO C it merely means 3750117395Skanthat the macro is not expanded. 375190075Sobrien 375290075Sobrien@item 375390075SobrienThe unary plus operator. This did not exist in traditional C@. 375490075Sobrien 375590075Sobrien@item 375690075SobrienThe @samp{U} and @samp{LL} integer constant suffixes, which were not 375790075Sobrienavailable in traditional C@. (Traditional C does support the @samp{L} 375890075Sobriensuffix for simple long integer constants.) You are not warned about 375990075Sobrienuses of these suffixes in macros defined in system headers. For 376090075Sobrieninstance, @code{UINT_MAX} may well be defined as @code{4294967295U}, but 376190075Sobrienyou will not be warned if you use @code{UINT_MAX}. 376290075Sobrien 376390075SobrienYou can usually avoid the warning, and the related warning about 376490075Sobrienconstants which are so large that they are unsigned, by writing the 376590075Sobrieninteger constant in question in hexadecimal, with no U suffix. Take 376690075Sobriencare, though, because this gives the wrong result in exotic cases. 376790075Sobrien@end itemize 376890075Sobrien 376990075Sobrien@node Implementation Details 377090075Sobrien@chapter Implementation Details 377190075Sobrien 377290075SobrienHere we document details of how the preprocessor's implementation 377390075Sobrienaffects its user-visible behavior. You should try to avoid undue 377490075Sobrienreliance on behavior described here, as it is possible that it will 377590075Sobrienchange subtly in future implementations. 377690075Sobrien 377790075SobrienAlso documented here are obsolete features and changes from previous 3778117395Skanversions of CPP@. 377990075Sobrien 378090075Sobrien@menu 378190075Sobrien* Implementation-defined behavior:: 378290075Sobrien* Implementation limits:: 378390075Sobrien* Obsolete Features:: 378490075Sobrien* Differences from previous versions:: 378590075Sobrien@end menu 378690075Sobrien 378790075Sobrien@node Implementation-defined behavior 378890075Sobrien@section Implementation-defined behavior 378990075Sobrien@cindex implementation-defined behavior 379090075Sobrien 3791117395SkanThis is how CPP behaves in all the cases which the C standard 379290075Sobriendescribes as @dfn{implementation-defined}. This term means that the 379390075Sobrienimplementation is free to do what it likes, but must document its choice 379490075Sobrienand stick to it. 379590075Sobrien@c FIXME: Check the C++ standard for more implementation-defined stuff. 379690075Sobrien 379790075Sobrien@itemize @bullet 379890075Sobrien@need 1000 379990075Sobrien@item The mapping of physical source file multi-byte characters to the 380090075Sobrienexecution character set. 380190075Sobrien 3802132718SkanCurrently, CPP requires its input to be ASCII or UTF-8. The execution 3803132718Skancharacter set may be controlled by the user, with the 3804169689Skan@option{-fexec-charset} and @option{-fwide-exec-charset} options. 380590075Sobrien 3806132718Skan@item Identifier characters. 3807132718Skan@anchor{Identifier characters} 3808132718Skan 3809132718SkanThe C and C++ standards allow identifiers to be composed of @samp{_} 3810132718Skanand the alphanumeric characters. C++ and C99 also allow universal 3811169689Skancharacter names, and C99 further permits implementation-defined 3812169689Skancharacters. GCC currently only permits universal character names if 3813169689Skan@option{-fextended-identifiers} is used, because the implementation of 3814169689Skanuniversal character names in identifiers is experimental. 3815132718Skan 3816132718SkanGCC allows the @samp{$} character in identifiers as an extension for 3817132718Skanmost targets. This is true regardless of the @option{std=} switch, 3818132718Skansince this extension cannot conflict with standards-conforming 3819132718Skanprograms. When preprocessing assembler, however, dollars are not 3820132718Skanidentifier characters by default. 3821132718Skan 3822132718SkanCurrently the targets that by default do not permit @samp{$} are AVR, 3823132718SkanIP2K, MMIX, MIPS Irix 3, ARM aout, and PowerPC targets for the AIX and 3824132718SkanBeOS operating systems. 3825132718Skan 3826132718SkanYou can override the default with @option{-fdollars-in-identifiers} or 3827132718Skan@option{fno-dollars-in-identifiers}. @xref{fdollars-in-identifiers}. 3828132718Skan 382990075Sobrien@item Non-empty sequences of whitespace characters. 383090075Sobrien 383190075SobrienIn textual output, each whitespace sequence is collapsed to a single 383290075Sobrienspace. For aesthetic reasons, the first token on each non-directive 383390075Sobrienline of output is preceded with sufficient spaces that it appears in the 383490075Sobriensame column as it did in the original source file. 383590075Sobrien 383690075Sobrien@item The numeric value of character constants in preprocessor expressions. 383790075Sobrien 3838117395SkanThe preprocessor and compiler interpret character constants in the 3839117395Skansame way; i.e.@: escape sequences such as @samp{\a} are given the 3840117395Skanvalues they would have on the target machine. 384190075Sobrien 3842117395SkanThe compiler values a multi-character character constant a character 3843117395Skanat a time, shifting the previous value left by the number of bits per 3844117395Skantarget character, and then or-ing in the bit-pattern of the new 3845117395Skancharacter truncated to the width of a target character. The final 3846117395Skanbit-pattern is given type @code{int}, and is therefore signed, 3847117395Skanregardless of whether single characters are signed or not (a slight 3848169689Skanchange from versions 3.1 and earlier of GCC)@. If there are more 3849117395Skancharacters in the constant than would fit in the target @code{int} the 3850117395Skancompiler issues a warning, and the excess leading characters are 3851117395Skanignored. 385290075Sobrien 3853169689SkanFor example, @code{'ab'} for a target with an 8-bit @code{char} would be 3854169689Skaninterpreted as @w{@samp{(int) ((unsigned char) 'a' * 256 + (unsigned char) 3855169689Skan'b')}}, and @code{'\234a'} as @w{@samp{(int) ((unsigned char) '\234' * 3856169689Skan256 + (unsigned char) 'a')}}. 3857117395Skan 385890075Sobrien@item Source file inclusion. 385990075Sobrien 386090075SobrienFor a discussion on how the preprocessor locates header files, 386190075Sobrien@ref{Include Operation}. 386290075Sobrien 386390075Sobrien@item Interpretation of the filename resulting from a macro-expanded 386490075Sobrien@samp{#include} directive. 386590075Sobrien 386690075Sobrien@xref{Computed Includes}. 386790075Sobrien 386890075Sobrien@item Treatment of a @samp{#pragma} directive that after macro-expansion 386990075Sobrienresults in a standard pragma. 387090075Sobrien 387190075SobrienNo macro expansion occurs on any @samp{#pragma} directive line, so the 387290075Sobrienquestion does not arise. 387390075Sobrien 387490075SobrienNote that GCC does not yet implement any of the standard 387590075Sobrienpragmas. 387690075Sobrien 387790075Sobrien@end itemize 387890075Sobrien 387990075Sobrien@node Implementation limits 388090075Sobrien@section Implementation limits 388190075Sobrien@cindex implementation limits 388290075Sobrien 3883117395SkanCPP has a small number of internal limits. This section lists the 388490075Sobrienlimits which the C standard requires to be no lower than some minimum, 3885132718Skanand all the others known. It is intended that there should be as few limits 388690075Sobrienas possible. If you encounter an undocumented or inconvenient limit, 3887132718Skanplease report that as a bug. @xref{Bugs, , Reporting Bugs, gcc, Using 3888132718Skanthe GNU Compiler Collection (GCC)}. 388990075Sobrien 389090075SobrienWhere we say something is limited @dfn{only by available memory}, that 389190075Sobrienmeans that internal data structures impose no intrinsic limit, and space 389290075Sobrienis allocated with @code{malloc} or equivalent. The actual limit will 389390075Sobrientherefore depend on many things, such as the size of other things 389490075Sobrienallocated by the compiler at the same time, the amount of memory 389590075Sobrienconsumed by other processes on the same computer, etc. 389690075Sobrien 389790075Sobrien@itemize @bullet 389890075Sobrien 389990075Sobrien@item Nesting levels of @samp{#include} files. 390090075Sobrien 390190075SobrienWe impose an arbitrary limit of 200 levels, to avoid runaway recursion. 390290075SobrienThe standard requires at least 15 levels. 390390075Sobrien 390490075Sobrien@item Nesting levels of conditional inclusion. 390590075Sobrien 3906117395SkanThe C standard mandates this be at least 63. CPP is limited only by 390790075Sobrienavailable memory. 390890075Sobrien 3909117395Skan@item Levels of parenthesized expressions within a full expression. 391090075Sobrien 391190075SobrienThe C standard requires this to be at least 63. In preprocessor 391290075Sobrienconditional expressions, it is limited only by available memory. 391390075Sobrien 391490075Sobrien@item Significant initial characters in an identifier or macro name. 391590075Sobrien 391690075SobrienThe preprocessor treats all characters as significant. The C standard 391790075Sobrienrequires only that the first 63 be significant. 391890075Sobrien 391990075Sobrien@item Number of macros simultaneously defined in a single translation unit. 392090075Sobrien 3921117395SkanThe standard requires at least 4095 be possible. CPP is limited only 392290075Sobrienby available memory. 392390075Sobrien 392490075Sobrien@item Number of parameters in a macro definition and arguments in a macro call. 392590075Sobrien 392690075SobrienWe allow @code{USHRT_MAX}, which is no smaller than 65,535. The minimum 392790075Sobrienrequired by the standard is 127. 392890075Sobrien 392990075Sobrien@item Number of characters on a logical source line. 393090075Sobrien 3931117395SkanThe C standard requires a minimum of 4096 be permitted. CPP places 393290075Sobrienno limits on this, but you may get incorrect column numbers reported in 393390075Sobriendiagnostics for lines longer than 65,535 characters. 393490075Sobrien 393590075Sobrien@item Maximum size of a source file. 393690075Sobrien 393790075SobrienThe standard does not specify any lower limit on the maximum size of a 393890075Sobriensource file. GNU cpp maps files into memory, so it is limited by the 393990075Sobrienavailable address space. This is generally at least two gigabytes. 394090075SobrienDepending on the operating system, the size of physical memory may or 394190075Sobrienmay not be a limitation. 394290075Sobrien 394390075Sobrien@end itemize 394490075Sobrien 394590075Sobrien@node Obsolete Features 394690075Sobrien@section Obsolete Features 394790075Sobrien 3948117395SkanCPP has a number of features which are present mainly for 394990075Sobriencompatibility with older programs. We discourage their use in new code. 395090075SobrienIn some cases, we plan to remove the feature in a future version of GCC@. 395190075Sobrien 395290075Sobrien@menu 395390075Sobrien* Assertions:: 395490075Sobrien* Obsolete once-only headers:: 395590075Sobrien@end menu 395690075Sobrien 395790075Sobrien@node Assertions 395890075Sobrien@subsection Assertions 395990075Sobrien@cindex assertions 396090075Sobrien 396190075Sobrien@dfn{Assertions} are a deprecated alternative to macros in writing 396290075Sobrienconditionals to test what sort of computer or system the compiled 396390075Sobrienprogram will run on. Assertions are usually predefined, but you can 396490075Sobriendefine them with preprocessing directives or command-line options. 396590075Sobrien 396690075SobrienAssertions were intended to provide a more systematic way to describe 396790075Sobrienthe compiler's target system. However, in practice they are just as 396890075Sobrienunpredictable as the system-specific predefined macros. In addition, they 396990075Sobrienare not part of any standard, and only a few compilers support them. 397090075SobrienTherefore, the use of assertions is @strong{less} portable than the use 397190075Sobrienof system-specific predefined macros. We recommend you do not use them at 397290075Sobrienall. 397390075Sobrien 397490075Sobrien@cindex predicates 397590075SobrienAn assertion looks like this: 397690075Sobrien 3977132718Skan@smallexample 397890075Sobrien#@var{predicate} (@var{answer}) 3979132718Skan@end smallexample 398090075Sobrien 398190075Sobrien@noindent 398290075Sobrien@var{predicate} must be a single identifier. @var{answer} can be any 398390075Sobriensequence of tokens; all characters are significant except for leading 398490075Sobrienand trailing whitespace, and differences in internal whitespace 398590075Sobriensequences are ignored. (This is similar to the rules governing macro 398690075Sobrienredefinition.) Thus, @code{(x + y)} is different from @code{(x+y)} but 398790075Sobrienequivalent to @code{@w{( x + y )}}. Parentheses do not nest inside an 398890075Sobrienanswer. 398990075Sobrien 399090075Sobrien@cindex testing predicates 399190075SobrienTo test an assertion, you write it in an @samp{#if}. For example, this 399290075Sobrienconditional succeeds if either @code{vax} or @code{ns16000} has been 399390075Sobrienasserted as an answer for @code{machine}. 399490075Sobrien 3995132718Skan@smallexample 399690075Sobrien#if #machine (vax) || #machine (ns16000) 3997132718Skan@end smallexample 399890075Sobrien 399990075Sobrien@noindent 400090075SobrienYou can test whether @emph{any} answer is asserted for a predicate by 400190075Sobrienomitting the answer in the conditional: 400290075Sobrien 4003132718Skan@smallexample 400490075Sobrien#if #machine 4005132718Skan@end smallexample 400690075Sobrien 400790075Sobrien@findex #assert 400890075SobrienAssertions are made with the @samp{#assert} directive. Its sole 400990075Sobrienargument is the assertion to make, without the leading @samp{#} that 401090075Sobrienidentifies assertions in conditionals. 401190075Sobrien 4012132718Skan@smallexample 401390075Sobrien#assert @var{predicate} (@var{answer}) 4014132718Skan@end smallexample 401590075Sobrien 401690075Sobrien@noindent 401790075SobrienYou may make several assertions with the same predicate and different 401890075Sobrienanswers. Subsequent assertions do not override previous ones for the 401990075Sobriensame predicate. All the answers for any given predicate are 402090075Sobriensimultaneously true. 402190075Sobrien 4022117395Skan@cindex assertions, canceling 402390075Sobrien@findex #unassert 4024117395SkanAssertions can be canceled with the @samp{#unassert} directive. It 402590075Sobrienhas the same syntax as @samp{#assert}. In that form it cancels only the 402690075Sobrienanswer which was specified on the @samp{#unassert} line; other answers 402790075Sobrienfor that predicate remain true. You can cancel an entire predicate by 402890075Sobrienleaving out the answer: 402990075Sobrien 4030132718Skan@smallexample 403190075Sobrien#unassert @var{predicate} 4032132718Skan@end smallexample 403390075Sobrien 403490075Sobrien@noindent 403590075SobrienIn either form, if no such assertion has been made, @samp{#unassert} has 403690075Sobrienno effect. 403790075Sobrien 403890075SobrienYou can also make or cancel assertions using command line options. 403990075Sobrien@xref{Invocation}. 404090075Sobrien 404190075Sobrien@node Obsolete once-only headers 404290075Sobrien@subsection Obsolete once-only headers 404390075Sobrien 4044220755SdimCPP supports one more way of indicating that a header file should be 4045220755Sdimread only once. This is not as portable as a wrapper @samp{#ifndef}, 4046220755Sdimand we recommend you do not use it in new programs. 404790075Sobrien 4048220755SdimA way to prevent a header file from being included more than once is 4049220755Sdimwith the @samp{#pragma once} directive. If @samp{#pragma once} is seen 4050220755Sdimwhen scanning a header file, that file will never be read again, no 405190075Sobrienmatter what. 405290075Sobrien 405390075Sobrien@samp{#pragma once} does not have the problems that @samp{#import} does, 405490075Sobrienbut it is not recognized by all preprocessors, so you cannot rely on it 405590075Sobrienin a portable program. 405690075Sobrien 405790075Sobrien@node Differences from previous versions 405890075Sobrien@section Differences from previous versions 405990075Sobrien@cindex differences from previous versions 406090075Sobrien 406190075SobrienThis section details behavior which has changed from previous versions 4062117395Skanof CPP@. We do not plan to change it again in the near future, but 406390075Sobrienwe do not promise not to, either. 406490075Sobrien 406590075SobrienThe ``previous versions'' discussed here are 2.95 and before. The 406690075Sobrienbehavior of GCC 3.0 is mostly the same as the behavior of the widely 406790075Sobrienused 2.96 and 2.97 development snapshots. Where there are differences, 406890075Sobrienthey generally represent bugs in the snapshots. 406990075Sobrien 407090075Sobrien@itemize @bullet 407190075Sobrien 4072169689Skan@item -I- deprecated 4073169689Skan 4074169689SkanThis option has been deprecated in 4.0. @option{-iquote} is meant to 4075169689Skanreplace the need for this option. 4076169689Skan 407790075Sobrien@item Order of evaluation of @samp{#} and @samp{##} operators 407890075Sobrien 407990075SobrienThe standard does not specify the order of evaluation of a chain of 408090075Sobrien@samp{##} operators, nor whether @samp{#} is evaluated before, after, or 408190075Sobrienat the same time as @samp{##}. You should therefore not write any code 408290075Sobrienwhich depends on any specific ordering. It is possible to guarantee an 408390075Sobrienordering, if you need one, by suitable use of nested macros. 408490075Sobrien 408590075SobrienAn example of where this might matter is pasting the arguments @samp{1}, 408690075Sobrien@samp{e} and @samp{-2}. This would be fine for left-to-right pasting, 408790075Sobrienbut right-to-left pasting would produce an invalid token @samp{e-2}. 408890075Sobrien 408990075SobrienGCC 3.0 evaluates @samp{#} and @samp{##} at the same time and strictly 409090075Sobrienleft to right. Older versions evaluated all @samp{#} operators first, 409190075Sobrienthen all @samp{##} operators, in an unreliable order. 409290075Sobrien 4093117395Skan@item The form of whitespace between tokens in preprocessor output 409490075Sobrien 409590075Sobrien@xref{Preprocessor Output}, for the current textual format. This is 409690075Sobrienalso the format used by stringification. Normally, the preprocessor 409790075Sobriencommunicates tokens directly to the compiler's parser, and whitespace 409890075Sobriendoes not come up at all. 409990075Sobrien 410090075SobrienOlder versions of GCC preserved all whitespace provided by the user and 410190075Sobrieninserted lots more whitespace of their own, because they could not 410290075Sobrienaccurately predict when extra spaces were needed to prevent accidental 410390075Sobrientoken pasting. 410490075Sobrien 410590075Sobrien@item Optional argument when invoking rest argument macros 410690075Sobrien 410790075SobrienAs an extension, GCC permits you to omit the variable arguments entirely 410890075Sobrienwhen you use a variable argument macro. This is forbidden by the 1999 C 410990075Sobrienstandard, and will provoke a pedantic warning with GCC 3.0. Previous 411090075Sobrienversions accepted it silently. 411190075Sobrien 411290075Sobrien@item @samp{##} swallowing preceding text in rest argument macros 411390075Sobrien 411490075SobrienFormerly, in a macro expansion, if @samp{##} appeared before a variable 411590075Sobrienarguments parameter, and the set of tokens specified for that argument 4116117395Skanin the macro invocation was empty, previous versions of CPP would 411790075Sobrienback up and remove the preceding sequence of non-whitespace characters 411890075Sobrien(@strong{not} the preceding token). This extension is in direct 411990075Sobrienconflict with the 1999 C standard and has been drastically pared back. 412090075Sobrien 412190075SobrienIn the current version of the preprocessor, if @samp{##} appears between 412290075Sobriena comma and a variable arguments parameter, and the variable argument is 412390075Sobrienomitted entirely, the comma will be removed from the expansion. If the 412490075Sobrienvariable argument is empty, or the token before @samp{##} is not a 412590075Sobriencomma, then @samp{##} behaves as a normal token paste. 412690075Sobrien 412796263Sobrien@item @samp{#line} and @samp{#include} 412896263Sobrien 412996263SobrienThe @samp{#line} directive used to change GCC's notion of the 4130169689Skan``directory containing the current file'', used by @samp{#include} with 413196263Sobriena double-quoted header file name. In 3.0 and later, it does not. 413296263Sobrien@xref{Line Control}, for further explanation. 413396263Sobrien 413496263Sobrien@item Syntax of @samp{#line} 413596263Sobrien 413696263SobrienIn GCC 2.95 and previous, the string constant argument to @samp{#line} 413796263Sobrienwas treated the same way as the argument to @samp{#include}: backslash 413896263Sobrienescapes were not honored, and the string ended at the second @samp{"}. 413996263SobrienThis is not compliant with the C standard. In GCC 3.0, an attempt was 414096263Sobrienmade to correct the behavior, so that the string was treated as a real 414196263Sobrienstring constant, but it turned out to be buggy. In 3.1, the bugs have 414296263Sobrienbeen fixed. (We are not fixing the bugs in 3.0 because they affect 414396263Sobrienrelatively few people and the fix is quite invasive.) 414496263Sobrien 414590075Sobrien@end itemize 414690075Sobrien 414790075Sobrien@node Invocation 414890075Sobrien@chapter Invocation 414990075Sobrien@cindex invocation 415090075Sobrien@cindex command line 415190075Sobrien 415290075SobrienMost often when you use the C preprocessor you will not have to invoke it 415390075Sobrienexplicitly: the C compiler will do so automatically. However, the 415490075Sobrienpreprocessor is sometimes useful on its own. All the options listed 415590075Sobrienhere are also acceptable to the C compiler and have the same meaning, 415690075Sobrienexcept that the C compiler has different rules for specifying the output 415790075Sobrienfile. 415890075Sobrien 4159169689Skan@emph{Note:} Whether you use the preprocessor by way of @command{gcc} 416090075Sobrienor @command{cpp}, the @dfn{compiler driver} is run first. This 416190075Sobrienprogram's purpose is to translate your command into invocations of the 416290075Sobrienprograms that do the actual work. Their command line interfaces are 416390075Sobriensimilar but not identical to the documented interface, and may change 416490075Sobrienwithout notice. 416590075Sobrien 416690075Sobrien@ignore 416790075Sobrien@c man begin SYNOPSIS 416890075Sobriencpp [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}] 4169169689Skan [@option{-I}@var{dir}@dots{}] [@option{-iquote}@var{dir}@dots{}] 4170169689Skan [@option{-W}@var{warn}@dots{}] 417190075Sobrien [@option{-M}|@option{-MM}] [@option{-MG}] [@option{-MF} @var{filename}] 4172132718Skan [@option{-MP}] [@option{-MQ} @var{target}@dots{}] 4173132718Skan [@option{-MT} @var{target}@dots{}] 4174132718Skan [@option{-P}] [@option{-fno-working-directory}] 417590075Sobrien [@option{-x} @var{language}] [@option{-std=}@var{standard}] 417690075Sobrien @var{infile} @var{outfile} 417790075Sobrien 417890075SobrienOnly the most useful options are listed here; see below for the remainder. 417990075Sobrien@c man end 418090075Sobrien@c man begin SEEALSO 418190075Sobriengpl(7), gfdl(7), fsf-funding(7), 418290075Sobriengcc(1), as(1), ld(1), and the Info entries for @file{cpp}, @file{gcc}, and 418390075Sobrien@file{binutils}. 418490075Sobrien@c man end 418590075Sobrien@end ignore 418690075Sobrien 418790075Sobrien@c man begin OPTIONS 418890075SobrienThe C preprocessor expects two file names as arguments, @var{infile} and 418990075Sobrien@var{outfile}. The preprocessor reads @var{infile} together with any 419090075Sobrienother files it specifies with @samp{#include}. All the output generated 419190075Sobrienby the combined input files is written in @var{outfile}. 419290075Sobrien 419390075SobrienEither @var{infile} or @var{outfile} may be @option{-}, which as 419490075Sobrien@var{infile} means to read from standard input and as @var{outfile} 419590075Sobrienmeans to write to standard output. Also, if either file is omitted, it 419690075Sobrienmeans the same as if @option{-} had been specified for that file. 419790075Sobrien 419890075SobrienUnless otherwise noted, or the option ends in @samp{=}, all options 419990075Sobrienwhich take an argument may have that argument appear either immediately 420090075Sobrienafter the option, or with a space between option and argument: 420190075Sobrien@option{-Ifoo} and @option{-I foo} have the same effect. 420290075Sobrien 420390075Sobrien@cindex grouping options 420490075Sobrien@cindex options, grouping 420590075SobrienMany options have multi-letter names; therefore multiple single-letter 420690075Sobrienoptions may @emph{not} be grouped: @option{-dM} is very different from 420790075Sobrien@w{@samp{-d -M}}. 420890075Sobrien 420990075Sobrien@cindex options 421096263Sobrien@include cppopts.texi 421196263Sobrien@c man end 421290075Sobrien 421396263Sobrien@node Environment Variables 421496263Sobrien@chapter Environment Variables 421596263Sobrien@cindex environment variables 421696263Sobrien@c man begin ENVIRONMENT 421790075Sobrien 421896263SobrienThis section describes the environment variables that affect how CPP 421996263Sobrienoperates. You can use them to specify directories or prefixes to use 422096263Sobrienwhen searching for include files, or to control dependency output. 422190075Sobrien 422296263SobrienNote that you can also specify places to search using options such as 422396263Sobrien@option{-I}, and control dependency output with options like 422496263Sobrien@option{-M} (@pxref{Invocation}). These take precedence over 422596263Sobrienenvironment variables, which in turn take precedence over the 422696263Sobrienconfiguration of GCC@. 4227132718Skan 422896263Sobrien@include cppenv.texi 422996263Sobrien@c man end 423090075Sobrien 4231117395Skan@page 423296263Sobrien@include fdl.texi 423390075Sobrien 423496263Sobrien@page 4235117395Skan@node Index of Directives 4236117395Skan@unnumbered Index of Directives 4237117395Skan@printindex fn 4238117395Skan 423996263Sobrien@node Option Index 424096263Sobrien@unnumbered Option Index 4241117395Skan@noindent 4242117395SkanCPP's command line options and environment variables are indexed here 4243117395Skanwithout any initial @samp{-} or @samp{--}. 424496263Sobrien@printindex op 424590075Sobrien 4246117395Skan@page 424790075Sobrien@node Concept Index 424890075Sobrien@unnumbered Concept Index 424990075Sobrien@printindex cp 425090075Sobrien 425190075Sobrien@bye 4252