OSDN Git Service

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