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