OSDN Git Service

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