OSDN Git Service

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