OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-old/] [gcc-4.2.2/] [gcc/] [doc/] [cpp.info] - Blame information for rev 38

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 38 julius
This is doc/cpp.info, produced by makeinfo version 4.8 from
2
/scratch/mitchell/gcc-releases/gcc-4.2.2/gcc-4.2.2/gcc/doc/cpp.texi.
3
 
4
   Copyright (C) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997,
5
1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free Software
6
Foundation, Inc.
7
 
8
   Permission is granted to copy, distribute and/or modify this document
9
under the terms of the GNU Free Documentation License, Version 1.1 or
10
any later version published by the Free Software Foundation.  A copy of
11
the license is included in the section entitled "GNU Free Documentation
12
License".
13
 
14
   This manual contains no Invariant Sections.  The Front-Cover Texts
15
are (a) (see below), and the Back-Cover Texts are (b) (see below).
16
 
17
   (a) The FSF's Front-Cover Text is:
18
 
19
   A GNU Manual
20
 
21
   (b) The FSF's Back-Cover Text is:
22
 
23
   You have freedom to copy and modify this GNU Manual, like GNU
24
software.  Copies published by the Free Software Foundation raise
25
funds for GNU development.
26
 
27
INFO-DIR-SECTION Software development
28
START-INFO-DIR-ENTRY
29
* Cpp: (cpp).                  The GNU C preprocessor.
30
END-INFO-DIR-ENTRY
31
 
32

33
File: cpp.info,  Node: Top,  Next: Overview,  Up: (dir)
34
 
35
The C Preprocessor
36
******************
37
 
38
The C preprocessor implements the macro language used to transform C,
39
C++, and Objective-C programs before they are compiled.  It can also be
40
useful on its own.
41
 
42
* Menu:
43
 
44
* Overview::
45
* Header Files::
46
* Macros::
47
* Conditionals::
48
* Diagnostics::
49
* Line Control::
50
* Pragmas::
51
* Other Directives::
52
* Preprocessor Output::
53
* Traditional Mode::
54
* Implementation Details::
55
* Invocation::
56
* Environment Variables::
57
* GNU Free Documentation License::
58
* Index of Directives::
59
* Option Index::
60
* Concept Index::
61
 
62
 --- The Detailed Node Listing ---
63
 
64
Overview
65
 
66
* Character sets::
67
* Initial processing::
68
* Tokenization::
69
* The preprocessing language::
70
 
71
Header Files
72
 
73
* Include Syntax::
74
* Include Operation::
75
* Search Path::
76
* Once-Only Headers::
77
* Computed Includes::
78
* Wrapper Headers::
79
* System Headers::
80
 
81
Macros
82
 
83
* Object-like Macros::
84
* Function-like Macros::
85
* Macro Arguments::
86
* Stringification::
87
* Concatenation::
88
* Variadic Macros::
89
* Predefined Macros::
90
* Undefining and Redefining Macros::
91
* Directives Within Macro Arguments::
92
* Macro Pitfalls::
93
 
94
Predefined Macros
95
 
96
* Standard Predefined Macros::
97
* Common Predefined Macros::
98
* System-specific Predefined Macros::
99
* C++ Named Operators::
100
 
101
Macro Pitfalls
102
 
103
* Misnesting::
104
* Operator Precedence Problems::
105
* Swallowing the Semicolon::
106
* Duplication of Side Effects::
107
* Self-Referential Macros::
108
* Argument Prescan::
109
* Newlines in Arguments::
110
 
111
Conditionals
112
 
113
* Conditional Uses::
114
* Conditional Syntax::
115
* Deleted Code::
116
 
117
Conditional Syntax
118
 
119
* Ifdef::
120
* If::
121
* Defined::
122
* Else::
123
* Elif::
124
 
125
Implementation Details
126
 
127
* Implementation-defined behavior::
128
* Implementation limits::
129
* Obsolete Features::
130
* Differences from previous versions::
131
 
132
Obsolete Features
133
 
134
* Assertions::
135
* Obsolete once-only headers::
136
 
137
   Copyright (C) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997,
138
1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free Software
139
Foundation, Inc.
140
 
141
   Permission is granted to copy, distribute and/or modify this document
142
under the terms of the GNU Free Documentation License, Version 1.1 or
143
any later version published by the Free Software Foundation.  A copy of
144
the license is included in the section entitled "GNU Free Documentation
145
License".
146
 
147
   This manual contains no Invariant Sections.  The Front-Cover Texts
148
are (a) (see below), and the Back-Cover Texts are (b) (see below).
149
 
150
   (a) The FSF's Front-Cover Text is:
151
 
152
   A GNU Manual
153
 
154
   (b) The FSF's Back-Cover Text is:
155
 
156
   You have freedom to copy and modify this GNU Manual, like GNU
157
software.  Copies published by the Free Software Foundation raise
158
funds for GNU development.
159
 
160

161
File: cpp.info,  Node: Overview,  Next: Header Files,  Prev: Top,  Up: Top
162
 
163
1 Overview
164
**********
165
 
166
The C preprocessor, often known as "cpp", is a "macro processor" that
167
is used automatically by the C compiler to transform your program
168
before compilation.  It is called a macro processor because it allows
169
you to define "macros", which are brief abbreviations for longer
170
constructs.
171
 
172
   The C preprocessor is intended to be used only with C, C++, and
173
Objective-C source code.  In the past, it has been abused as a general
174
text processor.  It will choke on input which does not obey C's lexical
175
rules.  For example, apostrophes will be interpreted as the beginning of
176
character constants, and cause errors.  Also, you cannot rely on it
177
preserving characteristics of the input which are not significant to
178
C-family languages.  If a Makefile is preprocessed, all the hard tabs
179
will be removed, and the Makefile will not work.
180
 
181
   Having said that, you can often get away with using cpp on things
182
which are not C.  Other Algol-ish programming languages are often safe
183
(Pascal, Ada, etc.) So is assembly, with caution.  `-traditional-cpp'
184
mode preserves more white space, and is otherwise more permissive.  Many
185
of the problems can be avoided by writing C or C++ style comments
186
instead of native language comments, and keeping macros simple.
187
 
188
   Wherever possible, you should use a preprocessor geared to the
189
language you are writing in.  Modern versions of the GNU assembler have
190
macro facilities.  Most high level programming languages have their own
191
conditional compilation and inclusion mechanism.  If all else fails,
192
try a true general text processor, such as GNU M4.
193
 
194
   C preprocessors vary in some details.  This manual discusses the GNU
195
C preprocessor, which provides a small superset of the features of ISO
196
Standard C.  In its default mode, the GNU C preprocessor does not do a
197
few things required by the standard.  These are features which are
198
rarely, if ever, used, and may cause surprising changes to the meaning
199
of a program which does not expect them.  To get strict ISO Standard C,
200
you should use the `-std=c89' or `-std=c99' options, depending on which
201
version of the standard you want.  To get all the mandatory
202
diagnostics, you must also use `-pedantic'.  *Note Invocation::.
203
 
204
   This manual describes the behavior of the ISO preprocessor.  To
205
minimize gratuitous differences, where the ISO preprocessor's behavior
206
does not conflict with traditional semantics, the traditional
207
preprocessor should behave the same way.  The various differences that
208
do exist are detailed in the section *Note Traditional Mode::.
209
 
210
   For clarity, unless noted otherwise, references to `CPP' in this
211
manual refer to GNU CPP.
212
 
213
* Menu:
214
 
215
* Character sets::
216
* Initial processing::
217
* Tokenization::
218
* The preprocessing language::
219
 
220

221
File: cpp.info,  Node: Character sets,  Next: Initial processing,  Up: Overview
222
 
223
1.1 Character sets
224
==================
225
 
226
Source code character set processing in C and related languages is
227
rather complicated.  The C standard discusses two character sets, but
228
there are really at least four.
229
 
230
   The files input to CPP might be in any character set at all.  CPP's
231
very first action, before it even looks for line boundaries, is to
232
convert the file into the character set it uses for internal
233
processing.  That set is what the C standard calls the "source"
234
character set.  It must be isomorphic with ISO 10646, also known as
235
Unicode.  CPP uses the UTF-8 encoding of Unicode.
236
 
237
   The character sets of the input files are specified using the
238
`-finput-charset=' option.
239
 
240
   All preprocessing work (the subject of the rest of this manual) is
241
carried out in the source character set.  If you request textual output
242
from the preprocessor with the `-E' option, it will be in UTF-8.
243
 
244
   After preprocessing is complete, string and character constants are
245
converted again, into the "execution" character set.  This character
246
set is under control of the user; the default is UTF-8, matching the
247
source character set.  Wide string and character constants have their
248
own character set, which is not called out specifically in the
249
standard.  Again, it is under control of the user.  The default is
250
UTF-16 or UTF-32, whichever fits in the target's `wchar_t' type, in the
251
target machine's byte order.(1)  Octal and hexadecimal escape sequences
252
do not undergo conversion; '\x12' has the value 0x12 regardless of the
253
currently selected execution character set.  All other escapes are
254
replaced by the character in the source character set that they
255
represent, then converted to the execution character set, just like
256
unescaped characters.
257
 
258
   Unless the experimental `-fextended-identifiers' option is used, GCC
259
does not permit the use of characters outside the ASCII range, nor `\u'
260
and `\U' escapes, in identifiers.  Even with that option, characters
261
outside the ASCII range can only be specified with the `\u' and `\U'
262
escapes, not used directly in identifiers.
263
 
264
   ---------- Footnotes ----------
265
 
266
   (1) UTF-16 does not meet the requirements of the C standard for a
267
wide character set, but the choice of 16-bit `wchar_t' is enshrined in
268
some system ABIs so we cannot fix this.
269
 
270

271
File: cpp.info,  Node: Initial processing,  Next: Tokenization,  Prev: Character sets,  Up: Overview
272
 
273
1.2 Initial processing
274
======================
275
 
276
The preprocessor performs a series of textual transformations on its
277
input.  These happen before all other processing.  Conceptually, they
278
happen in a rigid order, and the entire file is run through each
279
transformation before the next one begins.  CPP actually does them all
280
at once, for performance reasons.  These transformations correspond
281
roughly to the first three "phases of translation" described in the C
282
standard.
283
 
284
  1. The input file is read into memory and broken into lines.
285
 
286
     Different systems use different conventions to indicate the end of
287
     a line.  GCC accepts the ASCII control sequences `LF', `CR LF' and
288
     `CR' as end-of-line markers.  These are the canonical sequences
289
     used by Unix, DOS and VMS, and the classic Mac OS (before OSX)
290
     respectively.  You may therefore safely copy source code written
291
     on any of those systems to a different one and use it without
292
     conversion.  (GCC may lose track of the current line number if a
293
     file doesn't consistently use one convention, as sometimes happens
294
     when it is edited on computers with different conventions that
295
     share a network file system.)
296
 
297
     If the last line of any input file lacks an end-of-line marker,
298
     the end of the file is considered to implicitly supply one.  The C
299
     standard says that this condition provokes undefined behavior, so
300
     GCC will emit a warning message.
301
 
302
  2. If trigraphs are enabled, they are replaced by their corresponding
303
     single characters.  By default GCC ignores trigraphs, but if you
304
     request a strictly conforming mode with the `-std' option, or you
305
     specify the `-trigraphs' option, then it converts them.
306
 
307
     These are nine three-character sequences, all starting with `??',
308
     that are defined by ISO C to stand for single characters.  They
309
     permit obsolete systems that lack some of C's punctuation to use
310
     C.  For example, `??/' stands for `\', so '??/n' is a character
311
     constant for a newline.
312
 
313
     Trigraphs are not popular and many compilers implement them
314
     incorrectly.  Portable code should not rely on trigraphs being
315
     either converted or ignored.  With `-Wtrigraphs' GCC will warn you
316
     when a trigraph may change the meaning of your program if it were
317
     converted.  *Note Wtrigraphs::.
318
 
319
     In a string constant, you can prevent a sequence of question marks
320
     from being confused with a trigraph by inserting a backslash
321
     between the question marks, or by separating the string literal at
322
     the trigraph and making use of string literal concatenation.
323
     "(??\?)"  is the string `(???)', not `(?]'.  Traditional C
324
     compilers do not recognize these idioms.
325
 
326
     The nine trigraphs and their replacements are
327
 
328
          Trigraph:       ??(  ??)  ??<  ??>  ??=  ??/  ??'  ??!  ??-
329
          Replacement:      [    ]    {    }    #    \    ^    |    ~
330
 
331
  3. Continued lines are merged into one long line.
332
 
333
     A continued line is a line which ends with a backslash, `\'.  The
334
     backslash is removed and the following line is joined with the
335
     current one.  No space is inserted, so you may split a line
336
     anywhere, even in the middle of a word.  (It is generally more
337
     readable to split lines only at white space.)
338
 
339
     The trailing backslash on a continued line is commonly referred to
340
     as a "backslash-newline".
341
 
342
     If there is white space between a backslash and the end of a line,
343
     that is still a continued line.  However, as this is usually the
344
     result of an editing mistake, and many compilers will not accept
345
     it as a continued line, GCC will warn you about it.
346
 
347
  4. All comments are replaced with single spaces.
348
 
349
     There are two kinds of comments.  "Block comments" begin with `/*'
350
     and continue until the next `*/'.  Block comments do not nest:
351
 
352
          /* this is /* one comment */ text outside comment
353
 
354
     "Line comments" begin with `//' and continue to the end of the
355
     current line.  Line comments do not nest either, but it does not
356
     matter, because they would end in the same place anyway.
357
 
358
          // this is // one comment
359
          text outside comment
360
 
361
   It is safe to put line comments inside block comments, or vice versa.
362
 
363
     /* block comment
364
        // contains line comment
365
        yet more comment
366
      */ outside comment
367
 
368
     // line comment /* contains block comment */
369
 
370
   But beware of commenting out one end of a block comment with a line
371
comment.
372
 
373
      // l.c.  /* block comment begins
374
         oops! this isn't a comment anymore */
375
 
376
   Comments are not recognized within string literals.  "/* blah */" is
377
the string constant `/* blah */', not an empty string.
378
 
379
   Line comments are not in the 1989 edition of the C standard, but they
380
are recognized by GCC as an extension.  In C++ and in the 1999 edition
381
of the C standard, they are an official part of the language.
382
 
383
   Since these transformations happen before all other processing, you
384
can split a line mechanically with backslash-newline anywhere.  You can
385
comment out the end of a line.  You can continue a line comment onto the
386
next line with backslash-newline.  You can even split `/*', `*/', and
387
`//' onto multiple lines with backslash-newline.  For example:
388
 
389
     /\
390
     *
391
     */ # /*
392
     */ defi\
393
     ne FO\
394
     O 10\
395
     20
396
 
397
is equivalent to `#define FOO 1020'.  All these tricks are extremely
398
confusing and should not be used in code intended to be readable.
399
 
400
   There is no way to prevent a backslash at the end of a line from
401
being interpreted as a backslash-newline.  This cannot affect any
402
correct program, however.
403
 
404

405
File: cpp.info,  Node: Tokenization,  Next: The preprocessing language,  Prev: Initial processing,  Up: Overview
406
 
407
1.3 Tokenization
408
================
409
 
410
After the textual transformations are finished, the input file is
411
converted into a sequence of "preprocessing tokens".  These mostly
412
correspond to the syntactic tokens used by the C compiler, but there are
413
a few differences.  White space separates tokens; it is not itself a
414
token of any kind.  Tokens do not have to be separated by white space,
415
but it is often necessary to avoid ambiguities.
416
 
417
   When faced with a sequence of characters that has more than one
418
possible tokenization, the preprocessor is greedy.  It always makes
419
each token, starting from the left, as big as possible before moving on
420
to the next token.  For instance, `a+++++b' is interpreted as
421
`a ++ ++ + b', not as `a ++ + ++ b', even though the latter
422
tokenization could be part of a valid C program and the former could
423
not.
424
 
425
   Once the input file is broken into tokens, the token boundaries never
426
change, except when the `##' preprocessing operator is used to paste
427
tokens together.  *Note Concatenation::.  For example,
428
 
429
     #define foo() bar
430
     foo()baz
431
          ==> bar baz
432
     _not_
433
          ==> barbaz
434
 
435
   The compiler does not re-tokenize the preprocessor's output.  Each
436
preprocessing token becomes one compiler token.
437
 
438
   Preprocessing tokens fall into five broad classes: identifiers,
439
preprocessing numbers, string literals, punctuators, and other.  An
440
"identifier" is the same as an identifier in C: any sequence of
441
letters, digits, or underscores, which begins with a letter or
442
underscore.  Keywords of C have no significance to the preprocessor;
443
they are ordinary identifiers.  You can define a macro whose name is a
444
keyword, for instance.  The only identifier which can be considered a
445
preprocessing keyword is `defined'.  *Note Defined::.
446
 
447
   This is mostly true of other languages which use the C preprocessor.
448
However, a few of the keywords of C++ are significant even in the
449
preprocessor.  *Note C++ Named Operators::.
450
 
451
   In the 1999 C standard, identifiers may contain letters which are not
452
part of the "basic source character set", at the implementation's
453
discretion (such as accented Latin letters, Greek letters, or Chinese
454
ideograms).  This may be done with an extended character set, or the
455
`\u' and `\U' escape sequences.  The implementation of this feature in
456
GCC is experimental; such characters are only accepted in the `\u' and
457
`\U' forms and only if `-fextended-identifiers' is used.
458
 
459
   As an extension, GCC treats `$' as a letter.  This is for
460
compatibility with some systems, such as VMS, where `$' is commonly
461
used in system-defined function and object names.  `$' is not a letter
462
in strictly conforming mode, or if you specify the `-$' option.  *Note
463
Invocation::.
464
 
465
   A "preprocessing number" has a rather bizarre definition.  The
466
category includes all the normal integer and floating point constants
467
one expects of C, but also a number of other things one might not
468
initially recognize as a number.  Formally, preprocessing numbers begin
469
with an optional period, a required decimal digit, and then continue
470
with any sequence of letters, digits, underscores, periods, and
471
exponents.  Exponents are the two-character sequences `e+', `e-', `E+',
472
`E-', `p+', `p-', `P+', and `P-'.  (The exponents that begin with `p'
473
or `P' are new to C99.  They are used for hexadecimal floating-point
474
constants.)
475
 
476
   The purpose of this unusual definition is to isolate the preprocessor
477
from the full complexity of numeric constants.  It does not have to
478
distinguish between lexically valid and invalid floating-point numbers,
479
which is complicated.  The definition also permits you to split an
480
identifier at any position and get exactly two tokens, which can then be
481
pasted back together with the `##' operator.
482
 
483
   It's possible for preprocessing numbers to cause programs to be
484
misinterpreted.  For example, `0xE+12' is a preprocessing number which
485
does not translate to any valid numeric constant, therefore a syntax
486
error.  It does not mean `0xE + 12', which is what you might have
487
intended.
488
 
489
   "String literals" are string constants, character constants, and
490
header file names (the argument of `#include').(1)  String constants
491
and character constants are straightforward: "..." or '...'.  In either
492
case embedded quotes should be escaped with a backslash: '\'' is the
493
character constant for `''.  There is no limit on the length of a
494
character constant, but the value of a character constant that contains
495
more than one character is implementation-defined.  *Note
496
Implementation Details::.
497
 
498
   Header file names either look like string constants, "...", or are
499
written with angle brackets instead, <...>.  In either case, backslash
500
is an ordinary character.  There is no way to escape the closing quote
501
or angle bracket.  The preprocessor looks for the header file in
502
different places depending on which form you use.  *Note Include
503
Operation::.
504
 
505
   No string literal may extend past the end of a line.  Older versions
506
of GCC accepted multi-line string constants.  You may use continued
507
lines instead, or string constant concatenation.  *Note Differences
508
from previous versions::.
509
 
510
   "Punctuators" are all the usual bits of punctuation which are
511
meaningful to C and C++.  All but three of the punctuation characters in
512
ASCII are C punctuators.  The exceptions are `@', `$', and ``'.  In
513
addition, all the two- and three-character operators are punctuators.
514
There are also six "digraphs", which the C++ standard calls
515
"alternative tokens", which are merely alternate ways to spell other
516
punctuators.  This is a second attempt to work around missing
517
punctuation in obsolete systems.  It has no negative side effects,
518
unlike trigraphs, but does not cover as much ground.  The digraphs and
519
their corresponding normal punctuators are:
520
 
521
     Digraph:        <%  %>  <:  :>  %:  %:%:
522
     Punctuator:      {   }   [   ]   #    ##
523
 
524
   Any other single character is considered "other".  It is passed on to
525
the preprocessor's output unmolested.  The C compiler will almost
526
certainly reject source code containing "other" tokens.  In ASCII, the
527
only other characters are `@', `$', ``', and control characters other
528
than NUL (all bits zero).  (Note that `$' is normally considered a
529
letter.)  All characters with the high bit set (numeric range
530
0x7F-0xFF) are also "other" in the present implementation.  This will
531
change when proper support for international character sets is added to
532
GCC.
533
 
534
   NUL is a special case because of the high probability that its
535
appearance is accidental, and because it may be invisible to the user
536
(many terminals do not display NUL at all).  Within comments, NULs are
537
silently ignored, just as any other character would be.  In running
538
text, NUL is considered white space.  For example, these two directives
539
have the same meaning.
540
 
541
     #define X^@1
542
     #define X 1
543
 
544
(where `^@' is ASCII NUL).  Within string or character constants, NULs
545
are preserved.  In the latter two cases the preprocessor emits a
546
warning message.
547
 
548
   ---------- Footnotes ----------
549
 
550
   (1) The C standard uses the term "string literal" to refer only to
551
what we are calling "string constants".
552
 
553

554
File: cpp.info,  Node: The preprocessing language,  Prev: Tokenization,  Up: Overview
555
 
556
1.4 The preprocessing language
557
==============================
558
 
559
After tokenization, the stream of tokens may simply be passed straight
560
to the compiler's parser.  However, if it contains any operations in the
561
"preprocessing language", it will be transformed first.  This stage
562
corresponds roughly to the standard's "translation phase 4" and is what
563
most people think of as the preprocessor's job.
564
 
565
   The preprocessing language consists of "directives" to be executed
566
and "macros" to be expanded.  Its primary capabilities are:
567
 
568
   * Inclusion of header files.  These are files of declarations that
569
     can be substituted into your program.
570
 
571
   * Macro expansion.  You can define "macros", which are abbreviations
572
     for arbitrary fragments of C code.  The preprocessor will replace
573
     the macros with their definitions throughout the program.  Some
574
     macros are automatically defined for you.
575
 
576
   * Conditional compilation.  You can include or exclude parts of the
577
     program according to various conditions.
578
 
579
   * Line control.  If you use a program to combine or rearrange source
580
     files into an intermediate file which is then compiled, you can
581
     use line control to inform the compiler where each source line
582
     originally came from.
583
 
584
   * Diagnostics.  You can detect problems at compile time and issue
585
     errors or warnings.
586
 
587
   There are a few more, less useful, features.
588
 
589
   Except for expansion of predefined macros, all these operations are
590
triggered with "preprocessing directives".  Preprocessing directives
591
are lines in your program that start with `#'.  Whitespace is allowed
592
before and after the `#'.  The `#' is followed by an identifier, the
593
"directive name".  It specifies the operation to perform.  Directives
594
are commonly referred to as `#NAME' where NAME is the directive name.
595
For example, `#define' is the directive that defines a macro.
596
 
597
   The `#' which begins a directive cannot come from a macro expansion.
598
Also, the directive name is not macro expanded.  Thus, if `foo' is
599
defined as a macro expanding to `define', that does not make `#foo' a
600
valid preprocessing directive.
601
 
602
   The set of valid directive names is fixed.  Programs cannot define
603
new preprocessing directives.
604
 
605
   Some directives require arguments; these make up the rest of the
606
directive line and must be separated from the directive name by
607
whitespace.  For example, `#define' must be followed by a macro name
608
and the intended expansion of the macro.
609
 
610
   A preprocessing directive cannot cover more than one line.  The line
611
may, however, be continued with backslash-newline, or by a block comment
612
which extends past the end of the line.  In either case, when the
613
directive is processed, the continuations have already been merged with
614
the first line to make one long line.
615
 
616

617
File: cpp.info,  Node: Header Files,  Next: Macros,  Prev: Overview,  Up: Top
618
 
619
2 Header Files
620
**************
621
 
622
A header file is a file containing C declarations and macro definitions
623
(*note Macros::) to be shared between several source files.  You request
624
the use of a header file in your program by "including" it, with the C
625
preprocessing directive `#include'.
626
 
627
   Header files serve two purposes.
628
 
629
   * System header files declare the interfaces to parts of the
630
     operating system.  You include them in your program to supply the
631
     definitions and declarations you need to invoke system calls and
632
     libraries.
633
 
634
   * Your own header files contain declarations for interfaces between
635
     the source files of your program.  Each time you have a group of
636
     related declarations and macro definitions all or most of which
637
     are needed in several different source files, it is a good idea to
638
     create a header file for them.
639
 
640
   Including a header file produces the same results as copying the
641
header file into each source file that needs it.  Such copying would be
642
time-consuming and error-prone.  With a header file, the related
643
declarations appear in only one place.  If they need to be changed, they
644
can be changed in one place, and programs that include the header file
645
will automatically use the new version when next recompiled.  The header
646
file eliminates the labor of finding and changing all the copies as well
647
as the risk that a failure to find one copy will result in
648
inconsistencies within a program.
649
 
650
   In C, the usual convention is to give header files names that end
651
with `.h'.  It is most portable to use only letters, digits, dashes, and
652
underscores in header file names, and at most one dot.
653
 
654
* Menu:
655
 
656
* Include Syntax::
657
* Include Operation::
658
* Search Path::
659
* Once-Only Headers::
660
* Computed Includes::
661
* Wrapper Headers::
662
* System Headers::
663
 
664

665
File: cpp.info,  Node: Include Syntax,  Next: Include Operation,  Up: Header Files
666
 
667
2.1 Include Syntax
668
==================
669
 
670
Both user and system header files are included using the preprocessing
671
directive `#include'.  It has two variants:
672
 
673
`#include '
674
     This variant is used for system header files.  It searches for a
675
     file named FILE in a standard list of system directories.  You can
676
     prepend directories to this list with the `-I' option (*note
677
     Invocation::).
678
 
679
`#include "FILE"'
680
     This variant is used for header files of your own program.  It
681
     searches for a file named FILE first in the directory containing
682
     the current file, then in the quote directories and then the same
683
     directories used for `'.  You can prepend directories to the
684
     list of quote directories with the `-iquote' option.
685
 
686
   The argument of `#include', whether delimited with quote marks or
687
angle brackets, behaves like a string constant in that comments are not
688
recognized, and macro names are not expanded.  Thus, `#include '
689
specifies inclusion of a system header file named `x/*y'.
690
 
691
   However, if backslashes occur within FILE, they are considered
692
ordinary text characters, not escape characters.  None of the character
693
escape sequences appropriate to string constants in C are processed.
694
Thus, `#include "x\n\\y"' specifies a filename containing three
695
backslashes.  (Some systems interpret `\' as a pathname separator.  All
696
of these also interpret `/' the same way.  It is most portable to use
697
only `/'.)
698
 
699
   It is an error if there is anything (other than comments) on the line
700
after the file name.
701
 
702

703
File: cpp.info,  Node: Include Operation,  Next: Search Path,  Prev: Include Syntax,  Up: Header Files
704
 
705
2.2 Include Operation
706
=====================
707
 
708
The `#include' directive works by directing the C preprocessor to scan
709
the specified file as input before continuing with the rest of the
710
current file.  The output from the preprocessor contains the output
711
already generated, followed by the output resulting from the included
712
file, followed by the output that comes from the text after the
713
`#include' directive.  For example, if you have a header file
714
`header.h' as follows,
715
 
716
     char *test (void);
717
 
718
and a main program called `program.c' that uses the header file, like
719
this,
720
 
721
     int x;
722
     #include "header.h"
723
 
724
     int
725
     main (void)
726
     {
727
       puts (test ());
728
     }
729
 
730
the compiler will see the same token stream as it would if `program.c'
731
read
732
 
733
     int x;
734
     char *test (void);
735
 
736
     int
737
     main (void)
738
     {
739
       puts (test ());
740
     }
741
 
742
   Included files are not limited to declarations and macro definitions;
743
those are merely the typical uses.  Any fragment of a C program can be
744
included from another file.  The include file could even contain the
745
beginning of a statement that is concluded in the containing file, or
746
the end of a statement that was started in the including file.  However,
747
an included file must consist of complete tokens.  Comments and string
748
literals which have not been closed by the end of an included file are
749
invalid.  For error recovery, they are considered to end at the end of
750
the file.
751
 
752
   To avoid confusion, it is best if header files contain only complete
753
syntactic units--function declarations or definitions, type
754
declarations, etc.
755
 
756
   The line following the `#include' directive is always treated as a
757
separate line by the C preprocessor, even if the included file lacks a
758
final newline.
759
 
760

761
File: cpp.info,  Node: Search Path,  Next: Once-Only Headers,  Prev: Include Operation,  Up: Header Files
762
 
763
2.3 Search Path
764
===============
765
 
766
GCC looks in several different places for headers.  On a normal Unix
767
system, if you do not instruct it otherwise, it will look for headers
768
requested with `#include ' in:
769
 
770
     /usr/local/include
771
     LIBDIR/gcc/TARGET/VERSION/include
772
     /usr/TARGET/include
773
     /usr/include
774
 
775
   For C++ programs, it will also look in `/usr/include/g++-v3', first.
776
In the above, TARGET is the canonical name of the system GCC was
777
configured to compile code for; often but not always the same as the
778
canonical name of the system it runs on.  VERSION is the version of GCC
779
in use.
780
 
781
   You can add to this list with the `-IDIR' command line option.  All
782
the directories named by `-I' are searched, in left-to-right order,
783
_before_ the default directories.  The only exception is when `dir' is
784
already searched by default.  In this case, the option is ignored and
785
the search order for system directories remains unchanged.
786
 
787
   Duplicate directories are removed from the quote and bracket search
788
chains before the two chains are merged to make the final search chain.
789
Thus, it is possible for a directory to occur twice in the final search
790
chain if it was specified in both the quote and bracket chains.
791
 
792
   You can prevent GCC from searching any of the default directories
793
with the `-nostdinc' option.  This is useful when you are compiling an
794
operating system kernel or some other program that does not use the
795
standard C library facilities, or the standard C library itself.  `-I'
796
options are not ignored as described above when `-nostdinc' is in
797
effect.
798
 
799
   GCC looks for headers requested with `#include "FILE"' first in the
800
directory containing the current file, then in the directories as
801
specified by `-iquote' options, then in the same places it would have
802
looked for a header requested with angle brackets.  For example, if
803
`/usr/include/sys/stat.h' contains `#include "types.h"', GCC looks for
804
`types.h' first in `/usr/include/sys', then in its usual search path.
805
 
806
   `#line' (*note Line Control::) does not change GCC's idea of the
807
directory containing the current file.
808
 
809
   You may put `-I-' at any point in your list of `-I' options.  This
810
has two effects.  First, directories appearing before the `-I-' in the
811
list are searched only for headers requested with quote marks.
812
Directories after `-I-' are searched for all headers.  Second, the
813
directory containing the current file is not searched for anything,
814
unless it happens to be one of the directories named by an `-I' switch.
815
`-I-' is deprecated, `-iquote' should be used instead.
816
 
817
   `-I. -I-' is not the same as no `-I' options at all, and does not
818
cause the same behavior for `<>' includes that `""' includes get with
819
no special options.  `-I.' searches the compiler's current working
820
directory for header files.  That may or may not be the same as the
821
directory containing the current file.
822
 
823
   If you need to look for headers in a directory named `-', write
824
`-I./-'.
825
 
826
   There are several more ways to adjust the header search path.  They
827
are generally less useful.  *Note Invocation::.
828
 
829

830
File: cpp.info,  Node: Once-Only Headers,  Next: Computed Includes,  Prev: Search Path,  Up: Header Files
831
 
832
2.4 Once-Only Headers
833
=====================
834
 
835
If a header file happens to be included twice, the compiler will process
836
its contents twice.  This is very likely to cause an error, e.g. when
837
the compiler sees the same structure definition twice.  Even if it does
838
not, it will certainly waste time.
839
 
840
   The standard way to prevent this is to enclose the entire real
841
contents of the file in a conditional, like this:
842
 
843
     /* File foo.  */
844
     #ifndef FILE_FOO_SEEN
845
     #define FILE_FOO_SEEN
846
 
847
     THE ENTIRE FILE
848
 
849
     #endif /* !FILE_FOO_SEEN */
850
 
851
   This construct is commonly known as a "wrapper #ifndef".  When the
852
header is included again, the conditional will be false, because
853
`FILE_FOO_SEEN' is defined.  The preprocessor will skip over the entire
854
contents of the file, and the compiler will not see it twice.
855
 
856
   CPP optimizes even further.  It remembers when a header file has a
857
wrapper `#ifndef'.  If a subsequent `#include' specifies that header,
858
and the macro in the `#ifndef' is still defined, it does not bother to
859
rescan the file at all.
860
 
861
   You can put comments outside the wrapper.  They will not interfere
862
with this optimization.
863
 
864
   The macro `FILE_FOO_SEEN' is called the "controlling macro" or
865
"guard macro".  In a user header file, the macro name should not begin
866
with `_'.  In a system header file, it should begin with `__' to avoid
867
conflicts with user programs.  In any kind of header file, the macro
868
name should contain the name of the file and some additional text, to
869
avoid conflicts with other header files.
870
 
871

872
File: cpp.info,  Node: Computed Includes,  Next: Wrapper Headers,  Prev: Once-Only Headers,  Up: Header Files
873
 
874
2.5 Computed Includes
875
=====================
876
 
877
Sometimes it is necessary to select one of several different header
878
files to be included into your program.  They might specify
879
configuration parameters to be used on different sorts of operating
880
systems, for instance.  You could do this with a series of conditionals,
881
 
882
     #if SYSTEM_1
883
     # include "system_1.h"
884
     #elif SYSTEM_2
885
     # include "system_2.h"
886
     #elif SYSTEM_3
887
     ...
888
     #endif
889
 
890
   That rapidly becomes tedious.  Instead, the preprocessor offers the
891
ability to use a macro for the header name.  This is called a "computed
892
include".  Instead of writing a header name as the direct argument of
893
`#include', you simply put a macro name there instead:
894
 
895
     #define SYSTEM_H "system_1.h"
896
     ...
897
     #include SYSTEM_H
898
 
899
`SYSTEM_H' will be expanded, and the preprocessor will look for
900
`system_1.h' as if the `#include' had been written that way originally.
901
`SYSTEM_H' could be defined by your Makefile with a `-D' option.
902
 
903
   You must be careful when you define the macro.  `#define' saves
904
tokens, not text.  The preprocessor has no way of knowing that the macro
905
will be used as the argument of `#include', so it generates ordinary
906
tokens, not a header name.  This is unlikely to cause problems if you
907
use double-quote includes, which are close enough to string constants.
908
If you use angle brackets, however, you may have trouble.
909
 
910
   The syntax of a computed include is actually a bit more general than
911
the above.  If the first non-whitespace character after `#include' is
912
not `"' or `<', then the entire line is macro-expanded like running
913
text would be.
914
 
915
   If the line expands to a single string constant, the contents of that
916
string constant are the file to be included.  CPP does not re-examine
917
the string for embedded quotes, but neither does it process backslash
918
escapes in the string.  Therefore
919
 
920
     #define HEADER "a\"b"
921
     #include HEADER
922
 
923
looks for a file named `a\"b'.  CPP searches for the file according to
924
the rules for double-quoted includes.
925
 
926
   If the line expands to a token stream beginning with a `<' token and
927
including a `>' token, then the tokens between the `<' and the first
928
`>' are combined to form the filename to be included.  Any whitespace
929
between tokens is reduced to a single space; then any space after the
930
initial `<' is retained, but a trailing space before the closing `>' is
931
ignored.  CPP searches for the file according to the rules for
932
angle-bracket includes.
933
 
934
   In either case, if there are any tokens on the line after the file
935
name, an error occurs and the directive is not processed.  It is also
936
an error if the result of expansion does not match either of the two
937
expected forms.
938
 
939
   These rules are implementation-defined behavior according to the C
940
standard.  To minimize the risk of different compilers interpreting your
941
computed includes differently, we recommend you use only a single
942
object-like macro which expands to a string constant.  This will also
943
minimize confusion for people reading your program.
944
 
945

946
File: cpp.info,  Node: Wrapper Headers,  Next: System Headers,  Prev: Computed Includes,  Up: Header Files
947
 
948
2.6 Wrapper Headers
949
===================
950
 
951
Sometimes it is necessary to adjust the contents of a system-provided
952
header file without editing it directly.  GCC's `fixincludes' operation
953
does this, for example.  One way to do that would be to create a new
954
header file with the same name and insert it in the search path before
955
the original header.  That works fine as long as you're willing to
956
replace the old header entirely.  But what if you want to refer to the
957
old header from the new one?
958
 
959
   You cannot simply include the old header with `#include'.  That will
960
start from the beginning, and find your new header again.  If your
961
header is not protected from multiple inclusion (*note Once-Only
962
Headers::), it will recurse infinitely and cause a fatal error.
963
 
964
   You could include the old header with an absolute pathname:
965
     #include "/usr/include/old-header.h"
966
   This works, but is not clean; should the system headers ever move,
967
you would have to edit the new headers to match.
968
 
969
   There is no way to solve this problem within the C standard, but you
970
can use the GNU extension `#include_next'.  It means, "Include the
971
_next_ file with this name".  This directive works like `#include'
972
except in searching for the specified file: it starts searching the
973
list of header file directories _after_ the directory in which the
974
current file was found.
975
 
976
   Suppose you specify `-I /usr/local/include', and the list of
977
directories to search also includes `/usr/include'; and suppose both
978
directories contain `signal.h'.  Ordinary `#include ' finds
979
the file under `/usr/local/include'.  If that file contains
980
`#include_next ', it starts searching after that directory,
981
and finds the file in `/usr/include'.
982
 
983
   `#include_next' does not distinguish between `' and `"FILE"'
984
inclusion, nor does it check that the file you specify has the same
985
name as the current file.  It simply looks for the file named, starting
986
with the directory in the search path after the one where the current
987
file was found.
988
 
989
   The use of `#include_next' can lead to great confusion.  We
990
recommend it be used only when there is no other alternative.  In
991
particular, it should not be used in the headers belonging to a specific
992
program; it should be used only to make global corrections along the
993
lines of `fixincludes'.
994
 
995

996
File: cpp.info,  Node: System Headers,  Prev: Wrapper Headers,  Up: Header Files
997
 
998
2.7 System Headers
999
==================
1000
 
1001
The header files declaring interfaces to the operating system and
1002
runtime libraries often cannot be written in strictly conforming C.
1003
Therefore, GCC gives code found in "system headers" special treatment.
1004
All warnings, other than those generated by `#warning' (*note
1005
Diagnostics::), are suppressed while GCC is processing a system header.
1006
Macros defined in a system header are immune to a few warnings
1007
wherever they are expanded.  This immunity is granted on an ad-hoc
1008
basis, when we find that a warning generates lots of false positives
1009
because of code in macros defined in system headers.
1010
 
1011
   Normally, only the headers found in specific directories are
1012
considered system headers.  These directories are determined when GCC
1013
is compiled.  There are, however, two ways to make normal headers into
1014
system headers.
1015
 
1016
   The `-isystem' command line option adds its argument to the list of
1017
directories to search for headers, just like `-I'.  Any headers found
1018
in that directory will be considered system headers.
1019
 
1020
   All directories named by `-isystem' are searched _after_ all
1021
directories named by `-I', no matter what their order was on the
1022
command line.  If the same directory is named by both `-I' and
1023
`-isystem', the `-I' option is ignored.  GCC provides an informative
1024
message when this occurs if `-v' is used.
1025
 
1026
   There is also a directive, `#pragma GCC system_header', which tells
1027
GCC to consider the rest of the current include file a system header,
1028
no matter where it was found.  Code that comes before the `#pragma' in
1029
the file will not be affected.  `#pragma GCC system_header' has no
1030
effect in the primary source file.
1031
 
1032
   On very old systems, some of the pre-defined system header
1033
directories get even more special treatment.  GNU C++ considers code in
1034
headers found in those directories to be surrounded by an `extern "C"'
1035
block.  There is no way to request this behavior with a `#pragma', or
1036
from the command line.
1037
 
1038

1039
File: cpp.info,  Node: Macros,  Next: Conditionals,  Prev: Header Files,  Up: Top
1040
 
1041
3 Macros
1042
********
1043
 
1044
A "macro" is a fragment of code which has been given a name.  Whenever
1045
the name is used, it is replaced by the contents of the macro.  There
1046
are two kinds of macros.  They differ mostly in what they look like
1047
when they are used.  "Object-like" macros resemble data objects when
1048
used, "function-like" macros resemble function calls.
1049
 
1050
   You may define any valid identifier as a macro, even if it is a C
1051
keyword.  The preprocessor does not know anything about keywords.  This
1052
can be useful if you wish to hide a keyword such as `const' from an
1053
older compiler that does not understand it.  However, the preprocessor
1054
operator `defined' (*note Defined::) can never be defined as a macro,
1055
and C++'s named operators (*note C++ Named Operators::) cannot be
1056
macros when you are compiling C++.
1057
 
1058
* Menu:
1059
 
1060
* Object-like Macros::
1061
* Function-like Macros::
1062
* Macro Arguments::
1063
* Stringification::
1064
* Concatenation::
1065
* Variadic Macros::
1066
* Predefined Macros::
1067
* Undefining and Redefining Macros::
1068
* Directives Within Macro Arguments::
1069
* Macro Pitfalls::
1070
 
1071

1072
File: cpp.info,  Node: Object-like Macros,  Next: Function-like Macros,  Up: Macros
1073
 
1074
3.1 Object-like Macros
1075
======================
1076
 
1077
An "object-like macro" is a simple identifier which will be replaced by
1078
a code fragment.  It is called object-like because it looks like a data
1079
object in code that uses it.  They are most commonly used to give
1080
symbolic names to numeric constants.
1081
 
1082
   You create macros with the `#define' directive.  `#define' is
1083
followed by the name of the macro and then the token sequence it should
1084
be an abbreviation for, which is variously referred to as the macro's
1085
"body", "expansion" or "replacement list".  For example,
1086
 
1087
     #define BUFFER_SIZE 1024
1088
 
1089
defines a macro named `BUFFER_SIZE' as an abbreviation for the token
1090
`1024'.  If somewhere after this `#define' directive there comes a C
1091
statement of the form
1092
 
1093
     foo = (char *) malloc (BUFFER_SIZE);
1094
 
1095
then the C preprocessor will recognize and "expand" the macro
1096
`BUFFER_SIZE'.  The C compiler will see the same tokens as it would if
1097
you had written
1098
 
1099
     foo = (char *) malloc (1024);
1100
 
1101
   By convention, macro names are written in uppercase.  Programs are
1102
easier to read when it is possible to tell at a glance which names are
1103
macros.
1104
 
1105
   The macro's body ends at the end of the `#define' line.  You may
1106
continue the definition onto multiple lines, if necessary, using
1107
backslash-newline.  When the macro is expanded, however, it will all
1108
come out on one line.  For example,
1109
 
1110
     #define NUMBERS 1, \
1111
                     2, \
1112
                     3
1113
     int x[] = { NUMBERS };
1114
          ==> int x[] = { 1, 2, 3 };
1115
 
1116
The most common visible consequence of this is surprising line numbers
1117
in error messages.
1118
 
1119
   There is no restriction on what can go in a macro body provided it
1120
decomposes into valid preprocessing tokens.  Parentheses need not
1121
balance, and the body need not resemble valid C code.  (If it does not,
1122
you may get error messages from the C compiler when you use the macro.)
1123
 
1124
   The C preprocessor scans your program sequentially.  Macro
1125
definitions take effect at the place you write them.  Therefore, the
1126
following input to the C preprocessor
1127
 
1128
     foo = X;
1129
     #define X 4
1130
     bar = X;
1131
 
1132
produces
1133
 
1134
     foo = X;
1135
     bar = 4;
1136
 
1137
   When the preprocessor expands a macro name, the macro's expansion
1138
replaces the macro invocation, then the expansion is examined for more
1139
macros to expand.  For example,
1140
 
1141
     #define TABLESIZE BUFSIZE
1142
     #define BUFSIZE 1024
1143
     TABLESIZE
1144
          ==> BUFSIZE
1145
          ==> 1024
1146
 
1147
`TABLESIZE' is expanded first to produce `BUFSIZE', then that macro is
1148
expanded to produce the final result, `1024'.
1149
 
1150
   Notice that `BUFSIZE' was not defined when `TABLESIZE' was defined.
1151
The `#define' for `TABLESIZE' uses exactly the expansion you
1152
specify--in this case, `BUFSIZE'--and does not check to see whether it
1153
too contains macro names.  Only when you _use_ `TABLESIZE' is the
1154
result of its expansion scanned for more macro names.
1155
 
1156
   This makes a difference if you change the definition of `BUFSIZE' at
1157
some point in the source file.  `TABLESIZE', defined as shown, will
1158
always expand using the definition of `BUFSIZE' that is currently in
1159
effect:
1160
 
1161
     #define BUFSIZE 1020
1162
     #define TABLESIZE BUFSIZE
1163
     #undef BUFSIZE
1164
     #define BUFSIZE 37
1165
 
1166
Now `TABLESIZE' expands (in two stages) to `37'.
1167
 
1168
   If the expansion of a macro contains its own name, either directly or
1169
via intermediate macros, it is not expanded again when the expansion is
1170
examined for more macros.  This prevents infinite recursion.  *Note
1171
Self-Referential Macros::, for the precise details.
1172
 
1173

1174
File: cpp.info,  Node: Function-like Macros,  Next: Macro Arguments,  Prev: Object-like Macros,  Up: Macros
1175
 
1176
3.2 Function-like Macros
1177
========================
1178
 
1179
You can also define macros whose use looks like a function call.  These
1180
are called "function-like macros".  To define a function-like macro,
1181
you use the same `#define' directive, but you put a pair of parentheses
1182
immediately after the macro name.  For example,
1183
 
1184
     #define lang_init()  c_init()
1185
     lang_init()
1186
          ==> c_init()
1187
 
1188
   A function-like macro is only expanded if its name appears with a
1189
pair of parentheses after it.  If you write just the name, it is left
1190
alone.  This can be useful when you have a function and a macro of the
1191
same name, and you wish to use the function sometimes.
1192
 
1193
     extern void foo(void);
1194
     #define foo() /* optimized inline version */
1195
     ...
1196
       foo();
1197
       funcptr = foo;
1198
 
1199
   Here the call to `foo()' will use the macro, but the function
1200
pointer will get the address of the real function.  If the macro were to
1201
be expanded, it would cause a syntax error.
1202
 
1203
   If you put spaces between the macro name and the parentheses in the
1204
macro definition, that does not define a function-like macro, it defines
1205
an object-like macro whose expansion happens to begin with a pair of
1206
parentheses.
1207
 
1208
     #define lang_init ()    c_init()
1209
     lang_init()
1210
          ==> () c_init()()
1211
 
1212
   The first two pairs of parentheses in this expansion come from the
1213
macro.  The third is the pair that was originally after the macro
1214
invocation.  Since `lang_init' is an object-like macro, it does not
1215
consume those parentheses.
1216
 
1217

1218
File: cpp.info,  Node: Macro Arguments,  Next: Stringification,  Prev: Function-like Macros,  Up: Macros
1219
 
1220
3.3 Macro Arguments
1221
===================
1222
 
1223
Function-like macros can take "arguments", just like true functions.
1224
To define a macro that uses arguments, you insert "parameters" between
1225
the pair of parentheses in the macro definition that make the macro
1226
function-like.  The parameters must be valid C identifiers, separated
1227
by commas and optionally whitespace.
1228
 
1229
   To invoke a macro that takes arguments, you write the name of the
1230
macro followed by a list of "actual arguments" in parentheses, separated
1231
by commas.  The invocation of the macro need not be restricted to a
1232
single logical line--it can cross as many lines in the source file as
1233
you wish.  The number of arguments you give must match the number of
1234
parameters in the macro definition.  When the macro is expanded, each
1235
use of a parameter in its body is replaced by the tokens of the
1236
corresponding argument.  (You need not use all of the parameters in the
1237
macro body.)
1238
 
1239
   As an example, here is a macro that computes the minimum of two
1240
numeric values, as it is defined in many C programs, and some uses.
1241
 
1242
     #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
1243
       x = min(a, b);          ==>  x = ((a) < (b) ? (a) : (b));
1244
       y = min(1, 2);          ==>  y = ((1) < (2) ? (1) : (2));
1245
       z = min(a + 28, *p);    ==>  z = ((a + 28) < (*p) ? (a + 28) : (*p));
1246
 
1247
(In this small example you can already see several of the dangers of
1248
macro arguments.  *Note Macro Pitfalls::, for detailed explanations.)
1249
 
1250
   Leading and trailing whitespace in each argument is dropped, and all
1251
whitespace between the tokens of an argument is reduced to a single
1252
space.  Parentheses within each argument must balance; a comma within
1253
such parentheses does not end the argument.  However, there is no
1254
requirement for square brackets or braces to balance, and they do not
1255
prevent a comma from separating arguments.  Thus,
1256
 
1257
     macro (array[x = y, x + 1])
1258
 
1259
passes two arguments to `macro': `array[x = y' and `x + 1]'.  If you
1260
want to supply `array[x = y, x + 1]' as an argument, you can write it
1261
as `array[(x = y, x + 1)]', which is equivalent C code.
1262
 
1263
   All arguments to a macro are completely macro-expanded before they
1264
are substituted into the macro body.  After substitution, the complete
1265
text is scanned again for macros to expand, including the arguments.
1266
This rule may seem strange, but it is carefully designed so you need
1267
not worry about whether any function call is actually a macro
1268
invocation.  You can run into trouble if you try to be too clever,
1269
though.  *Note Argument Prescan::, for detailed discussion.
1270
 
1271
   For example, `min (min (a, b), c)' is first expanded to
1272
 
1273
       min (((a) < (b) ? (a) : (b)), (c))
1274
 
1275
and then to
1276
 
1277
     ((((a) < (b) ? (a) : (b))) < (c)
1278
      ? (((a) < (b) ? (a) : (b)))
1279
      : (c))
1280
 
1281
(Line breaks shown here for clarity would not actually be generated.)
1282
 
1283
   You can leave macro arguments empty; this is not an error to the
1284
preprocessor (but many macros will then expand to invalid code).  You
1285
cannot leave out arguments entirely; if a macro takes two arguments,
1286
there must be exactly one comma at the top level of its argument list.
1287
Here are some silly examples using `min':
1288
 
1289
     min(, b)        ==> ((   ) < (b) ? (   ) : (b))
1290
     min(a, )        ==> ((a  ) < ( ) ? (a  ) : ( ))
1291
     min(,)          ==> ((   ) < ( ) ? (   ) : ( ))
1292
     min((,),)       ==> (((,)) < ( ) ? ((,)) : ( ))
1293
 
1294
     min()      error--> macro "min" requires 2 arguments, but only 1 given
1295
     min(,,)    error--> macro "min" passed 3 arguments, but takes just 2
1296
 
1297
   Whitespace is not a preprocessing token, so if a macro `foo' takes
1298
one argument, `foo ()' and `foo ( )' both supply it an empty argument.
1299
Previous GNU preprocessor implementations and documentation were
1300
incorrect on this point, insisting that a function-like macro that
1301
takes a single argument be passed a space if an empty argument was
1302
required.
1303
 
1304
   Macro parameters appearing inside string literals are not replaced by
1305
their corresponding actual arguments.
1306
 
1307
     #define foo(x) x, "x"
1308
     foo(bar)        ==> bar, "x"
1309
 
1310

1311
File: cpp.info,  Node: Stringification,  Next: Concatenation,  Prev: Macro Arguments,  Up: Macros
1312
 
1313
3.4 Stringification
1314
===================
1315
 
1316
Sometimes you may want to convert a macro argument into a string
1317
constant.  Parameters are not replaced inside string constants, but you
1318
can use the `#' preprocessing operator instead.  When a macro parameter
1319
is used with a leading `#', the preprocessor replaces it with the
1320
literal text of the actual argument, converted to a string constant.
1321
Unlike normal parameter replacement, the argument is not macro-expanded
1322
first.  This is called "stringification".
1323
 
1324
   There is no way to combine an argument with surrounding text and
1325
stringify it all together.  Instead, you can write a series of adjacent
1326
string constants and stringified arguments.  The preprocessor will
1327
replace the stringified arguments with string constants.  The C
1328
compiler will then combine all the adjacent string constants into one
1329
long string.
1330
 
1331
   Here is an example of a macro definition that uses stringification:
1332
 
1333
     #define WARN_IF(EXP) \
1334
     do { if (EXP) \
1335
             fprintf (stderr, "Warning: " #EXP "\n"); } \
1336
     while (0)
1337
     WARN_IF (x == 0);
1338
          ==> do { if (x == 0)
1339
                fprintf (stderr, "Warning: " "x == 0" "\n"); } while (0);
1340
 
1341
The argument for `EXP' is substituted once, as-is, into the `if'
1342
statement, and once, stringified, into the argument to `fprintf'.  If
1343
`x' were a macro, it would be expanded in the `if' statement, but not
1344
in the string.
1345
 
1346
   The `do' and `while (0)' are a kludge to make it possible to write
1347
`WARN_IF (ARG);', which the resemblance of `WARN_IF' to a function
1348
would make C programmers want to do; see *Note Swallowing the
1349
Semicolon::.
1350
 
1351
   Stringification in C involves more than putting double-quote
1352
characters around the fragment.  The preprocessor backslash-escapes the
1353
quotes surrounding embedded string constants, and all backslashes
1354
within string and character constants, in order to get a valid C string
1355
constant with the proper contents.  Thus, stringifying `p = "foo\n";'
1356
results in "p = \"foo\\n\";".  However, backslashes that are not inside
1357
string or character constants are not duplicated: `\n' by itself
1358
stringifies to "\n".
1359
 
1360
   All leading and trailing whitespace in text being stringified is
1361
ignored.  Any sequence of whitespace in the middle of the text is
1362
converted to a single space in the stringified result.  Comments are
1363
replaced by whitespace long before stringification happens, so they
1364
never appear in stringified text.
1365
 
1366
   There is no way to convert a macro argument into a character
1367
constant.
1368
 
1369
   If you want to stringify the result of expansion of a macro argument,
1370
you have to use two levels of macros.
1371
 
1372
     #define xstr(s) str(s)
1373
     #define str(s) #s
1374
     #define foo 4
1375
     str (foo)
1376
          ==> "foo"
1377
     xstr (foo)
1378
          ==> xstr (4)
1379
          ==> str (4)
1380
          ==> "4"
1381
 
1382
   `s' is stringified when it is used in `str', so it is not
1383
macro-expanded first.  But `s' is an ordinary argument to `xstr', so it
1384
is completely macro-expanded before `xstr' itself is expanded (*note
1385
Argument Prescan::).  Therefore, by the time `str' gets to its
1386
argument, it has already been macro-expanded.
1387
 
1388

1389
File: cpp.info,  Node: Concatenation,  Next: Variadic Macros,  Prev: Stringification,  Up: Macros
1390
 
1391
3.5 Concatenation
1392
=================
1393
 
1394
It is often useful to merge two tokens into one while expanding macros.
1395
This is called "token pasting" or "token concatenation".  The `##'
1396
preprocessing operator performs token pasting.  When a macro is
1397
expanded, the two tokens on either side of each `##' operator are
1398
combined into a single token, which then replaces the `##' and the two
1399
original tokens in the macro expansion.  Usually both will be
1400
identifiers, or one will be an identifier and the other a preprocessing
1401
number.  When pasted, they make a longer identifier.  This isn't the
1402
only valid case.  It is also possible to concatenate two numbers (or a
1403
number and a name, such as `1.5' and `e3') into a number.  Also,
1404
multi-character operators such as `+=' can be formed by token pasting.
1405
 
1406
   However, two tokens that don't together form a valid token cannot be
1407
pasted together.  For example, you cannot concatenate `x' with `+' in
1408
either order.  If you try, the preprocessor issues a warning and emits
1409
the two tokens.  Whether it puts white space between the tokens is
1410
undefined.  It is common to find unnecessary uses of `##' in complex
1411
macros.  If you get this warning, it is likely that you can simply
1412
remove the `##'.
1413
 
1414
   Both the tokens combined by `##' could come from the macro body, but
1415
you could just as well write them as one token in the first place.
1416
Token pasting is most useful when one or both of the tokens comes from a
1417
macro argument.  If either of the tokens next to an `##' is a parameter
1418
name, it is replaced by its actual argument before `##' executes.  As
1419
with stringification, the actual argument is not macro-expanded first.
1420
If the argument is empty, that `##' has no effect.
1421
 
1422
   Keep in mind that the C preprocessor converts comments to whitespace
1423
before macros are even considered.  Therefore, you cannot create a
1424
comment by concatenating `/' and `*'.  You can put as much whitespace
1425
between `##' and its operands as you like, including comments, and you
1426
can put comments in arguments that will be concatenated.  However, it
1427
is an error if `##' appears at either end of a macro body.
1428
 
1429
   Consider a C program that interprets named commands.  There probably
1430
needs to be a table of commands, perhaps an array of structures declared
1431
as follows:
1432
 
1433
     struct command
1434
     {
1435
       char *name;
1436
       void (*function) (void);
1437
     };
1438
 
1439
     struct command commands[] =
1440
     {
1441
       { "quit", quit_command },
1442
       { "help", help_command },
1443
       ...
1444
     };
1445
 
1446
   It would be cleaner not to have to give each command name twice,
1447
once in the string constant and once in the function name.  A macro
1448
which takes the name of a command as an argument can make this
1449
unnecessary.  The string constant can be created with stringification,
1450
and the function name by concatenating the argument with `_command'.
1451
Here is how it is done:
1452
 
1453
     #define COMMAND(NAME)  { #NAME, NAME ## _command }
1454
 
1455
     struct command commands[] =
1456
     {
1457
       COMMAND (quit),
1458
       COMMAND (help),
1459
       ...
1460
     };
1461
 
1462

1463
File: cpp.info,  Node: Variadic Macros,  Next: Predefined Macros,  Prev: Concatenation,  Up: Macros
1464
 
1465
3.6 Variadic Macros
1466
===================
1467
 
1468
A macro can be declared to accept a variable number of arguments much as
1469
a function can.  The syntax for defining the macro is similar to that of
1470
a function.  Here is an example:
1471
 
1472
     #define eprintf(...) fprintf (stderr, __VA_ARGS__)
1473
 
1474
   This kind of macro is called "variadic".  When the macro is invoked,
1475
all the tokens in its argument list after the last named argument (this
1476
macro has none), including any commas, become the "variable argument".
1477
This sequence of tokens replaces the identifier `__VA_ARGS__' in the
1478
macro body wherever it appears.  Thus, we have this expansion:
1479
 
1480
     eprintf ("%s:%d: ", input_file, lineno)
1481
          ==>  fprintf (stderr, "%s:%d: ", input_file, lineno)
1482
 
1483
   The variable argument is completely macro-expanded before it is
1484
inserted into the macro expansion, just like an ordinary argument.  You
1485
may use the `#' and `##' operators to stringify the variable argument
1486
or to paste its leading or trailing token with another token.  (But see
1487
below for an important special case for `##'.)
1488
 
1489
   If your macro is complicated, you may want a more descriptive name
1490
for the variable argument than `__VA_ARGS__'.  CPP permits this, as an
1491
extension.  You may write an argument name immediately before the
1492
`...'; that name is used for the variable argument.  The `eprintf'
1493
macro above could be written
1494
 
1495
     #define eprintf(args...) fprintf (stderr, args)
1496
 
1497
using this extension.  You cannot use `__VA_ARGS__' and this extension
1498
in the same macro.
1499
 
1500
   You can have named arguments as well as variable arguments in a
1501
variadic macro.  We could define `eprintf' like this, instead:
1502
 
1503
     #define eprintf(format, ...) fprintf (stderr, format, __VA_ARGS__)
1504
 
1505
This formulation looks more descriptive, but unfortunately it is less
1506
flexible: you must now supply at least one argument after the format
1507
string.  In standard C, you cannot omit the comma separating the named
1508
argument from the variable arguments.  Furthermore, if you leave the
1509
variable argument empty, you will get a syntax error, because there
1510
will be an extra comma after the format string.
1511
 
1512
     eprintf("success!\n", );
1513
          ==> fprintf(stderr, "success!\n", );
1514
 
1515
   GNU CPP has a pair of extensions which deal with this problem.
1516
First, you are allowed to leave the variable argument out entirely:
1517
 
1518
     eprintf ("success!\n")
1519
          ==> fprintf(stderr, "success!\n", );
1520
 
1521
Second, the `##' token paste operator has a special meaning when placed
1522
between a comma and a variable argument.  If you write
1523
 
1524
     #define eprintf(format, ...) fprintf (stderr, format, ##__VA_ARGS__)
1525
 
1526
and the variable argument is left out when the `eprintf' macro is used,
1527
then the comma before the `##' will be deleted.  This does _not_ happen
1528
if you pass an empty argument, nor does it happen if the token
1529
preceding `##' is anything other than a comma.
1530
 
1531
     eprintf ("success!\n")
1532
          ==> fprintf(stderr, "success!\n");
1533
 
1534
The above explanation is ambiguous about the case where the only macro
1535
parameter is a variable arguments parameter, as it is meaningless to
1536
try to distinguish whether no argument at all is an empty argument or a
1537
missing argument.  In this case the C99 standard is clear that the
1538
comma must remain, however the existing GCC extension used to swallow
1539
the comma.  So CPP retains the comma when conforming to a specific C
1540
standard, and drops it otherwise.
1541
 
1542
   C99 mandates that the only place the identifier `__VA_ARGS__' can
1543
appear is in the replacement list of a variadic macro.  It may not be
1544
used as a macro name, macro argument name, or within a different type
1545
of macro.  It may also be forbidden in open text; the standard is
1546
ambiguous.  We recommend you avoid using it except for its defined
1547
purpose.
1548
 
1549
   Variadic macros are a new feature in C99.  GNU CPP has supported them
1550
for a long time, but only with a named variable argument (`args...',
1551
not `...' and `__VA_ARGS__').  If you are concerned with portability to
1552
previous versions of GCC, you should use only named variable arguments.
1553
On the other hand, if you are concerned with portability to other
1554
conforming implementations of C99, you should use only `__VA_ARGS__'.
1555
 
1556
   Previous versions of CPP implemented the comma-deletion extension
1557
much more generally.  We have restricted it in this release to minimize
1558
the differences from C99.  To get the same effect with both this and
1559
previous versions of GCC, the token preceding the special `##' must be
1560
a comma, and there must be white space between that comma and whatever
1561
comes immediately before it:
1562
 
1563
     #define eprintf(format, args...) fprintf (stderr, format , ##args)
1564
 
1565
*Note Differences from previous versions::, for the gory details.
1566
 
1567

1568
File: cpp.info,  Node: Predefined Macros,  Next: Undefining and Redefining Macros,  Prev: Variadic Macros,  Up: Macros
1569
 
1570
3.7 Predefined Macros
1571
=====================
1572
 
1573
Several object-like macros are predefined; you use them without
1574
supplying their definitions.  They fall into three classes: standard,
1575
common, and system-specific.
1576
 
1577
   In C++, there is a fourth category, the named operators.  They act
1578
like predefined macros, but you cannot undefine them.
1579
 
1580
* Menu:
1581
 
1582
* Standard Predefined Macros::
1583
* Common Predefined Macros::
1584
* System-specific Predefined Macros::
1585
* C++ Named Operators::
1586
 
1587

1588
File: cpp.info,  Node: Standard Predefined Macros,  Next: Common Predefined Macros,  Up: Predefined Macros
1589
 
1590
3.7.1 Standard Predefined Macros
1591
--------------------------------
1592
 
1593
The standard predefined macros are specified by the relevant language
1594
standards, so they are available with all compilers that implement
1595
those standards.  Older compilers may not provide all of them.  Their
1596
names all start with double underscores.
1597
 
1598
`__FILE__'
1599
     This macro expands to the name of the current input file, in the
1600
     form of a C string constant.  This is the path by which the
1601
     preprocessor opened the file, not the short name specified in
1602
     `#include' or as the input file name argument.  For example,
1603
     `"/usr/local/include/myheader.h"' is a possible expansion of this
1604
     macro.
1605
 
1606
`__LINE__'
1607
     This macro expands to the current input line number, in the form
1608
     of a decimal integer constant.  While we call it a predefined
1609
     macro, it's a pretty strange macro, since its "definition" changes
1610
     with each new line of source code.
1611
 
1612
   `__FILE__' and `__LINE__' are useful in generating an error message
1613
to report an inconsistency detected by the program; the message can
1614
state the source line at which the inconsistency was detected.  For
1615
example,
1616
 
1617
     fprintf (stderr, "Internal error: "
1618
                      "negative string length "
1619
                      "%d at %s, line %d.",
1620
              length, __FILE__, __LINE__);
1621
 
1622
   An `#include' directive changes the expansions of `__FILE__' and
1623
`__LINE__' to correspond to the included file.  At the end of that
1624
file, when processing resumes on the input file that contained the
1625
`#include' directive, the expansions of `__FILE__' and `__LINE__'
1626
revert to the values they had before the `#include' (but `__LINE__' is
1627
then incremented by one as processing moves to the line after the
1628
`#include').
1629
 
1630
   A `#line' directive changes `__LINE__', and may change `__FILE__' as
1631
well.  *Note Line Control::.
1632
 
1633
   C99 introduces `__func__', and GCC has provided `__FUNCTION__' for a
1634
long time.  Both of these are strings containing the name of the
1635
current function (there are slight semantic differences; see the GCC
1636
manual).  Neither of them is a macro; the preprocessor does not know the
1637
name of the current function.  They tend to be useful in conjunction
1638
with `__FILE__' and `__LINE__', though.
1639
 
1640
`__DATE__'
1641
     This macro expands to a string constant that describes the date on
1642
     which the preprocessor is being run.  The string constant contains
1643
     eleven characters and looks like `"Feb 12 1996"'.  If the day of
1644
     the month is less than 10, it is padded with a space on the left.
1645
 
1646
     If GCC cannot determine the current date, it will emit a warning
1647
     message (once per compilation) and `__DATE__' will expand to
1648
     `"??? ?? ????"'.
1649
 
1650
`__TIME__'
1651
     This macro expands to a string constant that describes the time at
1652
     which the preprocessor is being run.  The string constant contains
1653
     eight characters and looks like `"23:59:01"'.
1654
 
1655
     If GCC cannot determine the current time, it will emit a warning
1656
     message (once per compilation) and `__TIME__' will expand to
1657
     `"??:??:??"'.
1658
 
1659
`__STDC__'
1660
     In normal operation, this macro expands to the constant 1, to
1661
     signify that this compiler conforms to ISO Standard C.  If GNU CPP
1662
     is used with a compiler other than GCC, this is not necessarily
1663
     true; however, the preprocessor always conforms to the standard
1664
     unless the `-traditional-cpp' option is used.
1665
 
1666
     This macro is not defined if the `-traditional-cpp' option is used.
1667
 
1668
     On some hosts, the system compiler uses a different convention,
1669
     where `__STDC__' is normally 0, but is 1 if the user specifies
1670
     strict conformance to the C Standard.  CPP follows the host
1671
     convention when processing system header files, but when
1672
     processing user files `__STDC__' is always 1.  This has been
1673
     reported to cause problems; for instance, some versions of Solaris
1674
     provide X Windows headers that expect `__STDC__' to be either
1675
     undefined or 1.  *Note Invocation::.
1676
 
1677
`__STDC_VERSION__'
1678
     This macro expands to the C Standard's version number, a long
1679
     integer constant of the form `YYYYMML' where YYYY and MM are the
1680
     year and month of the Standard version.  This signifies which
1681
     version of the C Standard the compiler conforms to.  Like
1682
     `__STDC__', this is not necessarily accurate for the entire
1683
     implementation, unless GNU CPP is being used with GCC.
1684
 
1685
     The value `199409L' signifies the 1989 C standard as amended in
1686
     1994, which is the current default; the value `199901L' signifies
1687
     the 1999 revision of the C standard.  Support for the 1999
1688
     revision is not yet complete.
1689
 
1690
     This macro is not defined if the `-traditional-cpp' option is
1691
     used, nor when compiling C++ or Objective-C.
1692
 
1693
`__STDC_HOSTED__'
1694
     This macro is defined, with value 1, if the compiler's target is a
1695
     "hosted environment".  A hosted environment has the complete
1696
     facilities of the standard C library available.
1697
 
1698
`__cplusplus'
1699
     This macro is defined when the C++ compiler is in use.  You can use
1700
     `__cplusplus' to test whether a header is compiled by a C compiler
1701
     or a C++ compiler.  This macro is similar to `__STDC_VERSION__', in
1702
     that it expands to a version number.  A fully conforming
1703
     implementation of the 1998 C++ standard will define this macro to
1704
     `199711L'.  The GNU C++ compiler is not yet fully conforming, so
1705
     it uses `1' instead.  It is hoped to complete the implementation
1706
     of standard C++ in the near future.
1707
 
1708
`__OBJC__'
1709
     This macro is defined, with value 1, when the Objective-C compiler
1710
     is in use.  You can use `__OBJC__' to test whether a header is
1711
     compiled by a C compiler or a Objective-C compiler.
1712
 
1713
`__ASSEMBLER__'
1714
     This macro is defined with value 1 when preprocessing assembly
1715
     language.
1716
 
1717
 
1718

1719
File: cpp.info,  Node: Common Predefined Macros,  Next: System-specific Predefined Macros,  Prev: Standard Predefined Macros,  Up: Predefined Macros
1720
 
1721
3.7.2 Common Predefined Macros
1722
------------------------------
1723
 
1724
The common predefined macros are GNU C extensions.  They are available
1725
with the same meanings regardless of the machine or operating system on
1726
which you are using GNU C.  Their names all start with double
1727
underscores.
1728
 
1729
`__GNUC__'
1730
`__GNUC_MINOR__'
1731
`__GNUC_PATCHLEVEL__'
1732
     These macros are defined by all GNU compilers that use the C
1733
     preprocessor: C, C++, and Objective-C.  Their values are the major
1734
     version, minor version, and patch level of the compiler, as integer
1735
     constants.  For example, GCC 3.2.1 will define `__GNUC__' to 3,
1736
     `__GNUC_MINOR__' to 2, and `__GNUC_PATCHLEVEL__' to 1.  These
1737
     macros are also defined if you invoke the preprocessor directly.
1738
 
1739
     `__GNUC_PATCHLEVEL__' is new to GCC 3.0; it is also present in the
1740
     widely-used development snapshots leading up to 3.0 (which identify
1741
     themselves as GCC 2.96 or 2.97, depending on which snapshot you
1742
     have).
1743
 
1744
     If all you need to know is whether or not your program is being
1745
     compiled by GCC, or a non-GCC compiler that claims to accept the
1746
     GNU C dialects, you can simply test `__GNUC__'.  If you need to
1747
     write code which depends on a specific version, you must be more
1748
     careful.  Each time the minor version is increased, the patch
1749
     level is reset to zero; each time the major version is increased
1750
     (which happens rarely), the minor version and patch level are
1751
     reset.  If you wish to use the predefined macros directly in the
1752
     conditional, you will need to write it like this:
1753
 
1754
          /* Test for GCC > 3.2.0 */
1755
          #if __GNUC__ > 3 || \
1756
              (__GNUC__ == 3 && (__GNUC_MINOR__ > 2 || \
1757
                                 (__GNUC_MINOR__ == 2 && \
1758
                                  __GNUC_PATCHLEVEL__ > 0))
1759
 
1760
     Another approach is to use the predefined macros to calculate a
1761
     single number, then compare that against a threshold:
1762
 
1763
          #define GCC_VERSION (__GNUC__ * 10000 \
1764
                               + __GNUC_MINOR__ * 100 \
1765
                               + __GNUC_PATCHLEVEL__)
1766
          ...
1767
          /* Test for GCC > 3.2.0 */
1768
          #if GCC_VERSION > 30200
1769
 
1770
     Many people find this form easier to understand.
1771
 
1772
`__GNUG__'
1773
     The GNU C++ compiler defines this.  Testing it is equivalent to
1774
     testing `(__GNUC__ && __cplusplus)'.
1775
 
1776
`__STRICT_ANSI__'
1777
     GCC defines this macro if and only if the `-ansi' switch, or a
1778
     `-std' switch specifying strict conformance to some version of ISO
1779
     C, was specified when GCC was invoked.  It is defined to `1'.
1780
     This macro exists primarily to direct GNU libc's header files to
1781
     restrict their definitions to the minimal set found in the 1989 C
1782
     standard.
1783
 
1784
`__BASE_FILE__'
1785
     This macro expands to the name of the main input file, in the form
1786
     of a C string constant.  This is the source file that was specified
1787
     on the command line of the preprocessor or C compiler.
1788
 
1789
`__INCLUDE_LEVEL__'
1790
     This macro expands to a decimal integer constant that represents
1791
     the depth of nesting in include files.  The value of this macro is
1792
     incremented on every `#include' directive and decremented at the
1793
     end of every included file.  It starts out at 0, it's value within
1794
     the base file specified on the command line.
1795
 
1796
`__ELF__'
1797
     This macro is defined if the target uses the ELF object format.
1798
 
1799
`__VERSION__'
1800
     This macro expands to a string constant which describes the
1801
     version of the compiler in use.  You should not rely on its
1802
     contents having any particular form, but it can be counted on to
1803
     contain at least the release number.
1804
 
1805
`__OPTIMIZE__'
1806
`__OPTIMIZE_SIZE__'
1807
`__NO_INLINE__'
1808
     These macros describe the compilation mode.  `__OPTIMIZE__' is
1809
     defined in all optimizing compilations.  `__OPTIMIZE_SIZE__' is
1810
     defined if the compiler is optimizing for size, not speed.
1811
     `__NO_INLINE__' is defined if no functions will be inlined into
1812
     their callers (when not optimizing, or when inlining has been
1813
     specifically disabled by `-fno-inline').
1814
 
1815
     These macros cause certain GNU header files to provide optimized
1816
     definitions, using macros or inline functions, of system library
1817
     functions.  You should not use these macros in any way unless you
1818
     make sure that programs will execute with the same effect whether
1819
     or not they are defined.  If they are defined, their value is 1.
1820
 
1821
`__GNUC_GNU_INLINE__'
1822
     GCC defines this macro if functions declared `inline' will be
1823
     handled in GCC's traditional gnu89 mode.  In this mode an `extern
1824
     inline' function will never be compiled as a standalone function,
1825
     and an `inline' function which is neither `extern' nor `static'
1826
     will always be compiled as a standalone function.
1827
 
1828
`__GNUC_STDC_INLINE__'
1829
     GCC defines this macro if functions declared `inline' will be
1830
     handled according to the ISO C99 standard.  In this mode an
1831
     `extern inline' function will always be compiled as a standalone
1832
     externally visible function, and an `inline' function which is
1833
     neither `extern' nor `static' will never be compiled as a
1834
     standalone function.
1835
 
1836
     If this macro is defined, GCC supports the `gnu_inline' function
1837
     attribute as a way to always get the gnu89 behaviour.  Support for
1838
     this and `__GNUC_GNU_INLINE__' was added in GCC 4.1.3.  If neither
1839
     macro is defined, an older version of GCC is being used: `inline'
1840
     functions will be compiled in gnu89 mode, and the `gnu_inline'
1841
     function attribute will not be recognized.
1842
 
1843
`__CHAR_UNSIGNED__'
1844
     GCC defines this macro if and only if the data type `char' is
1845
     unsigned on the target machine.  It exists to cause the standard
1846
     header file `limits.h' to work correctly.  You should not use this
1847
     macro yourself; instead, refer to the standard macros defined in
1848
     `limits.h'.
1849
 
1850
`__WCHAR_UNSIGNED__'
1851
     Like `__CHAR_UNSIGNED__', this macro is defined if and only if the
1852
     data type `wchar_t' is unsigned and the front-end is in C++ mode.
1853
 
1854
`__REGISTER_PREFIX__'
1855
     This macro expands to a single token (not a string constant) which
1856
     is the prefix applied to CPU register names in assembly language
1857
     for this target.  You can use it to write assembly that is usable
1858
     in multiple environments.  For example, in the `m68k-aout'
1859
     environment it expands to nothing, but in the `m68k-coff'
1860
     environment it expands to a single `%'.
1861
 
1862
`__USER_LABEL_PREFIX__'
1863
     This macro expands to a single token which is the prefix applied to
1864
     user labels (symbols visible to C code) in assembly.  For example,
1865
     in the `m68k-aout' environment it expands to an `_', but in the
1866
     `m68k-coff' environment it expands to nothing.
1867
 
1868
     This macro will have the correct definition even if
1869
     `-f(no-)underscores' is in use, but it will not be correct if
1870
     target-specific options that adjust this prefix are used (e.g. the
1871
     OSF/rose `-mno-underscores' option).
1872
 
1873
`__SIZE_TYPE__'
1874
`__PTRDIFF_TYPE__'
1875
`__WCHAR_TYPE__'
1876
`__WINT_TYPE__'
1877
`__INTMAX_TYPE__'
1878
`__UINTMAX_TYPE__'
1879
     These macros are defined to the correct underlying types for the
1880
     `size_t', `ptrdiff_t', `wchar_t', `wint_t', `intmax_t', and
1881
     `uintmax_t' typedefs, respectively.  They exist to make the
1882
     standard header files `stddef.h' and `wchar.h' work correctly.
1883
     You should not use these macros directly; instead, include the
1884
     appropriate headers and use the typedefs.
1885
 
1886
`__CHAR_BIT__'
1887
     Defined to the number of bits used in the representation of the
1888
     `char' data type.  It exists to make the standard header given
1889
     numerical limits work correctly.  You should not use this macro
1890
     directly; instead, include the appropriate headers.
1891
 
1892
`__SCHAR_MAX__'
1893
`__WCHAR_MAX__'
1894
`__SHRT_MAX__'
1895
`__INT_MAX__'
1896
`__LONG_MAX__'
1897
`__LONG_LONG_MAX__'
1898
`__INTMAX_MAX__'
1899
     Defined to the maximum value of the `signed char', `wchar_t',
1900
     `signed short', `signed int', `signed long', `signed long long',
1901
     and `intmax_t' types respectively.  They exist to make the
1902
     standard header given numerical limits work correctly.  You should
1903
     not use these macros directly; instead, include the appropriate
1904
     headers.
1905
 
1906
`__DEPRECATED'
1907
     This macro is defined, with value 1, when compiling a C++ source
1908
     file with warnings about deprecated constructs enabled.  These
1909
     warnings are enabled by default, but can be disabled with
1910
     `-Wno-deprecated'.
1911
 
1912
`__EXCEPTIONS'
1913
     This macro is defined, with value 1, when compiling a C++ source
1914
     file with exceptions enabled.  If `-fno-exceptions' was used when
1915
     compiling the file, then this macro will not be defined.
1916
 
1917
`__USING_SJLJ_EXCEPTIONS__'
1918
     This macro is defined, with value 1, if the compiler uses the old
1919
     mechanism based on `setjmp' and `longjmp' for exception handling.
1920
 
1921
`__GXX_WEAK__'
1922
     This macro is defined when compiling a C++ source file.  It has the
1923
     value 1 if the compiler will use weak symbols, COMDAT sections, or
1924
     other similar techniques to collapse symbols with "vague linkage"
1925
     that are defined in multiple translation units.  If the compiler
1926
     will not collapse such symbols, this macro is defined with value
1927
     0.  In general, user code should not need to make use of this
1928
     macro; the purpose of this macro is to ease implementation of the
1929
     C++ runtime library provided with G++.
1930
 
1931
`__NEXT_RUNTIME__'
1932
     This macro is defined, with value 1, if (and only if) the NeXT
1933
     runtime (as in `-fnext-runtime') is in use for Objective-C.  If
1934
     the GNU runtime is used, this macro is not defined, so that you
1935
     can use this macro to determine which runtime (NeXT or GNU) is
1936
     being used.
1937
 
1938
`__LP64__'
1939
`_LP64'
1940
     These macros are defined, with value 1, if (and only if) the
1941
     compilation is for a target where `long int' and pointer both use
1942
     64-bits and `int' uses 32-bit.
1943
 
1944
`__SSP__'
1945
     This macro is defined, with value 1, when `-fstack-protector' is in
1946
     use.
1947
 
1948
`__SSP_ALL__'
1949
     This macro is defined, with value 2, when `-fstack-protector-all'
1950
     is in use.
1951
 
1952
`__TIMESTAMP__'
1953
     This macro expands to a string constant that describes the date
1954
     and time of the last modification of the current source file. The
1955
     string constant contains abbreviated day of the week, month, day
1956
     of the month, time in hh:mm:ss form, year and looks like
1957
     `"Sun Sep 16 01:03:52 1973"'.  If the day of the month is less
1958
     than 10, it is padded with a space on the left.
1959
 
1960
     If GCC cannot determine the current date, it will emit a warning
1961
     message (once per compilation) and `__TIMESTAMP__' will expand to
1962
     `"??? ??? ?? ??:??:?? ????"'.
1963
 
1964
 
1965

1966
File: cpp.info,  Node: System-specific Predefined Macros,  Next: C++ Named Operators,  Prev: Common Predefined Macros,  Up: Predefined Macros
1967
 
1968
3.7.3 System-specific Predefined Macros
1969
---------------------------------------
1970
 
1971
The C preprocessor normally predefines several macros that indicate what
1972
type of system and machine is in use.  They are obviously different on
1973
each target supported by GCC.  This manual, being for all systems and
1974
machines, cannot tell you what their names are, but you can use `cpp
1975
-dM' to see them all.  *Note Invocation::.  All system-specific
1976
predefined macros expand to the constant 1, so you can test them with
1977
either `#ifdef' or `#if'.
1978
 
1979
   The C standard requires that all system-specific macros be part of
1980
the "reserved namespace".  All names which begin with two underscores,
1981
or an underscore and a capital letter, are reserved for the compiler and
1982
library to use as they wish.  However, historically system-specific
1983
macros have had names with no special prefix; for instance, it is common
1984
to find `unix' defined on Unix systems.  For all such macros, GCC
1985
provides a parallel macro with two underscores added at the beginning
1986
and the end.  If `unix' is defined, `__unix__' will be defined too.
1987
There will never be more than two underscores; the parallel of `_mips'
1988
is `__mips__'.
1989
 
1990
   When the `-ansi' option, or any `-std' option that requests strict
1991
conformance, is given to the compiler, all the system-specific
1992
predefined macros outside the reserved namespace are suppressed.  The
1993
parallel macros, inside the reserved namespace, remain defined.
1994
 
1995
   We are slowly phasing out all predefined macros which are outside the
1996
reserved namespace.  You should never use them in new programs, and we
1997
encourage you to correct older code to use the parallel macros whenever
1998
you find it.  We don't recommend you use the system-specific macros that
1999
are in the reserved namespace, either.  It is better in the long run to
2000
check specifically for features you need, using a tool such as
2001
`autoconf'.
2002
 
2003

2004
File: cpp.info,  Node: C++ Named Operators,  Prev: System-specific Predefined Macros,  Up: Predefined Macros
2005
 
2006
3.7.4 C++ Named Operators
2007
-------------------------
2008
 
2009
In C++, there are eleven keywords which are simply alternate spellings
2010
of operators normally written with punctuation.  These keywords are
2011
treated as such even in the preprocessor.  They function as operators in
2012
`#if', and they cannot be defined as macros or poisoned.  In C, you can
2013
request that those keywords take their C++ meaning by including
2014
`iso646.h'.  That header defines each one as a normal object-like macro
2015
expanding to the appropriate punctuator.
2016
 
2017
   These are the named operators and their corresponding punctuators:
2018
 
2019
Named Operator   Punctuator
2020
`and'            `&&'
2021
`and_eq'         `&='
2022
`bitand'         `&'
2023
`bitor'          `|'
2024
`compl'          `~'
2025
`not'            `!'
2026
`not_eq'         `!='
2027
`or'             `||'
2028
`or_eq'          `|='
2029
`xor'            `^'
2030
`xor_eq'         `^='
2031
 
2032

2033
File: cpp.info,  Node: Undefining and Redefining Macros,  Next: Directives Within Macro Arguments,  Prev: Predefined Macros,  Up: Macros
2034
 
2035
3.8 Undefining and Redefining Macros
2036
====================================
2037
 
2038
If a macro ceases to be useful, it may be "undefined" with the `#undef'
2039
directive.  `#undef' takes a single argument, the name of the macro to
2040
undefine.  You use the bare macro name, even if the macro is
2041
function-like.  It is an error if anything appears on the line after
2042
the macro name.  `#undef' has no effect if the name is not a macro.
2043
 
2044
     #define FOO 4
2045
     x = FOO;        ==> x = 4;
2046
     #undef FOO
2047
     x = FOO;        ==> x = FOO;
2048
 
2049
   Once a macro has been undefined, that identifier may be "redefined"
2050
as a macro by a subsequent `#define' directive.  The new definition
2051
need not have any resemblance to the old definition.
2052
 
2053
   However, if an identifier which is currently a macro is redefined,
2054
then the new definition must be "effectively the same" as the old one.
2055
Two macro definitions are effectively the same if:
2056
   * Both are the same type of macro (object- or function-like).
2057
 
2058
   * All the tokens of the replacement list are the same.
2059
 
2060
   * If there are any parameters, they are the same.
2061
 
2062
   * Whitespace appears in the same places in both.  It need not be
2063
     exactly the same amount of whitespace, though.  Remember that
2064
     comments count as whitespace.
2065
 
2066
These definitions are effectively the same:
2067
     #define FOUR (2 + 2)
2068
     #define FOUR         (2    +    2)
2069
     #define FOUR (2 /* two */ + 2)
2070
   but these are not:
2071
     #define FOUR (2 + 2)
2072
     #define FOUR ( 2+2 )
2073
     #define FOUR (2 * 2)
2074
     #define FOUR(score,and,seven,years,ago) (2 + 2)
2075
 
2076
   If a macro is redefined with a definition that is not effectively the
2077
same as the old one, the preprocessor issues a warning and changes the
2078
macro to use the new definition.  If the new definition is effectively
2079
the same, the redefinition is silently ignored.  This allows, for
2080
instance, two different headers to define a common macro.  The
2081
preprocessor will only complain if the definitions do not match.
2082
 
2083

2084
File: cpp.info,  Node: Directives Within Macro Arguments,  Next: Macro Pitfalls,  Prev: Undefining and Redefining Macros,  Up: Macros
2085
 
2086
3.9 Directives Within Macro Arguments
2087
=====================================
2088
 
2089
Occasionally it is convenient to use preprocessor directives within the
2090
arguments of a macro.  The C and C++ standards declare that behavior in
2091
these cases is undefined.
2092
 
2093
   Versions of CPP prior to 3.2 would reject such constructs with an
2094
error message.  This was the only syntactic difference between normal
2095
functions and function-like macros, so it seemed attractive to remove
2096
this limitation, and people would often be surprised that they could
2097
not use macros in this way.  Moreover, sometimes people would use
2098
conditional compilation in the argument list to a normal library
2099
function like `printf', only to find that after a library upgrade
2100
`printf' had changed to be a function-like macro, and their code would
2101
no longer compile.  So from version 3.2 we changed CPP to successfully
2102
process arbitrary directives within macro arguments in exactly the same
2103
way as it would have processed the directive were the function-like
2104
macro invocation not present.
2105
 
2106
   If, within a macro invocation, that macro is redefined, then the new
2107
definition takes effect in time for argument pre-expansion, but the
2108
original definition is still used for argument replacement.  Here is a
2109
pathological example:
2110
 
2111
     #define f(x) x x
2112
     f (1
2113
     #undef f
2114
     #define f 2
2115
     f)
2116
 
2117
which expands to
2118
 
2119
     1 2 1 2
2120
 
2121
with the semantics described above.
2122
 
2123

2124
File: cpp.info,  Node: Macro Pitfalls,  Prev: Directives Within Macro Arguments,  Up: Macros
2125
 
2126
3.10 Macro Pitfalls
2127
===================
2128
 
2129
In this section we describe some special rules that apply to macros and
2130
macro expansion, and point out certain cases in which the rules have
2131
counter-intuitive consequences that you must watch out for.
2132
 
2133
* Menu:
2134
 
2135
* Misnesting::
2136
* Operator Precedence Problems::
2137
* Swallowing the Semicolon::
2138
* Duplication of Side Effects::
2139
* Self-Referential Macros::
2140
* Argument Prescan::
2141
* Newlines in Arguments::
2142
 
2143

2144
File: cpp.info,  Node: Misnesting,  Next: Operator Precedence Problems,  Up: Macro Pitfalls
2145
 
2146
3.10.1 Misnesting
2147
-----------------
2148
 
2149
When a macro is called with arguments, the arguments are substituted
2150
into the macro body and the result is checked, together with the rest of
2151
the input file, for more macro calls.  It is possible to piece together
2152
a macro call coming partially from the macro body and partially from the
2153
arguments.  For example,
2154
 
2155
     #define twice(x) (2*(x))
2156
     #define call_with_1(x) x(1)
2157
     call_with_1 (twice)
2158
          ==> twice(1)
2159
          ==> (2*(1))
2160
 
2161
   Macro definitions do not have to have balanced parentheses.  By
2162
writing an unbalanced open parenthesis in a macro body, it is possible
2163
to create a macro call that begins inside the macro body but ends
2164
outside of it.  For example,
2165
 
2166
     #define strange(file) fprintf (file, "%s %d",
2167
     ...
2168
     strange(stderr) p, 35)
2169
          ==> fprintf (stderr, "%s %d", p, 35)
2170
 
2171
   The ability to piece together a macro call can be useful, but the
2172
use of unbalanced open parentheses in a macro body is just confusing,
2173
and should be avoided.
2174
 
2175

2176
File: cpp.info,  Node: Operator Precedence Problems,  Next: Swallowing the Semicolon,  Prev: Misnesting,  Up: Macro Pitfalls
2177
 
2178
3.10.2 Operator Precedence Problems
2179
-----------------------------------
2180
 
2181
You may have noticed that in most of the macro definition examples shown
2182
above, each occurrence of a macro argument name had parentheses around
2183
it.  In addition, another pair of parentheses usually surround the
2184
entire macro definition.  Here is why it is best to write macros that
2185
way.
2186
 
2187
   Suppose you define a macro as follows,
2188
 
2189
     #define ceil_div(x, y) (x + y - 1) / y
2190
 
2191
whose purpose is to divide, rounding up.  (One use for this operation is
2192
to compute how many `int' objects are needed to hold a certain number
2193
of `char' objects.)  Then suppose it is used as follows:
2194
 
2195
     a = ceil_div (b & c, sizeof (int));
2196
          ==> a = (b & c + sizeof (int) - 1) / sizeof (int);
2197
 
2198
This does not do what is intended.  The operator-precedence rules of C
2199
make it equivalent to this:
2200
 
2201
     a = (b & (c + sizeof (int) - 1)) / sizeof (int);
2202
 
2203
What we want is this:
2204
 
2205
     a = ((b & c) + sizeof (int) - 1)) / sizeof (int);
2206
 
2207
Defining the macro as
2208
 
2209
     #define ceil_div(x, y) ((x) + (y) - 1) / (y)
2210
 
2211
provides the desired result.
2212
 
2213
   Unintended grouping can result in another way.  Consider `sizeof
2214
ceil_div(1, 2)'.  That has the appearance of a C expression that would
2215
compute the size of the type of `ceil_div (1, 2)', but in fact it means
2216
something very different.  Here is what it expands to:
2217
 
2218
     sizeof ((1) + (2) - 1) / (2)
2219
 
2220
This would take the size of an integer and divide it by two.  The
2221
precedence rules have put the division outside the `sizeof' when it was
2222
intended to be inside.
2223
 
2224
   Parentheses around the entire macro definition prevent such problems.
2225
Here, then, is the recommended way to define `ceil_div':
2226
 
2227
     #define ceil_div(x, y) (((x) + (y) - 1) / (y))
2228
 
2229

2230
File: cpp.info,  Node: Swallowing the Semicolon,  Next: Duplication of Side Effects,  Prev: Operator Precedence Problems,  Up: Macro Pitfalls
2231
 
2232
3.10.3 Swallowing the Semicolon
2233
-------------------------------
2234
 
2235
Often it is desirable to define a macro that expands into a compound
2236
statement.  Consider, for example, the following macro, that advances a
2237
pointer (the argument `p' says where to find it) across whitespace
2238
characters:
2239
 
2240
     #define SKIP_SPACES(p, limit)  \
2241
     { char *lim = (limit);         \
2242
       while (p < lim) {            \
2243
         if (*p++ != ' ') {         \
2244
           p--; break; }}}
2245
 
2246
Here backslash-newline is used to split the macro definition, which must
2247
be a single logical line, so that it resembles the way such code would
2248
be laid out if not part of a macro definition.
2249
 
2250
   A call to this macro might be `SKIP_SPACES (p, lim)'.  Strictly
2251
speaking, the call expands to a compound statement, which is a complete
2252
statement with no need for a semicolon to end it.  However, since it
2253
looks like a function call, it minimizes confusion if you can use it
2254
like a function call, writing a semicolon afterward, as in `SKIP_SPACES
2255
(p, lim);'
2256
 
2257
   This can cause trouble before `else' statements, because the
2258
semicolon is actually a null statement.  Suppose you write
2259
 
2260
     if (*p != 0)
2261
       SKIP_SPACES (p, lim);
2262
     else ...
2263
 
2264
The presence of two statements--the compound statement and a null
2265
statement--in between the `if' condition and the `else' makes invalid C
2266
code.
2267
 
2268
   The definition of the macro `SKIP_SPACES' can be altered to solve
2269
this problem, using a `do ... while' statement.  Here is how:
2270
 
2271
     #define SKIP_SPACES(p, limit)     \
2272
     do { char *lim = (limit);         \
2273
          while (p < lim) {            \
2274
            if (*p++ != ' ') {         \
2275
              p--; break; }}}          \
2276
     while (0)
2277
 
2278
   Now `SKIP_SPACES (p, lim);' expands into
2279
 
2280
     do {...} while (0);
2281
 
2282
which is one statement.  The loop executes exactly once; most compilers
2283
generate no extra code for it.
2284
 
2285

2286
File: cpp.info,  Node: Duplication of Side Effects,  Next: Self-Referential Macros,  Prev: Swallowing the Semicolon,  Up: Macro Pitfalls
2287
 
2288
3.10.4 Duplication of Side Effects
2289
----------------------------------
2290
 
2291
Many C programs define a macro `min', for "minimum", like this:
2292
 
2293
     #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
2294
 
2295
   When you use this macro with an argument containing a side effect,
2296
as shown here,
2297
 
2298
     next = min (x + y, foo (z));
2299
 
2300
it expands as follows:
2301
 
2302
     next = ((x + y) < (foo (z)) ? (x + y) : (foo (z)));
2303
 
2304
where `x + y' has been substituted for `X' and `foo (z)' for `Y'.
2305
 
2306
   The function `foo' is used only once in the statement as it appears
2307
in the program, but the expression `foo (z)' has been substituted twice
2308
into the macro expansion.  As a result, `foo' might be called two times
2309
when the statement is executed.  If it has side effects or if it takes
2310
a long time to compute, the results might not be what you intended.  We
2311
say that `min' is an "unsafe" macro.
2312
 
2313
   The best solution to this problem is to define `min' in a way that
2314
computes the value of `foo (z)' only once.  The C language offers no
2315
standard way to do this, but it can be done with GNU extensions as
2316
follows:
2317
 
2318
     #define min(X, Y)                \
2319
     ({ typeof (X) x_ = (X);          \
2320
        typeof (Y) y_ = (Y);          \
2321
        (x_ < y_) ? x_ : y_; })
2322
 
2323
   The `({ ... })' notation produces a compound statement that acts as
2324
an expression.  Its value is the value of its last statement.  This
2325
permits us to define local variables and assign each argument to one.
2326
The local variables have underscores after their names to reduce the
2327
risk of conflict with an identifier of wider scope (it is impossible to
2328
avoid this entirely).  Now each argument is evaluated exactly once.
2329
 
2330
   If you do not wish to use GNU C extensions, the only solution is to
2331
be careful when _using_ the macro `min'.  For example, you can
2332
calculate the value of `foo (z)', save it in a variable, and use that
2333
variable in `min':
2334
 
2335
     #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
2336
     ...
2337
     {
2338
       int tem = foo (z);
2339
       next = min (x + y, tem);
2340
     }
2341
 
2342
(where we assume that `foo' returns type `int').
2343
 
2344

2345
File: cpp.info,  Node: Self-Referential Macros,  Next: Argument Prescan,  Prev: Duplication of Side Effects,  Up: Macro Pitfalls
2346
 
2347
3.10.5 Self-Referential Macros
2348
------------------------------
2349
 
2350
A "self-referential" macro is one whose name appears in its definition.
2351
Recall that all macro definitions are rescanned for more macros to
2352
replace.  If the self-reference were considered a use of the macro, it
2353
would produce an infinitely large expansion.  To prevent this, the
2354
self-reference is not considered a macro call.  It is passed into the
2355
preprocessor output unchanged.  Consider an example:
2356
 
2357
     #define foo (4 + foo)
2358
 
2359
where `foo' is also a variable in your program.
2360
 
2361
   Following the ordinary rules, each reference to `foo' will expand
2362
into `(4 + foo)'; then this will be rescanned and will expand into `(4
2363
+ (4 + foo))'; and so on until the computer runs out of memory.
2364
 
2365
   The self-reference rule cuts this process short after one step, at
2366
`(4 + foo)'.  Therefore, this macro definition has the possibly useful
2367
effect of causing the program to add 4 to the value of `foo' wherever
2368
`foo' is referred to.
2369
 
2370
   In most cases, it is a bad idea to take advantage of this feature.  A
2371
person reading the program who sees that `foo' is a variable will not
2372
expect that it is a macro as well.  The reader will come across the
2373
identifier `foo' in the program and think its value should be that of
2374
the variable `foo', whereas in fact the value is four greater.
2375
 
2376
   One common, useful use of self-reference is to create a macro which
2377
expands to itself.  If you write
2378
 
2379
     #define EPERM EPERM
2380
 
2381
then the macro `EPERM' expands to `EPERM'.  Effectively, it is left
2382
alone by the preprocessor whenever it's used in running text.  You can
2383
tell that it's a macro with `#ifdef'.  You might do this if you want to
2384
define numeric constants with an `enum', but have `#ifdef' be true for
2385
each constant.
2386
 
2387
   If a macro `x' expands to use a macro `y', and the expansion of `y'
2388
refers to the macro `x', that is an "indirect self-reference" of `x'.
2389
`x' is not expanded in this case either.  Thus, if we have
2390
 
2391
     #define x (4 + y)
2392
     #define y (2 * x)
2393
 
2394
then `x' and `y' expand as follows:
2395
 
2396
     x    ==> (4 + y)
2397
          ==> (4 + (2 * x))
2398
 
2399
     y    ==> (2 * x)
2400
          ==> (2 * (4 + y))
2401
 
2402
Each macro is expanded when it appears in the definition of the other
2403
macro, but not when it indirectly appears in its own definition.
2404
 
2405

2406
File: cpp.info,  Node: Argument Prescan,  Next: Newlines in Arguments,  Prev: Self-Referential Macros,  Up: Macro Pitfalls
2407
 
2408
3.10.6 Argument Prescan
2409
-----------------------
2410
 
2411
Macro arguments are completely macro-expanded before they are
2412
substituted into a macro body, unless they are stringified or pasted
2413
with other tokens.  After substitution, the entire macro body, including
2414
the substituted arguments, is scanned again for macros to be expanded.
2415
The result is that the arguments are scanned _twice_ to expand macro
2416
calls in them.
2417
 
2418
   Most of the time, this has no effect.  If the argument contained any
2419
macro calls, they are expanded during the first scan.  The result
2420
therefore contains no macro calls, so the second scan does not change
2421
it.  If the argument were substituted as given, with no prescan, the
2422
single remaining scan would find the same macro calls and produce the
2423
same results.
2424
 
2425
   You might expect the double scan to change the results when a
2426
self-referential macro is used in an argument of another macro (*note
2427
Self-Referential Macros::): the self-referential macro would be
2428
expanded once in the first scan, and a second time in the second scan.
2429
However, this is not what happens.  The self-references that do not
2430
expand in the first scan are marked so that they will not expand in the
2431
second scan either.
2432
 
2433
   You might wonder, "Why mention the prescan, if it makes no
2434
difference?  And why not skip it and make the preprocessor faster?"
2435
The answer is that the prescan does make a difference in three special
2436
cases:
2437
 
2438
   * Nested calls to a macro.
2439
 
2440
     We say that "nested" calls to a macro occur when a macro's argument
2441
     contains a call to that very macro.  For example, if `f' is a macro
2442
     that expects one argument, `f (f (1))' is a nested pair of calls to
2443
     `f'.  The desired expansion is made by expanding `f (1)' and
2444
     substituting that into the definition of `f'.  The prescan causes
2445
     the expected result to happen.  Without the prescan, `f (1)' itself
2446
     would be substituted as an argument, and the inner use of `f' would
2447
     appear during the main scan as an indirect self-reference and
2448
     would not be expanded.
2449
 
2450
   * Macros that call other macros that stringify or concatenate.
2451
 
2452
     If an argument is stringified or concatenated, the prescan does not
2453
     occur.  If you _want_ to expand a macro, then stringify or
2454
     concatenate its expansion, you can do that by causing one macro to
2455
     call another macro that does the stringification or concatenation.
2456
     For instance, if you have
2457
 
2458
          #define AFTERX(x) X_ ## x
2459
          #define XAFTERX(x) AFTERX(x)
2460
          #define TABLESIZE 1024
2461
          #define BUFSIZE TABLESIZE
2462
 
2463
     then `AFTERX(BUFSIZE)' expands to `X_BUFSIZE', and
2464
     `XAFTERX(BUFSIZE)' expands to `X_1024'.  (Not to `X_TABLESIZE'.
2465
     Prescan always does a complete expansion.)
2466
 
2467
   * Macros used in arguments, whose expansions contain unshielded
2468
     commas.
2469
 
2470
     This can cause a macro expanded on the second scan to be called
2471
     with the wrong number of arguments.  Here is an example:
2472
 
2473
          #define foo  a,b
2474
          #define bar(x) lose(x)
2475
          #define lose(x) (1 + (x))
2476
 
2477
     We would like `bar(foo)' to turn into `(1 + (foo))', which would
2478
     then turn into `(1 + (a,b))'.  Instead, `bar(foo)' expands into
2479
     `lose(a,b)', and you get an error because `lose' requires a single
2480
     argument.  In this case, the problem is easily solved by the same
2481
     parentheses that ought to be used to prevent misnesting of
2482
     arithmetic operations:
2483
 
2484
          #define foo (a,b)
2485
     or
2486
          #define bar(x) lose((x))
2487
 
2488
     The extra pair of parentheses prevents the comma in `foo''s
2489
     definition from being interpreted as an argument separator.
2490
 
2491
 
2492

2493
File: cpp.info,  Node: Newlines in Arguments,  Prev: Argument Prescan,  Up: Macro Pitfalls
2494
 
2495
3.10.7 Newlines in Arguments
2496
----------------------------
2497
 
2498
The invocation of a function-like macro can extend over many logical
2499
lines.  However, in the present implementation, the entire expansion
2500
comes out on one line.  Thus line numbers emitted by the compiler or
2501
debugger refer to the line the invocation started on, which might be
2502
different to the line containing the argument causing the problem.
2503
 
2504
   Here is an example illustrating this:
2505
 
2506
     #define ignore_second_arg(a,b,c) a; c
2507
 
2508
     ignore_second_arg (foo (),
2509
                        ignored (),
2510
                        syntax error);
2511
 
2512
The syntax error triggered by the tokens `syntax error' results in an
2513
error message citing line three--the line of ignore_second_arg-- even
2514
though the problematic code comes from line five.
2515
 
2516
   We consider this a bug, and intend to fix it in the near future.
2517
 
2518

2519
File: cpp.info,  Node: Conditionals,  Next: Diagnostics,  Prev: Macros,  Up: Top
2520
 
2521
4 Conditionals
2522
**************
2523
 
2524
A "conditional" is a directive that instructs the preprocessor to
2525
select whether or not to include a chunk of code in the final token
2526
stream passed to the compiler.  Preprocessor conditionals can test
2527
arithmetic expressions, or whether a name is defined as a macro, or both
2528
simultaneously using the special `defined' operator.
2529
 
2530
   A conditional in the C preprocessor resembles in some ways an `if'
2531
statement in C, but it is important to understand the difference between
2532
them.  The condition in an `if' statement is tested during the
2533
execution of your program.  Its purpose is to allow your program to
2534
behave differently from run to run, depending on the data it is
2535
operating on.  The condition in a preprocessing conditional directive is
2536
tested when your program is compiled.  Its purpose is to allow different
2537
code to be included in the program depending on the situation at the
2538
time of compilation.
2539
 
2540
   However, the distinction is becoming less clear.  Modern compilers
2541
often do test `if' statements when a program is compiled, if their
2542
conditions are known not to vary at run time, and eliminate code which
2543
can never be executed.  If you can count on your compiler to do this,
2544
you may find that your program is more readable if you use `if'
2545
statements with constant conditions (perhaps determined by macros).  Of
2546
course, you can only use this to exclude code, not type definitions or
2547
other preprocessing directives, and you can only do it if the code
2548
remains syntactically valid when it is not to be used.
2549
 
2550
   GCC version 3 eliminates this kind of never-executed code even when
2551
not optimizing.  Older versions did it only when optimizing.
2552
 
2553
* Menu:
2554
 
2555
* Conditional Uses::
2556
* Conditional Syntax::
2557
* Deleted Code::
2558
 
2559

2560
File: cpp.info,  Node: Conditional Uses,  Next: Conditional Syntax,  Up: Conditionals
2561
 
2562
4.1 Conditional Uses
2563
====================
2564
 
2565
There are three general reasons to use a conditional.
2566
 
2567
   * A program may need to use different code depending on the machine
2568
     or operating system it is to run on.  In some cases the code for
2569
     one operating system may be erroneous on another operating system;
2570
     for example, it might refer to data types or constants that do not
2571
     exist on the other system.  When this happens, it is not enough to
2572
     avoid executing the invalid code.  Its mere presence will cause
2573
     the compiler to reject the program.  With a preprocessing
2574
     conditional, the offending code can be effectively excised from
2575
     the program when it is not valid.
2576
 
2577
   * You may want to be able to compile the same source file into two
2578
     different programs.  One version might make frequent time-consuming
2579
     consistency checks on its intermediate data, or print the values of
2580
     those data for debugging, and the other not.
2581
 
2582
   * A conditional whose condition is always false is one way to
2583
     exclude code from the program but keep it as a sort of comment for
2584
     future reference.
2585
 
2586
   Simple programs that do not need system-specific logic or complex
2587
debugging hooks generally will not need to use preprocessing
2588
conditionals.
2589
 
2590

2591
File: cpp.info,  Node: Conditional Syntax,  Next: Deleted Code,  Prev: Conditional Uses,  Up: Conditionals
2592
 
2593
4.2 Conditional Syntax
2594
======================
2595
 
2596
A conditional in the C preprocessor begins with a "conditional
2597
directive": `#if', `#ifdef' or `#ifndef'.
2598
 
2599
* Menu:
2600
 
2601
* Ifdef::
2602
* If::
2603
* Defined::
2604
* Else::
2605
* Elif::
2606
 
2607

2608
File: cpp.info,  Node: Ifdef,  Next: If,  Up: Conditional Syntax
2609
 
2610
4.2.1 Ifdef
2611
-----------
2612
 
2613
The simplest sort of conditional is
2614
 
2615
     #ifdef MACRO
2616
 
2617
     CONTROLLED TEXT
2618
 
2619
     #endif /* MACRO */
2620
 
2621
   This block is called a "conditional group".  CONTROLLED TEXT will be
2622
included in the output of the preprocessor if and only if MACRO is
2623
defined.  We say that the conditional "succeeds" if MACRO is defined,
2624
"fails" if it is not.
2625
 
2626
   The CONTROLLED TEXT inside of a conditional can include
2627
preprocessing directives.  They are executed only if the conditional
2628
succeeds.  You can nest conditional groups inside other conditional
2629
groups, but they must be completely nested.  In other words, `#endif'
2630
always matches the nearest `#ifdef' (or `#ifndef', or `#if').  Also,
2631
you cannot start a conditional group in one file and end it in another.
2632
 
2633
   Even if a conditional fails, the CONTROLLED TEXT inside it is still
2634
run through initial transformations and tokenization.  Therefore, it
2635
must all be lexically valid C.  Normally the only way this matters is
2636
that all comments and string literals inside a failing conditional group
2637
must still be properly ended.
2638
 
2639
   The comment following the `#endif' is not required, but it is a good
2640
practice if there is a lot of CONTROLLED TEXT, because it helps people
2641
match the `#endif' to the corresponding `#ifdef'.  Older programs
2642
sometimes put MACRO directly after the `#endif' without enclosing it in
2643
a comment.  This is invalid code according to the C standard.  CPP
2644
accepts it with a warning.  It never affects which `#ifndef' the
2645
`#endif' matches.
2646
 
2647
   Sometimes you wish to use some code if a macro is _not_ defined.
2648
You can do this by writing `#ifndef' instead of `#ifdef'.  One common
2649
use of `#ifndef' is to include code only the first time a header file
2650
is included.  *Note Once-Only Headers::.
2651
 
2652
   Macro definitions can vary between compilations for several reasons.
2653
Here are some samples.
2654
 
2655
   * Some macros are predefined on each kind of machine (*note
2656
     System-specific Predefined Macros::).  This allows you to provide
2657
     code specially tuned for a particular machine.
2658
 
2659
   * System header files define more macros, associated with the
2660
     features they implement.  You can test these macros with
2661
     conditionals to avoid using a system feature on a machine where it
2662
     is not implemented.
2663
 
2664
   * Macros can be defined or undefined with the `-D' and `-U' command
2665
     line options when you compile the program.  You can arrange to
2666
     compile the same source file into two different programs by
2667
     choosing a macro name to specify which program you want, writing
2668
     conditionals to test whether or how this macro is defined, and
2669
     then controlling the state of the macro with command line options,
2670
     perhaps set in the Makefile.  *Note Invocation::.
2671
 
2672
   * Your program might have a special header file (often called
2673
     `config.h') that is adjusted when the program is compiled.  It can
2674
     define or not define macros depending on the features of the
2675
     system and the desired capabilities of the program.  The
2676
     adjustment can be automated by a tool such as `autoconf', or done
2677
     by hand.
2678
 
2679

2680
File: cpp.info,  Node: If,  Next: Defined,  Prev: Ifdef,  Up: Conditional Syntax
2681
 
2682
4.2.2 If
2683
--------
2684
 
2685
The `#if' directive allows you to test the value of an arithmetic
2686
expression, rather than the mere existence of one macro.  Its syntax is
2687
 
2688
     #if EXPRESSION
2689
 
2690
     CONTROLLED TEXT
2691
 
2692
     #endif /* EXPRESSION */
2693
 
2694
   EXPRESSION is a C expression of integer type, subject to stringent
2695
restrictions.  It may contain
2696
 
2697
   * Integer constants.
2698
 
2699
   * Character constants, which are interpreted as they would be in
2700
     normal code.
2701
 
2702
   * Arithmetic operators for addition, subtraction, multiplication,
2703
     division, bitwise operations, shifts, comparisons, and logical
2704
     operations (`&&' and `||').  The latter two obey the usual
2705
     short-circuiting rules of standard C.
2706
 
2707
   * Macros.  All macros in the expression are expanded before actual
2708
     computation of the expression's value begins.
2709
 
2710
   * Uses of the `defined' operator, which lets you check whether macros
2711
     are defined in the middle of an `#if'.
2712
 
2713
   * Identifiers that are not macros, which are all considered to be the
2714
     number zero.  This allows you to write `#if MACRO' instead of
2715
     `#ifdef MACRO', if you know that MACRO, when defined, will always
2716
     have a nonzero value.  Function-like macros used without their
2717
     function call parentheses are also treated as zero.
2718
 
2719
     In some contexts this shortcut is undesirable.  The `-Wundef'
2720
     option causes GCC to warn whenever it encounters an identifier
2721
     which is not a macro in an `#if'.
2722
 
2723
   The preprocessor does not know anything about types in the language.
2724
Therefore, `sizeof' operators are not recognized in `#if', and neither
2725
are `enum' constants.  They will be taken as identifiers which are not
2726
macros, and replaced by zero.  In the case of `sizeof', this is likely
2727
to cause the expression to be invalid.
2728
 
2729
   The preprocessor calculates the value of EXPRESSION.  It carries out
2730
all calculations in the widest integer type known to the compiler; on
2731
most machines supported by GCC this is 64 bits.  This is not the same
2732
rule as the compiler uses to calculate the value of a constant
2733
expression, and may give different results in some cases.  If the value
2734
comes out to be nonzero, the `#if' succeeds and the CONTROLLED TEXT is
2735
included; otherwise it is skipped.
2736
 
2737

2738
File: cpp.info,  Node: Defined,  Next: Else,  Prev: If,  Up: Conditional Syntax
2739
 
2740
4.2.3 Defined
2741
-------------
2742
 
2743
The special operator `defined' is used in `#if' and `#elif' expressions
2744
to test whether a certain name is defined as a macro.  `defined NAME'
2745
and `defined (NAME)' are both expressions whose value is 1 if NAME is
2746
defined as a macro at the current point in the program, and 0
2747
otherwise.  Thus,  `#if defined MACRO' is precisely equivalent to
2748
`#ifdef MACRO'.
2749
 
2750
   `defined' is useful when you wish to test more than one macro for
2751
existence at once.  For example,
2752
 
2753
     #if defined (__vax__) || defined (__ns16000__)
2754
 
2755
would succeed if either of the names `__vax__' or `__ns16000__' is
2756
defined as a macro.
2757
 
2758
   Conditionals written like this:
2759
 
2760
     #if defined BUFSIZE && BUFSIZE >= 1024
2761
 
2762
can generally be simplified to just `#if BUFSIZE >= 1024', since if
2763
`BUFSIZE' is not defined, it will be interpreted as having the value
2764
zero.
2765
 
2766
   If the `defined' operator appears as a result of a macro expansion,
2767
the C standard says the behavior is undefined.  GNU cpp treats it as a
2768
genuine `defined' operator and evaluates it normally.  It will warn
2769
wherever your code uses this feature if you use the command-line option
2770
`-pedantic', since other compilers may handle it differently.
2771
 
2772

2773
File: cpp.info,  Node: Else,  Next: Elif,  Prev: Defined,  Up: Conditional Syntax
2774
 
2775
4.2.4 Else
2776
----------
2777
 
2778
The `#else' directive can be added to a conditional to provide
2779
alternative text to be used if the condition fails.  This is what it
2780
looks like:
2781
 
2782
     #if EXPRESSION
2783
     TEXT-IF-TRUE
2784
     #else /* Not EXPRESSION */
2785
     TEXT-IF-FALSE
2786
     #endif /* Not EXPRESSION */
2787
 
2788
If EXPRESSION is nonzero, the TEXT-IF-TRUE is included and the
2789
TEXT-IF-FALSE is skipped.  If EXPRESSION is zero, the opposite happens.
2790
 
2791
   You can use `#else' with `#ifdef' and `#ifndef', too.
2792
 
2793

2794
File: cpp.info,  Node: Elif,  Prev: Else,  Up: Conditional Syntax
2795
 
2796
4.2.5 Elif
2797
----------
2798
 
2799
One common case of nested conditionals is used to check for more than
2800
two possible alternatives.  For example, you might have
2801
 
2802
     #if X == 1
2803
     ...
2804
     #else /* X != 1 */
2805
     #if X == 2
2806
     ...
2807
     #else /* X != 2 */
2808
     ...
2809
     #endif /* X != 2 */
2810
     #endif /* X != 1 */
2811
 
2812
   Another conditional directive, `#elif', allows this to be
2813
abbreviated as follows:
2814
 
2815
     #if X == 1
2816
     ...
2817
     #elif X == 2
2818
     ...
2819
     #else /* X != 2 and X != 1*/
2820
     ...
2821
     #endif /* X != 2 and X != 1*/
2822
 
2823
   `#elif' stands for "else if".  Like `#else', it goes in the middle
2824
of a conditional group and subdivides it; it does not require a
2825
matching `#endif' of its own.  Like `#if', the `#elif' directive
2826
includes an expression to be tested.  The text following the `#elif' is
2827
processed only if the original `#if'-condition failed and the `#elif'
2828
condition succeeds.
2829
 
2830
   More than one `#elif' can go in the same conditional group.  Then
2831
the text after each `#elif' is processed only if the `#elif' condition
2832
succeeds after the original `#if' and all previous `#elif' directives
2833
within it have failed.
2834
 
2835
   `#else' is allowed after any number of `#elif' directives, but
2836
`#elif' may not follow `#else'.
2837
 
2838

2839
File: cpp.info,  Node: Deleted Code,  Prev: Conditional Syntax,  Up: Conditionals
2840
 
2841
4.3 Deleted Code
2842
================
2843
 
2844
If you replace or delete a part of the program but want to keep the old
2845
code around for future reference, you often cannot simply comment it
2846
out.  Block comments do not nest, so the first comment inside the old
2847
code will end the commenting-out.  The probable result is a flood of
2848
syntax errors.
2849
 
2850
   One way to avoid this problem is to use an always-false conditional
2851
instead.  For instance, put `#if 0' before the deleted code and
2852
`#endif' after it.  This works even if the code being turned off
2853
contains conditionals, but they must be entire conditionals (balanced
2854
`#if' and `#endif').
2855
 
2856
   Some people use `#ifdef notdef' instead.  This is risky, because
2857
`notdef' might be accidentally defined as a macro, and then the
2858
conditional would succeed.  `#if 0' can be counted on to fail.
2859
 
2860
   Do not use `#if 0' for comments which are not C code.  Use a real
2861
comment, instead.  The interior of `#if 0' must consist of complete
2862
tokens; in particular, single-quote characters must balance.  Comments
2863
often contain unbalanced single-quote characters (known in English as
2864
apostrophes).  These confuse `#if 0'.  They don't confuse `/*'.
2865
 
2866

2867
File: cpp.info,  Node: Diagnostics,  Next: Line Control,  Prev: Conditionals,  Up: Top
2868
 
2869
5 Diagnostics
2870
*************
2871
 
2872
The directive `#error' causes the preprocessor to report a fatal error.
2873
The tokens forming the rest of the line following `#error' are used as
2874
the error message.
2875
 
2876
   You would use `#error' inside of a conditional that detects a
2877
combination of parameters which you know the program does not properly
2878
support.  For example, if you know that the program will not run
2879
properly on a VAX, you might write
2880
 
2881
     #ifdef __vax__
2882
     #error "Won't work on VAXen.  See comments at get_last_object."
2883
     #endif
2884
 
2885
   If you have several configuration parameters that must be set up by
2886
the installation in a consistent way, you can use conditionals to detect
2887
an inconsistency and report it with `#error'.  For example,
2888
 
2889
     #if !defined(UNALIGNED_INT_ASM_OP) && defined(DWARF2_DEBUGGING_INFO)
2890
     #error "DWARF2_DEBUGGING_INFO requires UNALIGNED_INT_ASM_OP."
2891
     #endif
2892
 
2893
   The directive `#warning' is like `#error', but causes the
2894
preprocessor to issue a warning and continue preprocessing.  The tokens
2895
following `#warning' are used as the warning message.
2896
 
2897
   You might use `#warning' in obsolete header files, with a message
2898
directing the user to the header file which should be used instead.
2899
 
2900
   Neither `#error' nor `#warning' macro-expands its argument.
2901
Internal whitespace sequences are each replaced with a single space.
2902
The line must consist of complete tokens.  It is wisest to make the
2903
argument of these directives be a single string constant; this avoids
2904
problems with apostrophes and the like.
2905
 
2906

2907
File: cpp.info,  Node: Line Control,  Next: Pragmas,  Prev: Diagnostics,  Up: Top
2908
 
2909
6 Line Control
2910
**************
2911
 
2912
The C preprocessor informs the C compiler of the location in your source
2913
code where each token came from.  Presently, this is just the file name
2914
and line number.  All the tokens resulting from macro expansion are
2915
reported as having appeared on the line of the source file where the
2916
outermost macro was used.  We intend to be more accurate in the future.
2917
 
2918
   If you write a program which generates source code, such as the
2919
`bison' parser generator, you may want to adjust the preprocessor's
2920
notion of the current file name and line number by hand.  Parts of the
2921
output from `bison' are generated from scratch, other parts come from a
2922
standard parser file.  The rest are copied verbatim from `bison''s
2923
input.  You would like compiler error messages and symbolic debuggers
2924
to be able to refer to `bison''s input file.
2925
 
2926
   `bison' or any such program can arrange this by writing `#line'
2927
directives into the output file.  `#line' is a directive that specifies
2928
the original line number and source file name for subsequent input in
2929
the current preprocessor input file.  `#line' has three variants:
2930
 
2931
`#line LINENUM'
2932
     LINENUM is a non-negative decimal integer constant.  It specifies
2933
     the line number which should be reported for the following line of
2934
     input.  Subsequent lines are counted from LINENUM.
2935
 
2936
`#line LINENUM FILENAME'
2937
     LINENUM is the same as for the first form, and has the same
2938
     effect.  In addition, FILENAME is a string constant.  The
2939
     following line and all subsequent lines are reported to come from
2940
     the file it specifies, until something else happens to change that.
2941
     FILENAME is interpreted according to the normal rules for a string
2942
     constant: backslash escapes are interpreted.  This is different
2943
     from `#include'.
2944
 
2945
     Previous versions of CPP did not interpret escapes in `#line'; we
2946
     have changed it because the standard requires they be interpreted,
2947
     and most other compilers do.
2948
 
2949
`#line ANYTHING ELSE'
2950
     ANYTHING ELSE is checked for macro calls, which are expanded.  The
2951
     result should match one of the above two forms.
2952
 
2953
   `#line' directives alter the results of the `__FILE__' and
2954
`__LINE__' predefined macros from that point on.  *Note Standard
2955
Predefined Macros::.  They do not have any effect on `#include''s idea
2956
of the directory containing the current file.  This is a change from
2957
GCC 2.95.  Previously, a file reading
2958
 
2959
     #line 1 "../src/gram.y"
2960
     #include "gram.h"
2961
 
2962
   would search for `gram.h' in `../src', then the `-I' chain; the
2963
directory containing the physical source file would not be searched.
2964
In GCC 3.0 and later, the `#include' is not affected by the presence of
2965
a `#line' referring to a different directory.
2966
 
2967
   We made this change because the old behavior caused problems when
2968
generated source files were transported between machines.  For instance,
2969
it is common practice to ship generated parsers with a source release,
2970
so that people building the distribution do not need to have yacc or
2971
Bison installed.  These files frequently have `#line' directives
2972
referring to the directory tree of the system where the distribution was
2973
created.  If GCC tries to search for headers in those directories, the
2974
build is likely to fail.
2975
 
2976
   The new behavior can cause failures too, if the generated file is not
2977
in the same directory as its source and it attempts to include a header
2978
which would be visible searching from the directory containing the
2979
source file.  However, this problem is easily solved with an additional
2980
`-I' switch on the command line.  The failures caused by the old
2981
semantics could sometimes be corrected only by editing the generated
2982
files, which is difficult and error-prone.
2983
 
2984

2985
File: cpp.info,  Node: Pragmas,  Next: Other Directives,  Prev: Line Control,  Up: Top
2986
 
2987
7 Pragmas
2988
*********
2989
 
2990
The `#pragma' directive is the method specified by the C standard for
2991
providing additional information to the compiler, beyond what is
2992
conveyed in the language itself.  Three forms of this directive
2993
(commonly known as "pragmas") are specified by the 1999 C standard.  A
2994
C compiler is free to attach any meaning it likes to other pragmas.
2995
 
2996
   GCC has historically preferred to use extensions to the syntax of the
2997
language, such as `__attribute__', for this purpose.  However, GCC does
2998
define a few pragmas of its own.  These mostly have effects on the
2999
entire translation unit or source file.
3000
 
3001
   In GCC version 3, all GNU-defined, supported pragmas have been given
3002
a `GCC' prefix.  This is in line with the `STDC' prefix on all pragmas
3003
defined by C99.  For backward compatibility, pragmas which were
3004
recognized by previous versions are still recognized without the `GCC'
3005
prefix, but that usage is deprecated.  Some older pragmas are
3006
deprecated in their entirety.  They are not recognized with the `GCC'
3007
prefix.  *Note Obsolete Features::.
3008
 
3009
   C99 introduces the `_Pragma' operator.  This feature addresses a
3010
major problem with `#pragma': being a directive, it cannot be produced
3011
as the result of macro expansion.  `_Pragma' is an operator, much like
3012
`sizeof' or `defined', and can be embedded in a macro.
3013
 
3014
   Its syntax is `_Pragma (STRING-LITERAL)', where STRING-LITERAL can
3015
be either a normal or wide-character string literal.  It is
3016
destringized, by replacing all `\\' with a single `\' and all `\"' with
3017
a `"'.  The result is then processed as if it had appeared as the right
3018
hand side of a `#pragma' directive.  For example,
3019
 
3020
     _Pragma ("GCC dependency \"parse.y\"")
3021
 
3022
has the same effect as `#pragma GCC dependency "parse.y"'.  The same
3023
effect could be achieved using macros, for example
3024
 
3025
     #define DO_PRAGMA(x) _Pragma (#x)
3026
     DO_PRAGMA (GCC dependency "parse.y")
3027
 
3028
   The standard is unclear on where a `_Pragma' operator can appear.
3029
The preprocessor does not accept it within a preprocessing conditional
3030
directive like `#if'.  To be safe, you are probably best keeping it out
3031
of directives other than `#define', and putting it on a line of its own.
3032
 
3033
   This manual documents the pragmas which are meaningful to the
3034
preprocessor itself.  Other pragmas are meaningful to the C or C++
3035
compilers.  They are documented in the GCC manual.
3036
 
3037
`#pragma GCC dependency'
3038
     `#pragma GCC dependency' allows you to check the relative dates of
3039
     the current file and another file.  If the other file is more
3040
     recent than the current file, a warning is issued.  This is useful
3041
     if the current file is derived from the other file, and should be
3042
     regenerated.  The other file is searched for using the normal
3043
     include search path.  Optional trailing text can be used to give
3044
     more information in the warning message.
3045
 
3046
          #pragma GCC dependency "parse.y"
3047
          #pragma GCC dependency "/usr/include/time.h" rerun fixincludes
3048
 
3049
`#pragma GCC poison'
3050
     Sometimes, there is an identifier that you want to remove
3051
     completely from your program, and make sure that it never creeps
3052
     back in.  To enforce this, you can "poison" the identifier with
3053
     this pragma.  `#pragma GCC poison' is followed by a list of
3054
     identifiers to poison.  If any of those identifiers appears
3055
     anywhere in the source after the directive, it is a hard error.
3056
     For example,
3057
 
3058
          #pragma GCC poison printf sprintf fprintf
3059
          sprintf(some_string, "hello");
3060
 
3061
     will produce an error.
3062
 
3063
     If a poisoned identifier appears as part of the expansion of a
3064
     macro which was defined before the identifier was poisoned, it
3065
     will _not_ cause an error.  This lets you poison an identifier
3066
     without worrying about system headers defining macros that use it.
3067
 
3068
     For example,
3069
 
3070
          #define strrchr rindex
3071
          #pragma GCC poison rindex
3072
          strrchr(some_string, 'h');
3073
 
3074
     will not produce an error.
3075
 
3076
`#pragma GCC system_header'
3077
     This pragma takes no arguments.  It causes the rest of the code in
3078
     the current file to be treated as if it came from a system header.
3079
     *Note System Headers::.
3080
 
3081
 
3082

3083
File: cpp.info,  Node: Other Directives,  Next: Preprocessor Output,  Prev: Pragmas,  Up: Top
3084
 
3085
8 Other Directives
3086
******************
3087
 
3088
The `#ident' directive takes one argument, a string constant.  On some
3089
systems, that string constant is copied into a special segment of the
3090
object file.  On other systems, the directive is ignored.  The `#sccs'
3091
directive is a synonym for `#ident'.
3092
 
3093
   These directives are not part of the C standard, but they are not
3094
official GNU extensions either.  What historical information we have
3095
been able to find, suggests they originated with System V.
3096
 
3097
   The "null directive" consists of a `#' followed by a newline, with
3098
only whitespace (including comments) in between.  A null directive is
3099
understood as a preprocessing directive but has no effect on the
3100
preprocessor output.  The primary significance of the existence of the
3101
null directive is that an input line consisting of just a `#' will
3102
produce no output, rather than a line of output containing just a `#'.
3103
Supposedly some old C programs contain such lines.
3104
 
3105

3106
File: cpp.info,  Node: Preprocessor Output,  Next: Traditional Mode,  Prev: Other Directives,  Up: Top
3107
 
3108
9 Preprocessor Output
3109
*********************
3110
 
3111
When the C preprocessor is used with the C, C++, or Objective-C
3112
compilers, it is integrated into the compiler and communicates a stream
3113
of binary tokens directly to the compiler's parser.  However, it can
3114
also be used in the more conventional standalone mode, where it produces
3115
textual output.
3116
 
3117
   The output from the C preprocessor looks much like the input, except
3118
that all preprocessing directive lines have been replaced with blank
3119
lines and all comments with spaces.  Long runs of blank lines are
3120
discarded.
3121
 
3122
   The ISO standard specifies that it is implementation defined whether
3123
a preprocessor preserves whitespace between tokens, or replaces it with
3124
e.g. a single space.  In GNU CPP, whitespace between tokens is collapsed
3125
to become a single space, with the exception that the first token on a
3126
non-directive line is preceded with sufficient spaces that it appears in
3127
the same column in the preprocessed output that it appeared in the
3128
original source file.  This is so the output is easy to read.  *Note
3129
Differences from previous versions::.  CPP does not insert any
3130
whitespace where there was none in the original source, except where
3131
necessary to prevent an accidental token paste.
3132
 
3133
   Source file name and line number information is conveyed by lines of
3134
the form
3135
 
3136
     # LINENUM FILENAME FLAGS
3137
 
3138
These are called "linemarkers".  They are inserted as needed into the
3139
output (but never within a string or character constant).  They mean
3140
that the following line originated in file FILENAME at line LINENUM.
3141
FILENAME will never contain any non-printing characters; they are
3142
replaced with octal escape sequences.
3143
 
3144
   After the file name comes zero or more flags, which are `1', `2',
3145
`3', or `4'.  If there are multiple flags, spaces separate them.  Here
3146
is what the flags mean:
3147
 
3148
`1'
3149
     This indicates the start of a new file.
3150
 
3151
`2'
3152
     This indicates returning to a file (after having included another
3153
     file).
3154
 
3155
`3'
3156
     This indicates that the following text comes from a system header
3157
     file, so certain warnings should be suppressed.
3158
 
3159
`4'
3160
     This indicates that the following text should be treated as being
3161
     wrapped in an implicit `extern "C"' block.
3162
 
3163
   As an extension, the preprocessor accepts linemarkers in
3164
non-assembler input files.  They are treated like the corresponding
3165
`#line' directive, (*note Line Control::), except that trailing flags
3166
are permitted, and are interpreted with the meanings described above.
3167
If multiple flags are given, they must be in ascending order.
3168
 
3169
   Some directives may be duplicated in the output of the preprocessor.
3170
These are `#ident' (always), `#pragma' (only if the preprocessor does
3171
not handle the pragma itself), and `#define' and `#undef' (with certain
3172
debugging options).  If this happens, the `#' of the directive will
3173
always be in the first column, and there will be no space between the
3174
`#' and the directive name.  If macro expansion happens to generate
3175
tokens which might be mistaken for a duplicated directive, a space will
3176
be inserted between the `#' and the directive name.
3177
 
3178

3179
File: cpp.info,  Node: Traditional Mode,  Next: Implementation Details,  Prev: Preprocessor Output,  Up: Top
3180
 
3181
10 Traditional Mode
3182
*******************
3183
 
3184
Traditional (pre-standard) C preprocessing is rather different from the
3185
preprocessing specified by the standard.  When GCC is given the
3186
`-traditional-cpp' option, it attempts to emulate a traditional
3187
preprocessor.
3188
 
3189
   GCC versions 3.2 and later only support traditional mode semantics in
3190
the preprocessor, and not in the compiler front ends.  This chapter
3191
outlines the traditional preprocessor semantics we implemented.
3192
 
3193
   The implementation does not correspond precisely to the behavior of
3194
earlier versions of GCC, nor to any true traditional preprocessor.
3195
After all, inconsistencies among traditional implementations were a
3196
major motivation for C standardization.  However, we intend that it
3197
should be compatible with true traditional preprocessors in all ways
3198
that actually matter.
3199
 
3200
* Menu:
3201
 
3202
* Traditional lexical analysis::
3203
* Traditional macros::
3204
* Traditional miscellany::
3205
* Traditional warnings::
3206
 
3207

3208
File: cpp.info,  Node: Traditional lexical analysis,  Next: Traditional macros,  Up: Traditional Mode
3209
 
3210
10.1 Traditional lexical analysis
3211
=================================
3212
 
3213
The traditional preprocessor does not decompose its input into tokens
3214
the same way a standards-conforming preprocessor does.  The input is
3215
simply treated as a stream of text with minimal internal form.
3216
 
3217
   This implementation does not treat trigraphs (*note trigraphs::)
3218
specially since they were an invention of the standards committee.  It
3219
handles arbitrarily-positioned escaped newlines properly and splices
3220
the lines as you would expect; many traditional preprocessors did not
3221
do this.
3222
 
3223
   The form of horizontal whitespace in the input file is preserved in
3224
the output.  In particular, hard tabs remain hard tabs.  This can be
3225
useful if, for example, you are preprocessing a Makefile.
3226
 
3227
   Traditional CPP only recognizes C-style block comments, and treats
3228
the `/*' sequence as introducing a comment only if it lies outside
3229
quoted text.  Quoted text is introduced by the usual single and double
3230
quotes, and also by an initial `<' in a `#include' directive.
3231
 
3232
   Traditionally, comments are completely removed and are not replaced
3233
with a space.  Since a traditional compiler does its own tokenization
3234
of the output of the preprocessor, this means that comments can
3235
effectively be used as token paste operators.  However, comments behave
3236
like separators for text handled by the preprocessor itself, since it
3237
doesn't re-lex its input.  For example, in
3238
 
3239
     #if foo/**/bar
3240
 
3241
`foo' and `bar' are distinct identifiers and expanded separately if
3242
they happen to be macros.  In other words, this directive is equivalent
3243
to
3244
 
3245
     #if foo bar
3246
 
3247
rather than
3248
 
3249
     #if foobar
3250
 
3251
   Generally speaking, in traditional mode an opening quote need not
3252
have a matching closing quote.  In particular, a macro may be defined
3253
with replacement text that contains an unmatched quote.  Of course, if
3254
you attempt to compile preprocessed output containing an unmatched quote
3255
you will get a syntax error.
3256
 
3257
   However, all preprocessing directives other than `#define' require
3258
matching quotes.  For example:
3259
 
3260
     #define m This macro's fine and has an unmatched quote
3261
     "/* This is not a comment.  */
3262
     /* This is a comment.  The following #include directive
3263
        is ill-formed.  */
3264
     #include 
3265
 
3266
   Just as for the ISO preprocessor, what would be a closing quote can
3267
be escaped with a backslash to prevent the quoted text from closing.
3268
 
3269

3270
File: cpp.info,  Node: Traditional macros,  Next: Traditional miscellany,  Prev: Traditional lexical analysis,  Up: Traditional Mode
3271
 
3272
10.2 Traditional macros
3273
=======================
3274
 
3275
The major difference between traditional and ISO macros is that the
3276
former expand to text rather than to a token sequence.  CPP removes all
3277
leading and trailing horizontal whitespace from a macro's replacement
3278
text before storing it, but preserves the form of internal whitespace.
3279
 
3280
   One consequence is that it is legitimate for the replacement text to
3281
contain an unmatched quote (*note Traditional lexical analysis::).  An
3282
unclosed string or character constant continues into the text following
3283
the macro call.  Similarly, the text at the end of a macro's expansion
3284
can run together with the text after the macro invocation to produce a
3285
single token.
3286
 
3287
   Normally comments are removed from the replacement text after the
3288
macro is expanded, but if the `-CC' option is passed on the command
3289
line comments are preserved.  (In fact, the current implementation
3290
removes comments even before saving the macro replacement text, but it
3291
careful to do it in such a way that the observed effect is identical
3292
even in the function-like macro case.)
3293
 
3294
   The ISO stringification operator `#' and token paste operator `##'
3295
have no special meaning.  As explained later, an effect similar to
3296
these operators can be obtained in a different way.  Macro names that
3297
are embedded in quotes, either from the main file or after macro
3298
replacement, do not expand.
3299
 
3300
   CPP replaces an unquoted object-like macro name with its replacement
3301
text, and then rescans it for further macros to replace.  Unlike
3302
standard macro expansion, traditional macro expansion has no provision
3303
to prevent recursion.  If an object-like macro appears unquoted in its
3304
replacement text, it will be replaced again during the rescan pass, and
3305
so on _ad infinitum_.  GCC detects when it is expanding recursive
3306
macros, emits an error message, and continues after the offending macro
3307
invocation.
3308
 
3309
     #define PLUS +
3310
     #define INC(x) PLUS+x
3311
     INC(foo);
3312
          ==> ++foo;
3313
 
3314
   Function-like macros are similar in form but quite different in
3315
behavior to their ISO counterparts.  Their arguments are contained
3316
within parentheses, are comma-separated, and can cross physical lines.
3317
Commas within nested parentheses are not treated as argument
3318
separators.  Similarly, a quote in an argument cannot be left unclosed;
3319
a following comma or parenthesis that comes before the closing quote is
3320
treated like any other character.  There is no facility for handling
3321
variadic macros.
3322
 
3323
   This implementation removes all comments from macro arguments, unless
3324
the `-C' option is given.  The form of all other horizontal whitespace
3325
in arguments is preserved, including leading and trailing whitespace.
3326
In particular
3327
 
3328
     f( )
3329
 
3330
is treated as an invocation of the macro `f' with a single argument
3331
consisting of a single space.  If you want to invoke a function-like
3332
macro that takes no arguments, you must not leave any whitespace
3333
between the parentheses.
3334
 
3335
   If a macro argument crosses a new line, the new line is replaced with
3336
a space when forming the argument.  If the previous line contained an
3337
unterminated quote, the following line inherits the quoted state.
3338
 
3339
   Traditional preprocessors replace parameters in the replacement text
3340
with their arguments regardless of whether the parameters are within
3341
quotes or not.  This provides a way to stringize arguments.  For example
3342
 
3343
     #define str(x) "x"
3344
     str(/* A comment */some text )
3345
          ==> "some text "
3346
 
3347
Note that the comment is removed, but that the trailing space is
3348
preserved.  Here is an example of using a comment to effect token
3349
pasting.
3350
 
3351
     #define suffix(x) foo_/**/x
3352
     suffix(bar)
3353
          ==> foo_bar
3354
 
3355

3356
File: cpp.info,  Node: Traditional miscellany,  Next: Traditional warnings,  Prev: Traditional macros,  Up: Traditional Mode
3357
 
3358
10.3 Traditional miscellany
3359
===========================
3360
 
3361
Here are some things to be aware of when using the traditional
3362
preprocessor.
3363
 
3364
   * Preprocessing directives are recognized only when their leading
3365
     `#' appears in the first column.  There can be no whitespace
3366
     between the beginning of the line and the `#', but whitespace can
3367
     follow the `#'.
3368
 
3369
   * A true traditional C preprocessor does not recognize `#error' or
3370
     `#pragma', and may not recognize `#elif'.  CPP supports all the
3371
     directives in traditional mode that it supports in ISO mode,
3372
     including extensions, with the exception that the effects of
3373
     `#pragma GCC poison' are undefined.
3374
 
3375
   * __STDC__ is not defined.
3376
 
3377
   * If you use digraphs the behavior is undefined.
3378
 
3379
   * If a line that looks like a directive appears within macro
3380
     arguments, the behavior is undefined.
3381
 
3382
 
3383

3384
File: cpp.info,  Node: Traditional warnings,  Prev: Traditional miscellany,  Up: Traditional Mode
3385
 
3386
10.4 Traditional warnings
3387
=========================
3388
 
3389
You can request warnings about features that did not exist, or worked
3390
differently, in traditional C with the `-Wtraditional' option.  GCC
3391
does not warn about features of ISO C which you must use when you are
3392
using a conforming compiler, such as the `#' and `##' operators.
3393
 
3394
   Presently `-Wtraditional' warns about:
3395
 
3396
   * Macro parameters that appear within string literals in the macro
3397
     body.  In traditional C macro replacement takes place within
3398
     string literals, but does not in ISO C.
3399
 
3400
   * In traditional C, some preprocessor directives did not exist.
3401
     Traditional preprocessors would only consider a line to be a
3402
     directive if the `#' appeared in column 1 on the line.  Therefore
3403
     `-Wtraditional' warns about directives that traditional C
3404
     understands but would ignore because the `#' does not appear as the
3405
     first character on the line.  It also suggests you hide directives
3406
     like `#pragma' not understood by traditional C by indenting them.
3407
     Some traditional implementations would not recognize `#elif', so it
3408
     suggests avoiding it altogether.
3409
 
3410
   * A function-like macro that appears without an argument list.  In
3411
     some traditional preprocessors this was an error.  In ISO C it
3412
     merely means that the macro is not expanded.
3413
 
3414
   * The unary plus operator.  This did not exist in traditional C.
3415
 
3416
   * The `U' and `LL' integer constant suffixes, which were not
3417
     available in traditional C.  (Traditional C does support the `L'
3418
     suffix for simple long integer constants.)  You are not warned
3419
     about uses of these suffixes in macros defined in system headers.
3420
     For instance, `UINT_MAX' may well be defined as `4294967295U', but
3421
     you will not be warned if you use `UINT_MAX'.
3422
 
3423
     You can usually avoid the warning, and the related warning about
3424
     constants which are so large that they are unsigned, by writing the
3425
     integer constant in question in hexadecimal, with no U suffix.
3426
     Take care, though, because this gives the wrong result in exotic
3427
     cases.
3428
 
3429

3430
File: cpp.info,  Node: Implementation Details,  Next: Invocation,  Prev: Traditional Mode,  Up: Top
3431
 
3432
11 Implementation Details
3433
*************************
3434
 
3435
Here we document details of how the preprocessor's implementation
3436
affects its user-visible behavior.  You should try to avoid undue
3437
reliance on behavior described here, as it is possible that it will
3438
change subtly in future implementations.
3439
 
3440
   Also documented here are obsolete features and changes from previous
3441
versions of CPP.
3442
 
3443
* Menu:
3444
 
3445
* Implementation-defined behavior::
3446
* Implementation limits::
3447
* Obsolete Features::
3448
* Differences from previous versions::
3449
 
3450

3451
File: cpp.info,  Node: Implementation-defined behavior,  Next: Implementation limits,  Up: Implementation Details
3452
 
3453
11.1 Implementation-defined behavior
3454
====================================
3455
 
3456
This is how CPP behaves in all the cases which the C standard describes
3457
as "implementation-defined".  This term means that the implementation
3458
is free to do what it likes, but must document its choice and stick to
3459
it.
3460
 
3461
   * The mapping of physical source file multi-byte characters to the
3462
     execution character set.
3463
 
3464
     Currently, CPP requires its input to be ASCII or UTF-8.  The
3465
     execution character set may be controlled by the user, with the
3466
     `-fexec-charset' and `-fwide-exec-charset' options.
3467
 
3468
   * Identifier characters.
3469
 
3470
     The C and C++ standards allow identifiers to be composed of `_'
3471
     and the alphanumeric characters.  C++ and C99 also allow universal
3472
     character names, and C99 further permits implementation-defined
3473
     characters.  GCC currently only permits universal character names
3474
     if `-fextended-identifiers' is used, because the implementation of
3475
     universal character names in identifiers is experimental.
3476
 
3477
     GCC allows the `$' character in identifiers as an extension for
3478
     most targets.  This is true regardless of the `std=' switch, since
3479
     this extension cannot conflict with standards-conforming programs.
3480
     When preprocessing assembler, however, dollars are not identifier
3481
     characters by default.
3482
 
3483
     Currently the targets that by default do not permit `$' are AVR,
3484
     IP2K, MMIX, MIPS Irix 3, ARM aout, and PowerPC targets for the AIX
3485
     and BeOS operating systems.
3486
 
3487
     You can override the default with `-fdollars-in-identifiers' or
3488
     `fno-dollars-in-identifiers'.  *Note fdollars-in-identifiers::.
3489
 
3490
   * Non-empty sequences of whitespace characters.
3491
 
3492
     In textual output, each whitespace sequence is collapsed to a
3493
     single space.  For aesthetic reasons, the first token on each
3494
     non-directive line of output is preceded with sufficient spaces
3495
     that it appears in the same column as it did in the original
3496
     source file.
3497
 
3498
   * The numeric value of character constants in preprocessor
3499
     expressions.
3500
 
3501
     The preprocessor and compiler interpret character constants in the
3502
     same way; i.e. escape sequences such as `\a' are given the values
3503
     they would have on the target machine.
3504
 
3505
     The compiler values a multi-character character constant a
3506
     character at a time, shifting the previous value left by the
3507
     number of bits per target character, and then or-ing in the
3508
     bit-pattern of the new character truncated to the width of a
3509
     target character.  The final bit-pattern is given type `int', and
3510
     is therefore signed, regardless of whether single characters are
3511
     signed or not (a slight change from versions 3.1 and earlier of
3512
     GCC).  If there are more characters in the constant than would fit
3513
     in the target `int' the compiler issues a warning, and the excess
3514
     leading characters are ignored.
3515
 
3516
     For example, `'ab'' for a target with an 8-bit `char' would be
3517
     interpreted as
3518
     `(int) ((unsigned char) 'a' * 256 + (unsigned char) 'b')', and
3519
     `'\234a'' as
3520
     `(int) ((unsigned char) '\234' * 256 + (unsigned char) 'a')'.
3521
 
3522
   * Source file inclusion.
3523
 
3524
     For a discussion on how the preprocessor locates header files,
3525
     *Note Include Operation::.
3526
 
3527
   * Interpretation of the filename resulting from a macro-expanded
3528
     `#include' directive.
3529
 
3530
     *Note Computed Includes::.
3531
 
3532
   * Treatment of a `#pragma' directive that after macro-expansion
3533
     results in a standard pragma.
3534
 
3535
     No macro expansion occurs on any `#pragma' directive line, so the
3536
     question does not arise.
3537
 
3538
     Note that GCC does not yet implement any of the standard pragmas.
3539
 
3540
 
3541

3542
File: cpp.info,  Node: Implementation limits,  Next: Obsolete Features,  Prev: Implementation-defined behavior,  Up: Implementation Details
3543
 
3544
11.2 Implementation limits
3545
==========================
3546
 
3547
CPP has a small number of internal limits.  This section lists the
3548
limits which the C standard requires to be no lower than some minimum,
3549
and all the others known.  It is intended that there should be as few
3550
limits as possible.  If you encounter an undocumented or inconvenient
3551
limit, please report that as a bug.  *Note Reporting Bugs: (gcc)Bugs.
3552
 
3553
   Where we say something is limited "only by available memory", that
3554
means that internal data structures impose no intrinsic limit, and space
3555
is allocated with `malloc' or equivalent.  The actual limit will
3556
therefore depend on many things, such as the size of other things
3557
allocated by the compiler at the same time, the amount of memory
3558
consumed by other processes on the same computer, etc.
3559
 
3560
   * Nesting levels of `#include' files.
3561
 
3562
     We impose an arbitrary limit of 200 levels, to avoid runaway
3563
     recursion.  The standard requires at least 15 levels.
3564
 
3565
   * Nesting levels of conditional inclusion.
3566
 
3567
     The C standard mandates this be at least 63.  CPP is limited only
3568
     by available memory.
3569
 
3570
   * Levels of parenthesized expressions within a full expression.
3571
 
3572
     The C standard requires this to be at least 63.  In preprocessor
3573
     conditional expressions, it is limited only by available memory.
3574
 
3575
   * Significant initial characters in an identifier or macro name.
3576
 
3577
     The preprocessor treats all characters as significant.  The C
3578
     standard requires only that the first 63 be significant.
3579
 
3580
   * Number of macros simultaneously defined in a single translation
3581
     unit.
3582
 
3583
     The standard requires at least 4095 be possible.  CPP is limited
3584
     only by available memory.
3585
 
3586
   * Number of parameters in a macro definition and arguments in a
3587
     macro call.
3588
 
3589
     We allow `USHRT_MAX', which is no smaller than 65,535.  The minimum
3590
     required by the standard is 127.
3591
 
3592
   * Number of characters on a logical source line.
3593
 
3594
     The C standard requires a minimum of 4096 be permitted.  CPP places
3595
     no limits on this, but you may get incorrect column numbers
3596
     reported in diagnostics for lines longer than 65,535 characters.
3597
 
3598
   * Maximum size of a source file.
3599
 
3600
     The standard does not specify any lower limit on the maximum size
3601
     of a source file.  GNU cpp maps files into memory, so it is
3602
     limited by the available address space.  This is generally at
3603
     least two gigabytes.  Depending on the operating system, the size
3604
     of physical memory may or may not be a limitation.
3605
 
3606
 
3607

3608
File: cpp.info,  Node: Obsolete Features,  Next: Differences from previous versions,  Prev: Implementation limits,  Up: Implementation Details
3609
 
3610
11.3 Obsolete Features
3611
======================
3612
 
3613
CPP has a number of features which are present mainly for compatibility
3614
with older programs.  We discourage their use in new code.  In some
3615
cases, we plan to remove the feature in a future version of GCC.
3616
 
3617
* Menu:
3618
 
3619
* Assertions::
3620
* Obsolete once-only headers::
3621
 
3622

3623
File: cpp.info,  Node: Assertions,  Next: Obsolete once-only headers,  Up: Obsolete Features
3624
 
3625
11.3.1 Assertions
3626
-----------------
3627
 
3628
"Assertions" are a deprecated alternative to macros in writing
3629
conditionals to test what sort of computer or system the compiled
3630
program will run on.  Assertions are usually predefined, but you can
3631
define them with preprocessing directives or command-line options.
3632
 
3633
   Assertions were intended to provide a more systematic way to describe
3634
the compiler's target system.  However, in practice they are just as
3635
unpredictable as the system-specific predefined macros.  In addition,
3636
they are not part of any standard, and only a few compilers support
3637
them.  Therefore, the use of assertions is *less* portable than the use
3638
of system-specific predefined macros.  We recommend you do not use them
3639
at all.
3640
 
3641
   An assertion looks like this:
3642
 
3643
     #PREDICATE (ANSWER)
3644
 
3645
PREDICATE must be a single identifier.  ANSWER can be any sequence of
3646
tokens; all characters are significant except for leading and trailing
3647
whitespace, and differences in internal whitespace sequences are
3648
ignored.  (This is similar to the rules governing macro redefinition.)
3649
Thus, `(x + y)' is different from `(x+y)' but equivalent to
3650
`( x + y )'.  Parentheses do not nest inside an answer.
3651
 
3652
   To test an assertion, you write it in an `#if'.  For example, this
3653
conditional succeeds if either `vax' or `ns16000' has been asserted as
3654
an answer for `machine'.
3655
 
3656
     #if #machine (vax) || #machine (ns16000)
3657
 
3658
You can test whether _any_ answer is asserted for a predicate by
3659
omitting the answer in the conditional:
3660
 
3661
     #if #machine
3662
 
3663
   Assertions are made with the `#assert' directive.  Its sole argument
3664
is the assertion to make, without the leading `#' that identifies
3665
assertions in conditionals.
3666
 
3667
     #assert PREDICATE (ANSWER)
3668
 
3669
You may make several assertions with the same predicate and different
3670
answers.  Subsequent assertions do not override previous ones for the
3671
same predicate.  All the answers for any given predicate are
3672
simultaneously true.
3673
 
3674
   Assertions can be canceled with the `#unassert' directive.  It has
3675
the same syntax as `#assert'.  In that form it cancels only the answer
3676
which was specified on the `#unassert' line; other answers for that
3677
predicate remain true.  You can cancel an entire predicate by leaving
3678
out the answer:
3679
 
3680
     #unassert PREDICATE
3681
 
3682
In either form, if no such assertion has been made, `#unassert' has no
3683
effect.
3684
 
3685
   You can also make or cancel assertions using command line options.
3686
*Note Invocation::.
3687
 
3688

3689
File: cpp.info,  Node: Obsolete once-only headers,  Prev: Assertions,  Up: Obsolete Features
3690
 
3691
11.3.2 Obsolete once-only headers
3692
---------------------------------
3693
 
3694
CPP supports two more ways of indicating that a header file should be
3695
read only once.  Neither one is as portable as a wrapper `#ifndef', and
3696
we recommend you do not use them in new programs.
3697
 
3698
   In the Objective-C language, there is a variant of `#include' called
3699
`#import' which includes a file, but does so at most once.  If you use
3700
`#import' instead of `#include', then you don't need the conditionals
3701
inside the header file to prevent multiple inclusion of the contents.
3702
GCC permits the use of `#import' in C and C++ as well as Objective-C.
3703
However, it is not in standard C or C++ and should therefore not be
3704
used by portable programs.
3705
 
3706
   `#import' is not a well designed feature.  It requires the users of
3707
a header file to know that it should only be included once.  It is much
3708
better for the header file's implementor to write the file so that users
3709
don't need to know this.  Using a wrapper `#ifndef' accomplishes this
3710
goal.
3711
 
3712
   In the present implementation, a single use of `#import' will
3713
prevent the file from ever being read again, by either `#import' or
3714
`#include'.  You should not rely on this; do not use both `#import' and
3715
`#include' to refer to the same header file.
3716
 
3717
   Another way to prevent a header file from being included more than
3718
once is with the `#pragma once' directive.  If `#pragma once' is seen
3719
when scanning a header file, that file will never be read again, no
3720
matter what.
3721
 
3722
   `#pragma once' does not have the problems that `#import' does, but
3723
it is not recognized by all preprocessors, so you cannot rely on it in
3724
a portable program.
3725
 
3726

3727
File: cpp.info,  Node: Differences from previous versions,  Prev: Obsolete Features,  Up: Implementation Details
3728
 
3729
11.4 Differences from previous versions
3730
=======================================
3731
 
3732
This section details behavior which has changed from previous versions
3733
of CPP.  We do not plan to change it again in the near future, but we
3734
do not promise not to, either.
3735
 
3736
   The "previous versions" discussed here are 2.95 and before.  The
3737
behavior of GCC 3.0 is mostly the same as the behavior of the widely
3738
used 2.96 and 2.97 development snapshots.  Where there are differences,
3739
they generally represent bugs in the snapshots.
3740
 
3741
   * -I- deprecated
3742
 
3743
     This option has been deprecated in 4.0.  `-iquote' is meant to
3744
     replace the need for this option.
3745
 
3746
   * Order of evaluation of `#' and `##' operators
3747
 
3748
     The standard does not specify the order of evaluation of a chain of
3749
     `##' operators, nor whether `#' is evaluated before, after, or at
3750
     the same time as `##'.  You should therefore not write any code
3751
     which depends on any specific ordering.  It is possible to
3752
     guarantee an ordering, if you need one, by suitable use of nested
3753
     macros.
3754
 
3755
     An example of where this might matter is pasting the arguments `1',
3756
     `e' and `-2'.  This would be fine for left-to-right pasting, but
3757
     right-to-left pasting would produce an invalid token `e-2'.
3758
 
3759
     GCC 3.0 evaluates `#' and `##' at the same time and strictly left
3760
     to right.  Older versions evaluated all `#' operators first, then
3761
     all `##' operators, in an unreliable order.
3762
 
3763
   * The form of whitespace between tokens in preprocessor output
3764
 
3765
     *Note Preprocessor Output::, for the current textual format.  This
3766
     is also the format used by stringification.  Normally, the
3767
     preprocessor communicates tokens directly to the compiler's
3768
     parser, and whitespace does not come up at all.
3769
 
3770
     Older versions of GCC preserved all whitespace provided by the
3771
     user and inserted lots more whitespace of their own, because they
3772
     could not accurately predict when extra spaces were needed to
3773
     prevent accidental token pasting.
3774
 
3775
   * Optional argument when invoking rest argument macros
3776
 
3777
     As an extension, GCC permits you to omit the variable arguments
3778
     entirely when you use a variable argument macro.  This is
3779
     forbidden by the 1999 C standard, and will provoke a pedantic
3780
     warning with GCC 3.0.  Previous versions accepted it silently.
3781
 
3782
   * `##' swallowing preceding text in rest argument macros
3783
 
3784
     Formerly, in a macro expansion, if `##' appeared before a variable
3785
     arguments parameter, and the set of tokens specified for that
3786
     argument in the macro invocation was empty, previous versions of
3787
     CPP would back up and remove the preceding sequence of
3788
     non-whitespace characters (*not* the preceding token).  This
3789
     extension is in direct conflict with the 1999 C standard and has
3790
     been drastically pared back.
3791
 
3792
     In the current version of the preprocessor, if `##' appears between
3793
     a comma and a variable arguments parameter, and the variable
3794
     argument is omitted entirely, the comma will be removed from the
3795
     expansion.  If the variable argument is empty, or the token before
3796
     `##' is not a comma, then `##' behaves as a normal token paste.
3797
 
3798
   * `#line' and `#include'
3799
 
3800
     The `#line' directive used to change GCC's notion of the
3801
     "directory containing the current file", used by `#include' with a
3802
     double-quoted header file name.  In 3.0 and later, it does not.
3803
     *Note Line Control::, for further explanation.
3804
 
3805
   * Syntax of `#line'
3806
 
3807
     In GCC 2.95 and previous, the string constant argument to `#line'
3808
     was treated the same way as the argument to `#include': backslash
3809
     escapes were not honored, and the string ended at the second `"'.
3810
     This is not compliant with the C standard.  In GCC 3.0, an attempt
3811
     was made to correct the behavior, so that the string was treated
3812
     as a real string constant, but it turned out to be buggy.  In 3.1,
3813
     the bugs have been fixed.  (We are not fixing the bugs in 3.0
3814
     because they affect relatively few people and the fix is quite
3815
     invasive.)
3816
 
3817
 
3818

3819
File: cpp.info,  Node: Invocation,  Next: Environment Variables,  Prev: Implementation Details,  Up: Top
3820
 
3821
12 Invocation
3822
*************
3823
 
3824
Most often when you use the C preprocessor you will not have to invoke
3825
it explicitly: the C compiler will do so automatically.  However, the
3826
preprocessor is sometimes useful on its own.  All the options listed
3827
here are also acceptable to the C compiler and have the same meaning,
3828
except that the C compiler has different rules for specifying the output
3829
file.
3830
 
3831
   _Note:_ Whether you use the preprocessor by way of `gcc' or `cpp',
3832
the "compiler driver" is run first.  This program's purpose is to
3833
translate your command into invocations of the programs that do the
3834
actual work.  Their command line interfaces are similar but not
3835
identical to the documented interface, and may change without notice.
3836
 
3837
   The C preprocessor expects two file names as arguments, INFILE and
3838
OUTFILE.  The preprocessor reads INFILE together with any other files
3839
it specifies with `#include'.  All the output generated by the combined
3840
input files is written in OUTFILE.
3841
 
3842
   Either INFILE or OUTFILE may be `-', which as INFILE means to read
3843
from standard input and as OUTFILE means to write to standard output.
3844
Also, if either file is omitted, it means the same as if `-' had been
3845
specified for that file.
3846
 
3847
   Unless otherwise noted, or the option ends in `=', all options which
3848
take an argument may have that argument appear either immediately after
3849
the option, or with a space between option and argument: `-Ifoo' and
3850
`-I foo' have the same effect.
3851
 
3852
   Many options have multi-letter names; therefore multiple
3853
single-letter options may _not_ be grouped: `-dM' is very different from
3854
`-d -M'.
3855
 
3856
`-D NAME'
3857
     Predefine NAME as a macro, with definition `1'.
3858
 
3859
`-D NAME=DEFINITION'
3860
     The contents of DEFINITION are tokenized and processed as if they
3861
     appeared during translation phase three in a `#define' directive.
3862
     In particular, the definition will be truncated by embedded
3863
     newline characters.
3864
 
3865
     If you are invoking the preprocessor from a shell or shell-like
3866
     program you may need to use the shell's quoting syntax to protect
3867
     characters such as spaces that have a meaning in the shell syntax.
3868
 
3869
     If you wish to define a function-like macro on the command line,
3870
     write its argument list with surrounding parentheses before the
3871
     equals sign (if any).  Parentheses are meaningful to most shells,
3872
     so you will need to quote the option.  With `sh' and `csh',
3873
     `-D'NAME(ARGS...)=DEFINITION'' works.
3874
 
3875
     `-D' and `-U' options are processed in the order they are given on
3876
     the command line.  All `-imacros FILE' and `-include FILE' options
3877
     are processed after all `-D' and `-U' options.
3878
 
3879
`-U NAME'
3880
     Cancel any previous definition of NAME, either built in or
3881
     provided with a `-D' option.
3882
 
3883
`-undef'
3884
     Do not predefine any system-specific or GCC-specific macros.  The
3885
     standard predefined macros remain defined.  *Note Standard
3886
     Predefined Macros::.
3887
 
3888
`-I DIR'
3889
     Add the directory DIR to the list of directories to be searched
3890
     for header files.  *Note Search Path::.  Directories named by `-I'
3891
     are searched before the standard system include directories.  If
3892
     the directory DIR is a standard system include directory, the
3893
     option is ignored to ensure that the default search order for
3894
     system directories and the special treatment of system headers are
3895
     not defeated (*note System Headers::) .
3896
 
3897
`-o FILE'
3898
     Write output to FILE.  This is the same as specifying FILE as the
3899
     second non-option argument to `cpp'.  `gcc' has a different
3900
     interpretation of a second non-option argument, so you must use
3901
     `-o' to specify the output file.
3902
 
3903
`-Wall'
3904
     Turns on all optional warnings which are desirable for normal code.
3905
     At present this is `-Wcomment', `-Wtrigraphs', `-Wmultichar' and a
3906
     warning about integer promotion causing a change of sign in `#if'
3907
     expressions.  Note that many of the preprocessor's warnings are on
3908
     by default and have no options to control them.
3909
 
3910
`-Wcomment'
3911
`-Wcomments'
3912
     Warn whenever a comment-start sequence `/*' appears in a `/*'
3913
     comment, or whenever a backslash-newline appears in a `//' comment.
3914
     (Both forms have the same effect.)
3915
 
3916
`-Wtrigraphs'
3917
     Most trigraphs in comments cannot affect the meaning of the
3918
     program.  However, a trigraph that would form an escaped newline
3919
     (`??/' at the end of a line) can, by changing where the comment
3920
     begins or ends.  Therefore, only trigraphs that would form escaped
3921
     newlines produce warnings inside a comment.
3922
 
3923
     This option is implied by `-Wall'.  If `-Wall' is not given, this
3924
     option is still enabled unless trigraphs are enabled.  To get
3925
     trigraph conversion without warnings, but get the other `-Wall'
3926
     warnings, use `-trigraphs -Wall -Wno-trigraphs'.
3927
 
3928
`-Wtraditional'
3929
     Warn about certain constructs that behave differently in
3930
     traditional and ISO C.  Also warn about ISO C constructs that have
3931
     no traditional C equivalent, and problematic constructs which
3932
     should be avoided.  *Note Traditional Mode::.
3933
 
3934
`-Wimport'
3935
     Warn the first time `#import' is used.
3936
 
3937
`-Wundef'
3938
     Warn whenever an identifier which is not a macro is encountered in
3939
     an `#if' directive, outside of `defined'.  Such identifiers are
3940
     replaced with zero.
3941
 
3942
`-Wunused-macros'
3943
     Warn about macros defined in the main file that are unused.  A
3944
     macro is "used" if it is expanded or tested for existence at least
3945
     once.  The preprocessor will also warn if the macro has not been
3946
     used at the time it is redefined or undefined.
3947
 
3948
     Built-in macros, macros defined on the command line, and macros
3949
     defined in include files are not warned about.
3950
 
3951
     _Note:_ If a macro is actually used, but only used in skipped
3952
     conditional blocks, then CPP will report it as unused.  To avoid
3953
     the warning in such a case, you might improve the scope of the
3954
     macro's definition by, for example, moving it into the first
3955
     skipped block.  Alternatively, you could provide a dummy use with
3956
     something like:
3957
 
3958
          #if defined the_macro_causing_the_warning
3959
          #endif
3960
 
3961
`-Wendif-labels'
3962
     Warn whenever an `#else' or an `#endif' are followed by text.
3963
     This usually happens in code of the form
3964
 
3965
          #if FOO
3966
          ...
3967
          #else FOO
3968
          ...
3969
          #endif FOO
3970
 
3971
     The second and third `FOO' should be in comments, but often are not
3972
     in older programs.  This warning is on by default.
3973
 
3974
`-Werror'
3975
     Make all warnings into hard errors.  Source code which triggers
3976
     warnings will be rejected.
3977
 
3978
`-Wsystem-headers'
3979
     Issue warnings for code in system headers.  These are normally
3980
     unhelpful in finding bugs in your own code, therefore suppressed.
3981
     If you are responsible for the system library, you may want to see
3982
     them.
3983
 
3984
`-w'
3985
     Suppress all warnings, including those which GNU CPP issues by
3986
     default.
3987
 
3988
`-pedantic'
3989
     Issue all the mandatory diagnostics listed in the C standard.
3990
     Some of them are left out by default, since they trigger
3991
     frequently on harmless code.
3992
 
3993
`-pedantic-errors'
3994
     Issue all the mandatory diagnostics, and make all mandatory
3995
     diagnostics into errors.  This includes mandatory diagnostics that
3996
     GCC issues without `-pedantic' but treats as warnings.
3997
 
3998
`-M'
3999
     Instead of outputting the result of preprocessing, output a rule
4000
     suitable for `make' describing the dependencies of the main source
4001
     file.  The preprocessor outputs one `make' rule containing the
4002
     object file name for that source file, a colon, and the names of
4003
     all the included files, including those coming from `-include' or
4004
     `-imacros' command line options.
4005
 
4006
     Unless specified explicitly (with `-MT' or `-MQ'), the object file
4007
     name consists of the basename of the source file with any suffix
4008
     replaced with object file suffix.  If there are many included
4009
     files then the rule is split into several lines using `\'-newline.
4010
     The rule has no commands.
4011
 
4012
     This option does not suppress the preprocessor's debug output,
4013
     such as `-dM'.  To avoid mixing such debug output with the
4014
     dependency rules you should explicitly specify the dependency
4015
     output file with `-MF', or use an environment variable like
4016
     `DEPENDENCIES_OUTPUT' (*note Environment Variables::).  Debug
4017
     output will still be sent to the regular output stream as normal.
4018
 
4019
     Passing `-M' to the driver implies `-E', and suppresses warnings
4020
     with an implicit `-w'.
4021
 
4022
`-MM'
4023
     Like `-M' but do not mention header files that are found in system
4024
     header directories, nor header files that are included, directly
4025
     or indirectly, from such a header.
4026
 
4027
     This implies that the choice of angle brackets or double quotes in
4028
     an `#include' directive does not in itself determine whether that
4029
     header will appear in `-MM' dependency output.  This is a slight
4030
     change in semantics from GCC versions 3.0 and earlier.
4031
 
4032
`-MF FILE'
4033
     When used with `-M' or `-MM', specifies a file to write the
4034
     dependencies to.  If no `-MF' switch is given the preprocessor
4035
     sends the rules to the same place it would have sent preprocessed
4036
     output.
4037
 
4038
     When used with the driver options `-MD' or `-MMD', `-MF' overrides
4039
     the default dependency output file.
4040
 
4041
`-MG'
4042
     In conjunction with an option such as `-M' requesting dependency
4043
     generation, `-MG' assumes missing header files are generated files
4044
     and adds them to the dependency list without raising an error.
4045
     The dependency filename is taken directly from the `#include'
4046
     directive without prepending any path.  `-MG' also suppresses
4047
     preprocessed output, as a missing header file renders this useless.
4048
 
4049
     This feature is used in automatic updating of makefiles.
4050
 
4051
`-MP'
4052
     This option instructs CPP to add a phony target for each dependency
4053
     other than the main file, causing each to depend on nothing.  These
4054
     dummy rules work around errors `make' gives if you remove header
4055
     files without updating the `Makefile' to match.
4056
 
4057
     This is typical output:
4058
 
4059
          test.o: test.c test.h
4060
 
4061
          test.h:
4062
 
4063
`-MT TARGET'
4064
     Change the target of the rule emitted by dependency generation.  By
4065
     default CPP takes the name of the main input file, including any
4066
     path, deletes any file suffix such as `.c', and appends the
4067
     platform's usual object suffix.  The result is the target.
4068
 
4069
     An `-MT' option will set the target to be exactly the string you
4070
     specify.  If you want multiple targets, you can specify them as a
4071
     single argument to `-MT', or use multiple `-MT' options.
4072
 
4073
     For example, `-MT '$(objpfx)foo.o'' might give
4074
 
4075
          $(objpfx)foo.o: foo.c
4076
 
4077
`-MQ TARGET'
4078
     Same as `-MT', but it quotes any characters which are special to
4079
     Make.  `-MQ '$(objpfx)foo.o'' gives
4080
 
4081
          $$(objpfx)foo.o: foo.c
4082
 
4083
     The default target is automatically quoted, as if it were given
4084
     with `-MQ'.
4085
 
4086
`-MD'
4087
     `-MD' is equivalent to `-M -MF FILE', except that `-E' is not
4088
     implied.  The driver determines FILE based on whether an `-o'
4089
     option is given.  If it is, the driver uses its argument but with
4090
     a suffix of `.d', otherwise it take the basename of the input file
4091
     and applies a `.d' suffix.
4092
 
4093
     If `-MD' is used in conjunction with `-E', any `-o' switch is
4094
     understood to specify the dependency output file (*note -MF:
4095
     dashMF.), but if used without `-E', each `-o' is understood to
4096
     specify a target object file.
4097
 
4098
     Since `-E' is not implied, `-MD' can be used to generate a
4099
     dependency output file as a side-effect of the compilation process.
4100
 
4101
`-MMD'
4102
     Like `-MD' except mention only user header files, not system
4103
     header files.
4104
 
4105
`-x c'
4106
`-x c++'
4107
`-x objective-c'
4108
`-x assembler-with-cpp'
4109
     Specify the source language: C, C++, Objective-C, or assembly.
4110
     This has nothing to do with standards conformance or extensions;
4111
     it merely selects which base syntax to expect.  If you give none
4112
     of these options, cpp will deduce the language from the extension
4113
     of the source file: `.c', `.cc', `.m', or `.S'.  Some other common
4114
     extensions for C++ and assembly are also recognized.  If cpp does
4115
     not recognize the extension, it will treat the file as C; this is
4116
     the most generic mode.
4117
 
4118
     _Note:_ Previous versions of cpp accepted a `-lang' option which
4119
     selected both the language and the standards conformance level.
4120
     This option has been removed, because it conflicts with the `-l'
4121
     option.
4122
 
4123
`-std=STANDARD'
4124
`-ansi'
4125
     Specify the standard to which the code should conform.  Currently
4126
     CPP knows about C and C++ standards; others may be added in the
4127
     future.
4128
 
4129
     STANDARD may be one of:
4130
    `iso9899:1990'
4131
    `c89'
4132
          The ISO C standard from 1990.  `c89' is the customary
4133
          shorthand for this version of the standard.
4134
 
4135
          The `-ansi' option is equivalent to `-std=c89'.
4136
 
4137
    `iso9899:199409'
4138
          The 1990 C standard, as amended in 1994.
4139
 
4140
    `iso9899:1999'
4141
    `c99'
4142
    `iso9899:199x'
4143
    `c9x'
4144
          The revised ISO C standard, published in December 1999.
4145
          Before publication, this was known as C9X.
4146
 
4147
    `gnu89'
4148
          The 1990 C standard plus GNU extensions.  This is the default.
4149
 
4150
    `gnu99'
4151
    `gnu9x'
4152
          The 1999 C standard plus GNU extensions.
4153
 
4154
    `c++98'
4155
          The 1998 ISO C++ standard plus amendments.
4156
 
4157
    `gnu++98'
4158
          The same as `-std=c++98' plus GNU extensions.  This is the
4159
          default for C++ code.
4160
 
4161
`-I-'
4162
     Split the include path.  Any directories specified with `-I'
4163
     options before `-I-' are searched only for headers requested with
4164
     `#include "FILE"'; they are not searched for `#include '.
4165
     If additional directories are specified with `-I' options after
4166
     the `-I-', those directories are searched for all `#include'
4167
     directives.
4168
 
4169
     In addition, `-I-' inhibits the use of the directory of the current
4170
     file directory as the first search directory for `#include "FILE"'.
4171
     *Note Search Path::.  This option has been deprecated.
4172
 
4173
`-nostdinc'
4174
     Do not search the standard system directories for header files.
4175
     Only the directories you have specified with `-I' options (and the
4176
     directory of the current file, if appropriate) are searched.
4177
 
4178
`-nostdinc++'
4179
     Do not search for header files in the C++-specific standard
4180
     directories, but do still search the other standard directories.
4181
     (This option is used when building the C++ library.)
4182
 
4183
`-include FILE'
4184
     Process FILE as if `#include "file"' appeared as the first line of
4185
     the primary source file.  However, the first directory searched
4186
     for FILE is the preprocessor's working directory _instead of_ the
4187
     directory containing the main source file.  If not found there, it
4188
     is searched for in the remainder of the `#include "..."' search
4189
     chain as normal.
4190
 
4191
     If multiple `-include' options are given, the files are included
4192
     in the order they appear on the command line.
4193
 
4194
`-imacros FILE'
4195
     Exactly like `-include', except that any output produced by
4196
     scanning FILE is thrown away.  Macros it defines remain defined.
4197
     This allows you to acquire all the macros from a header without
4198
     also processing its declarations.
4199
 
4200
     All files specified by `-imacros' are processed before all files
4201
     specified by `-include'.
4202
 
4203
`-idirafter DIR'
4204
     Search DIR for header files, but do it _after_ all directories
4205
     specified with `-I' and the standard system directories have been
4206
     exhausted.  DIR is treated as a system include directory.
4207
 
4208
`-iprefix PREFIX'
4209
     Specify PREFIX as the prefix for subsequent `-iwithprefix'
4210
     options.  If the prefix represents a directory, you should include
4211
     the final `/'.
4212
 
4213
`-iwithprefix DIR'
4214
`-iwithprefixbefore DIR'
4215
     Append DIR to the prefix specified previously with `-iprefix', and
4216
     add the resulting directory to the include search path.
4217
     `-iwithprefixbefore' puts it in the same place `-I' would;
4218
     `-iwithprefix' puts it where `-idirafter' would.
4219
 
4220
`-isysroot DIR'
4221
     This option is like the `--sysroot' option, but applies only to
4222
     header files.  See the `--sysroot' option for more information.
4223
 
4224
`-imultilib DIR'
4225
     Use DIR as a subdirectory of the directory containing
4226
     target-specific C++ headers.
4227
 
4228
`-isystem DIR'
4229
     Search DIR for header files, after all directories specified by
4230
     `-I' but before the standard system directories.  Mark it as a
4231
     system directory, so that it gets the same special treatment as is
4232
     applied to the standard system directories.  *Note System
4233
     Headers::.
4234
 
4235
`-iquote DIR'
4236
     Search DIR only for header files requested with `#include "FILE"';
4237
     they are not searched for `#include ', before all
4238
     directories specified by `-I' and before the standard system
4239
     directories.  *Note Search Path::.
4240
 
4241
`-fdollars-in-identifiers'
4242
     Accept `$' in identifiers.    *Note Identifier characters::.
4243
 
4244
`-fextended-identifiers'
4245
     Accept universal character names in identifiers.  This option is
4246
     experimental; in a future version of GCC, it will be enabled by
4247
     default for C99 and C++.
4248
 
4249
`-fpreprocessed'
4250
     Indicate to the preprocessor that the input file has already been
4251
     preprocessed.  This suppresses things like macro expansion,
4252
     trigraph conversion, escaped newline splicing, and processing of
4253
     most directives.  The preprocessor still recognizes and removes
4254
     comments, so that you can pass a file preprocessed with `-C' to
4255
     the compiler without problems.  In this mode the integrated
4256
     preprocessor is little more than a tokenizer for the front ends.
4257
 
4258
     `-fpreprocessed' is implicit if the input file has one of the
4259
     extensions `.i', `.ii' or `.mi'.  These are the extensions that
4260
     GCC uses for preprocessed files created by `-save-temps'.
4261
 
4262
`-ftabstop=WIDTH'
4263
     Set the distance between tab stops.  This helps the preprocessor
4264
     report correct column numbers in warnings or errors, even if tabs
4265
     appear on the line.  If the value is less than 1 or greater than
4266
     100, the option is ignored.  The default is 8.
4267
 
4268
`-fexec-charset=CHARSET'
4269
     Set the execution character set, used for string and character
4270
     constants.  The default is UTF-8.  CHARSET can be any encoding
4271
     supported by the system's `iconv' library routine.
4272
 
4273
`-fwide-exec-charset=CHARSET'
4274
     Set the wide execution character set, used for wide string and
4275
     character constants.  The default is UTF-32 or UTF-16, whichever
4276
     corresponds to the width of `wchar_t'.  As with `-fexec-charset',
4277
     CHARSET can be any encoding supported by the system's `iconv'
4278
     library routine; however, you will have problems with encodings
4279
     that do not fit exactly in `wchar_t'.
4280
 
4281
`-finput-charset=CHARSET'
4282
     Set the input character set, used for translation from the
4283
     character set of the input file to the source character set used
4284
     by GCC.  If the locale does not specify, or GCC cannot get this
4285
     information from the locale, the default is UTF-8.  This can be
4286
     overridden by either the locale or this command line option.
4287
     Currently the command line option takes precedence if there's a
4288
     conflict.  CHARSET can be any encoding supported by the system's
4289
     `iconv' library routine.
4290
 
4291
`-fworking-directory'
4292
     Enable generation of linemarkers in the preprocessor output that
4293
     will let the compiler know the current working directory at the
4294
     time of preprocessing.  When this option is enabled, the
4295
     preprocessor will emit, after the initial linemarker, a second
4296
     linemarker with the current working directory followed by two
4297
     slashes.  GCC will use this directory, when it's present in the
4298
     preprocessed input, as the directory emitted as the current
4299
     working directory in some debugging information formats.  This
4300
     option is implicitly enabled if debugging information is enabled,
4301
     but this can be inhibited with the negated form
4302
     `-fno-working-directory'.  If the `-P' flag is present in the
4303
     command line, this option has no effect, since no `#line'
4304
     directives are emitted whatsoever.
4305
 
4306
`-fno-show-column'
4307
     Do not print column numbers in diagnostics.  This may be necessary
4308
     if diagnostics are being scanned by a program that does not
4309
     understand the column numbers, such as `dejagnu'.
4310
 
4311
`-A PREDICATE=ANSWER'
4312
     Make an assertion with the predicate PREDICATE and answer ANSWER.
4313
     This form is preferred to the older form `-A PREDICATE(ANSWER)',
4314
     which is still supported, because it does not use shell special
4315
     characters.  *Note Assertions::.
4316
 
4317
`-A -PREDICATE=ANSWER'
4318
     Cancel an assertion with the predicate PREDICATE and answer ANSWER.
4319
 
4320
`-dCHARS'
4321
     CHARS is a sequence of one or more of the following characters,
4322
     and must not be preceded by a space.  Other characters are
4323
     interpreted by the compiler proper, or reserved for future
4324
     versions of GCC, and so are silently ignored.  If you specify
4325
     characters whose behavior conflicts, the result is undefined.
4326
 
4327
    `M'
4328
          Instead of the normal output, generate a list of `#define'
4329
          directives for all the macros defined during the execution of
4330
          the preprocessor, including predefined macros.  This gives
4331
          you a way of finding out what is predefined in your version
4332
          of the preprocessor.  Assuming you have no file `foo.h', the
4333
          command
4334
 
4335
               touch foo.h; cpp -dM foo.h
4336
 
4337
          will show all the predefined macros.
4338
 
4339
    `D'
4340
          Like `M' except in two respects: it does _not_ include the
4341
          predefined macros, and it outputs _both_ the `#define'
4342
          directives and the result of preprocessing.  Both kinds of
4343
          output go to the standard output file.
4344
 
4345
    `N'
4346
          Like `D', but emit only the macro names, not their expansions.
4347
 
4348
    `I'
4349
          Output `#include' directives in addition to the result of
4350
          preprocessing.
4351
 
4352
`-P'
4353
     Inhibit generation of linemarkers in the output from the
4354
     preprocessor.  This might be useful when running the preprocessor
4355
     on something that is not C code, and will be sent to a program
4356
     which might be confused by the linemarkers.  *Note Preprocessor
4357
     Output::.
4358
 
4359
`-C'
4360
     Do not discard comments.  All comments are passed through to the
4361
     output file, except for comments in processed directives, which
4362
     are deleted along with the directive.
4363
 
4364
     You should be prepared for side effects when using `-C'; it causes
4365
     the preprocessor to treat comments as tokens in their own right.
4366
     For example, comments appearing at the start of what would be a
4367
     directive line have the effect of turning that line into an
4368
     ordinary source line, since the first token on the line is no
4369
     longer a `#'.
4370
 
4371
`-CC'
4372
     Do not discard comments, including during macro expansion.  This is
4373
     like `-C', except that comments contained within macros are also
4374
     passed through to the output file where the macro is expanded.
4375
 
4376
     In addition to the side-effects of the `-C' option, the `-CC'
4377
     option causes all C++-style comments inside a macro to be
4378
     converted to C-style comments.  This is to prevent later use of
4379
     that macro from inadvertently commenting out the remainder of the
4380
     source line.
4381
 
4382
     The `-CC' option is generally used to support lint comments.
4383
 
4384
`-traditional-cpp'
4385
     Try to imitate the behavior of old-fashioned C preprocessors, as
4386
     opposed to ISO C preprocessors.  *Note Traditional Mode::.
4387
 
4388
`-trigraphs'
4389
     Process trigraph sequences.  *Note Initial processing::.
4390
 
4391
`-remap'
4392
     Enable special code to work around file systems which only permit
4393
     very short file names, such as MS-DOS.
4394
 
4395
`--help'
4396
`--target-help'
4397
     Print text describing all the command line options instead of
4398
     preprocessing anything.
4399
 
4400
`-v'
4401
     Verbose mode.  Print out GNU CPP's version number at the beginning
4402
     of execution, and report the final form of the include path.
4403
 
4404
`-H'
4405
     Print the name of each header file used, in addition to other
4406
     normal activities.  Each name is indented to show how deep in the
4407
     `#include' stack it is.  Precompiled header files are also
4408
     printed, even if they are found to be invalid; an invalid
4409
     precompiled header file is printed with `...x' and a valid one
4410
     with `...!' .
4411
 
4412
`-version'
4413
`--version'
4414
     Print out GNU CPP's version number.  With one dash, proceed to
4415
     preprocess as normal.  With two dashes, exit immediately.
4416
 
4417

4418
File: cpp.info,  Node: Environment Variables,  Next: GNU Free Documentation License,  Prev: Invocation,  Up: Top
4419
 
4420
13 Environment Variables
4421
************************
4422
 
4423
This section describes the environment variables that affect how CPP
4424
operates.  You can use them to specify directories or prefixes to use
4425
when searching for include files, or to control dependency output.
4426
 
4427
   Note that you can also specify places to search using options such as
4428
`-I', and control dependency output with options like `-M' (*note
4429
Invocation::).  These take precedence over environment variables, which
4430
in turn take precedence over the configuration of GCC.
4431
 
4432
`CPATH'
4433
`C_INCLUDE_PATH'
4434
`CPLUS_INCLUDE_PATH'
4435
`OBJC_INCLUDE_PATH'
4436
     Each variable's value is a list of directories separated by a
4437
     special character, much like `PATH', in which to look for header
4438
     files.  The special character, `PATH_SEPARATOR', is
4439
     target-dependent and determined at GCC build time.  For Microsoft
4440
     Windows-based targets it is a semicolon, and for almost all other
4441
     targets it is a colon.
4442
 
4443
     `CPATH' specifies a list of directories to be searched as if
4444
     specified with `-I', but after any paths given with `-I' options
4445
     on the command line.  This environment variable is used regardless
4446
     of which language is being preprocessed.
4447
 
4448
     The remaining environment variables apply only when preprocessing
4449
     the particular language indicated.  Each specifies a list of
4450
     directories to be searched as if specified with `-isystem', but
4451
     after any paths given with `-isystem' options on the command line.
4452
 
4453
     In all these variables, an empty element instructs the compiler to
4454
     search its current working directory.  Empty elements can appear
4455
     at the beginning or end of a path.  For instance, if the value of
4456
     `CPATH' is `:/special/include', that has the same effect as
4457
     `-I. -I/special/include'.
4458
 
4459
     See also *Note Search Path::.
4460
 
4461
`DEPENDENCIES_OUTPUT'
4462
     If this variable is set, its value specifies how to output
4463
     dependencies for Make based on the non-system header files
4464
     processed by the compiler.  System header files are ignored in the
4465
     dependency output.
4466
 
4467
     The value of `DEPENDENCIES_OUTPUT' can be just a file name, in
4468
     which case the Make rules are written to that file, guessing the
4469
     target name from the source file name.  Or the value can have the
4470
     form `FILE TARGET', in which case the rules are written to file
4471
     FILE using TARGET as the target name.
4472
 
4473
     In other words, this environment variable is equivalent to
4474
     combining the options `-MM' and `-MF' (*note Invocation::), with
4475
     an optional `-MT' switch too.
4476
 
4477
`SUNPRO_DEPENDENCIES'
4478
     This variable is the same as `DEPENDENCIES_OUTPUT' (see above),
4479
     except that system header files are not ignored, so it implies
4480
     `-M' rather than `-MM'.  However, the dependence on the main input
4481
     file is omitted.  *Note Invocation::.
4482
 
4483

4484
File: cpp.info,  Node: GNU Free Documentation License,  Next: Index of Directives,  Prev: Environment Variables,  Up: Top
4485
 
4486
GNU Free Documentation License
4487
******************************
4488
 
4489
                      Version 1.2, November 2002
4490
 
4491
     Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
4492
     51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
4493
 
4494
     Everyone is permitted to copy and distribute verbatim copies
4495
     of this license document, but changing it is not allowed.
4496
 
4497
  0. PREAMBLE
4498
 
4499
     The purpose of this License is to make a manual, textbook, or other
4500
     functional and useful document "free" in the sense of freedom: to
4501
     assure everyone the effective freedom to copy and redistribute it,
4502
     with or without modifying it, either commercially or
4503
     noncommercially.  Secondarily, this License preserves for the
4504
     author and publisher a way to get credit for their work, while not
4505
     being considered responsible for modifications made by others.
4506
 
4507
     This License is a kind of "copyleft", which means that derivative
4508
     works of the document must themselves be free in the same sense.
4509
     It complements the GNU General Public License, which is a copyleft
4510
     license designed for free software.
4511
 
4512
     We have designed this License in order to use it for manuals for
4513
     free software, because free software needs free documentation: a
4514
     free program should come with manuals providing the same freedoms
4515
     that the software does.  But this License is not limited to
4516
     software manuals; it can be used for any textual work, regardless
4517
     of subject matter or whether it is published as a printed book.
4518
     We recommend this License principally for works whose purpose is
4519
     instruction or reference.
4520
 
4521
  1. APPLICABILITY AND DEFINITIONS
4522
 
4523
     This License applies to any manual or other work, in any medium,
4524
     that contains a notice placed by the copyright holder saying it
4525
     can be distributed under the terms of this License.  Such a notice
4526
     grants a world-wide, royalty-free license, unlimited in duration,
4527
     to use that work under the conditions stated herein.  The
4528
     "Document", below, refers to any such manual or work.  Any member
4529
     of the public is a licensee, and is addressed as "you".  You
4530
     accept the license if you copy, modify or distribute the work in a
4531
     way requiring permission under copyright law.
4532
 
4533
     A "Modified Version" of the Document means any work containing the
4534
     Document or a portion of it, either copied verbatim, or with
4535
     modifications and/or translated into another language.
4536
 
4537
     A "Secondary Section" is a named appendix or a front-matter section
4538
     of the Document that deals exclusively with the relationship of the
4539
     publishers or authors of the Document to the Document's overall
4540
     subject (or to related matters) and contains nothing that could
4541
     fall directly within that overall subject.  (Thus, if the Document
4542
     is in part a textbook of mathematics, a Secondary Section may not
4543
     explain any mathematics.)  The relationship could be a matter of
4544
     historical connection with the subject or with related matters, or
4545
     of legal, commercial, philosophical, ethical or political position
4546
     regarding them.
4547
 
4548
     The "Invariant Sections" are certain Secondary Sections whose
4549
     titles are designated, as being those of Invariant Sections, in
4550
     the notice that says that the Document is released under this
4551
     License.  If a section does not fit the above definition of
4552
     Secondary then it is not allowed to be designated as Invariant.
4553
     The Document may contain zero Invariant Sections.  If the Document
4554
     does not identify any Invariant Sections then there are none.
4555
 
4556
     The "Cover Texts" are certain short passages of text that are
4557
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
4558
     that says that the Document is released under this License.  A
4559
     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
4560
     be at most 25 words.
4561
 
4562
     A "Transparent" copy of the Document means a machine-readable copy,
4563
     represented in a format whose specification is available to the
4564
     general public, that is suitable for revising the document
4565
     straightforwardly with generic text editors or (for images
4566
     composed of pixels) generic paint programs or (for drawings) some
4567
     widely available drawing editor, and that is suitable for input to
4568
     text formatters or for automatic translation to a variety of
4569
     formats suitable for input to text formatters.  A copy made in an
4570
     otherwise Transparent file format whose markup, or absence of
4571
     markup, has been arranged to thwart or discourage subsequent
4572
     modification by readers is not Transparent.  An image format is
4573
     not Transparent if used for any substantial amount of text.  A
4574
     copy that is not "Transparent" is called "Opaque".
4575
 
4576
     Examples of suitable formats for Transparent copies include plain
4577
     ASCII without markup, Texinfo input format, LaTeX input format,
4578
     SGML or XML using a publicly available DTD, and
4579
     standard-conforming simple HTML, PostScript or PDF designed for
4580
     human modification.  Examples of transparent image formats include
4581
     PNG, XCF and JPG.  Opaque formats include proprietary formats that
4582
     can be read and edited only by proprietary word processors, SGML or
4583
     XML for which the DTD and/or processing tools are not generally
4584
     available, and the machine-generated HTML, PostScript or PDF
4585
     produced by some word processors for output purposes only.
4586
 
4587
     The "Title Page" means, for a printed book, the title page itself,
4588
     plus such following pages as are needed to hold, legibly, the
4589
     material this License requires to appear in the title page.  For
4590
     works in formats which do not have any title page as such, "Title
4591
     Page" means the text near the most prominent appearance of the
4592
     work's title, preceding the beginning of the body of the text.
4593
 
4594
     A section "Entitled XYZ" means a named subunit of the Document
4595
     whose title either is precisely XYZ or contains XYZ in parentheses
4596
     following text that translates XYZ in another language.  (Here XYZ
4597
     stands for a specific section name mentioned below, such as
4598
     "Acknowledgements", "Dedications", "Endorsements", or "History".)
4599
     To "Preserve the Title" of such a section when you modify the
4600
     Document means that it remains a section "Entitled XYZ" according
4601
     to this definition.
4602
 
4603
     The Document may include Warranty Disclaimers next to the notice
4604
     which states that this License applies to the Document.  These
4605
     Warranty Disclaimers are considered to be included by reference in
4606
     this License, but only as regards disclaiming warranties: any other
4607
     implication that these Warranty Disclaimers may have is void and
4608
     has no effect on the meaning of this License.
4609
 
4610
  2. VERBATIM COPYING
4611
 
4612
     You may copy and distribute the Document in any medium, either
4613
     commercially or noncommercially, provided that this License, the
4614
     copyright notices, and the license notice saying this License
4615
     applies to the Document are reproduced in all copies, and that you
4616
     add no other conditions whatsoever to those of this License.  You
4617
     may not use technical measures to obstruct or control the reading
4618
     or further copying of the copies you make or distribute.  However,
4619
     you may accept compensation in exchange for copies.  If you
4620
     distribute a large enough number of copies you must also follow
4621
     the conditions in section 3.
4622
 
4623
     You may also lend copies, under the same conditions stated above,
4624
     and you may publicly display copies.
4625
 
4626
  3. COPYING IN QUANTITY
4627
 
4628
     If you publish printed copies (or copies in media that commonly
4629
     have printed covers) of the Document, numbering more than 100, and
4630
     the Document's license notice requires Cover Texts, you must
4631
     enclose the copies in covers that carry, clearly and legibly, all
4632
     these Cover Texts: Front-Cover Texts on the front cover, and
4633
     Back-Cover Texts on the back cover.  Both covers must also clearly
4634
     and legibly identify you as the publisher of these copies.  The
4635
     front cover must present the full title with all words of the
4636
     title equally prominent and visible.  You may add other material
4637
     on the covers in addition.  Copying with changes limited to the
4638
     covers, as long as they preserve the title of the Document and
4639
     satisfy these conditions, can be treated as verbatim copying in
4640
     other respects.
4641
 
4642
     If the required texts for either cover are too voluminous to fit
4643
     legibly, you should put the first ones listed (as many as fit
4644
     reasonably) on the actual cover, and continue the rest onto
4645
     adjacent pages.
4646
 
4647
     If you publish or distribute Opaque copies of the Document
4648
     numbering more than 100, you must either include a
4649
     machine-readable Transparent copy along with each Opaque copy, or
4650
     state in or with each Opaque copy a computer-network location from
4651
     which the general network-using public has access to download
4652
     using public-standard network protocols a complete Transparent
4653
     copy of the Document, free of added material.  If you use the
4654
     latter option, you must take reasonably prudent steps, when you
4655
     begin distribution of Opaque copies in quantity, to ensure that
4656
     this Transparent copy will remain thus accessible at the stated
4657
     location until at least one year after the last time you
4658
     distribute an Opaque copy (directly or through your agents or
4659
     retailers) of that edition to the public.
4660
 
4661
     It is requested, but not required, that you contact the authors of
4662
     the Document well before redistributing any large number of
4663
     copies, to give them a chance to provide you with an updated
4664
     version of the Document.
4665
 
4666
  4. MODIFICATIONS
4667
 
4668
     You may copy and distribute a Modified Version of the Document
4669
     under the conditions of sections 2 and 3 above, provided that you
4670
     release the Modified Version under precisely this License, with
4671
     the Modified Version filling the role of the Document, thus
4672
     licensing distribution and modification of the Modified Version to
4673
     whoever possesses a copy of it.  In addition, you must do these
4674
     things in the Modified Version:
4675
 
4676
       A. Use in the Title Page (and on the covers, if any) a title
4677
          distinct from that of the Document, and from those of
4678
          previous versions (which should, if there were any, be listed
4679
          in the History section of the Document).  You may use the
4680
          same title as a previous version if the original publisher of
4681
          that version gives permission.
4682
 
4683
       B. List on the Title Page, as authors, one or more persons or
4684
          entities responsible for authorship of the modifications in
4685
          the Modified Version, together with at least five of the
4686
          principal authors of the Document (all of its principal
4687
          authors, if it has fewer than five), unless they release you
4688
          from this requirement.
4689
 
4690
       C. State on the Title page the name of the publisher of the
4691
          Modified Version, as the publisher.
4692
 
4693
       D. Preserve all the copyright notices of the Document.
4694
 
4695
       E. Add an appropriate copyright notice for your modifications
4696
          adjacent to the other copyright notices.
4697
 
4698
       F. Include, immediately after the copyright notices, a license
4699
          notice giving the public permission to use the Modified
4700
          Version under the terms of this License, in the form shown in
4701
          the Addendum below.
4702
 
4703
       G. Preserve in that license notice the full lists of Invariant
4704
          Sections and required Cover Texts given in the Document's
4705
          license notice.
4706
 
4707
       H. Include an unaltered copy of this License.
4708
 
4709
       I. Preserve the section Entitled "History", Preserve its Title,
4710
          and add to it an item stating at least the title, year, new
4711
          authors, and publisher of the Modified Version as given on
4712
          the Title Page.  If there is no section Entitled "History" in
4713
          the Document, create one stating the title, year, authors,
4714
          and publisher of the Document as given on its Title Page,
4715
          then add an item describing the Modified Version as stated in
4716
          the previous sentence.
4717
 
4718
       J. Preserve the network location, if any, given in the Document
4719
          for public access to a Transparent copy of the Document, and
4720
          likewise the network locations given in the Document for
4721
          previous versions it was based on.  These may be placed in
4722
          the "History" section.  You may omit a network location for a
4723
          work that was published at least four years before the
4724
          Document itself, or if the original publisher of the version
4725
          it refers to gives permission.
4726
 
4727
       K. For any section Entitled "Acknowledgements" or "Dedications",
4728
          Preserve the Title of the section, and preserve in the
4729
          section all the substance and tone of each of the contributor
4730
          acknowledgements and/or dedications given therein.
4731
 
4732
       L. Preserve all the Invariant Sections of the Document,
4733
          unaltered in their text and in their titles.  Section numbers
4734
          or the equivalent are not considered part of the section
4735
          titles.
4736
 
4737
       M. Delete any section Entitled "Endorsements".  Such a section
4738
          may not be included in the Modified Version.
4739
 
4740
       N. Do not retitle any existing section to be Entitled
4741
          "Endorsements" or to conflict in title with any Invariant
4742
          Section.
4743
 
4744
       O. Preserve any Warranty Disclaimers.
4745
 
4746
     If the Modified Version includes new front-matter sections or
4747
     appendices that qualify as Secondary Sections and contain no
4748
     material copied from the Document, you may at your option
4749
     designate some or all of these sections as invariant.  To do this,
4750
     add their titles to the list of Invariant Sections in the Modified
4751
     Version's license notice.  These titles must be distinct from any
4752
     other section titles.
4753
 
4754
     You may add a section Entitled "Endorsements", provided it contains
4755
     nothing but endorsements of your Modified Version by various
4756
     parties--for example, statements of peer review or that the text
4757
     has been approved by an organization as the authoritative
4758
     definition of a standard.
4759
 
4760
     You may add a passage of up to five words as a Front-Cover Text,
4761
     and a passage of up to 25 words as a Back-Cover Text, to the end
4762
     of the list of Cover Texts in the Modified Version.  Only one
4763
     passage of Front-Cover Text and one of Back-Cover Text may be
4764
     added by (or through arrangements made by) any one entity.  If the
4765
     Document already includes a cover text for the same cover,
4766
     previously added by you or by arrangement made by the same entity
4767
     you are acting on behalf of, you may not add another; but you may
4768
     replace the old one, on explicit permission from the previous
4769
     publisher that added the old one.
4770
 
4771
     The author(s) and publisher(s) of the Document do not by this
4772
     License give permission to use their names for publicity for or to
4773
     assert or imply endorsement of any Modified Version.
4774
 
4775
  5. COMBINING DOCUMENTS
4776
 
4777
     You may combine the Document with other documents released under
4778
     this License, under the terms defined in section 4 above for
4779
     modified versions, provided that you include in the combination
4780
     all of the Invariant Sections of all of the original documents,
4781
     unmodified, and list them all as Invariant Sections of your
4782
     combined work in its license notice, and that you preserve all
4783
     their Warranty Disclaimers.
4784
 
4785
     The combined work need only contain one copy of this License, and
4786
     multiple identical Invariant Sections may be replaced with a single
4787
     copy.  If there are multiple Invariant Sections with the same name
4788
     but different contents, make the title of each such section unique
4789
     by adding at the end of it, in parentheses, the name of the
4790
     original author or publisher of that section if known, or else a
4791
     unique number.  Make the same adjustment to the section titles in
4792
     the list of Invariant Sections in the license notice of the
4793
     combined work.
4794
 
4795
     In the combination, you must combine any sections Entitled
4796
     "History" in the various original documents, forming one section
4797
     Entitled "History"; likewise combine any sections Entitled
4798
     "Acknowledgements", and any sections Entitled "Dedications".  You
4799
     must delete all sections Entitled "Endorsements."
4800
 
4801
  6. COLLECTIONS OF DOCUMENTS
4802
 
4803
     You may make a collection consisting of the Document and other
4804
     documents released under this License, and replace the individual
4805
     copies of this License in the various documents with a single copy
4806
     that is included in the collection, provided that you follow the
4807
     rules of this License for verbatim copying of each of the
4808
     documents in all other respects.
4809
 
4810
     You may extract a single document from such a collection, and
4811
     distribute it individually under this License, provided you insert
4812
     a copy of this License into the extracted document, and follow
4813
     this License in all other respects regarding verbatim copying of
4814
     that document.
4815
 
4816
  7. AGGREGATION WITH INDEPENDENT WORKS
4817
 
4818
     A compilation of the Document or its derivatives with other
4819
     separate and independent documents or works, in or on a volume of
4820
     a storage or distribution medium, is called an "aggregate" if the
4821
     copyright resulting from the compilation is not used to limit the
4822
     legal rights of the compilation's users beyond what the individual
4823
     works permit.  When the Document is included in an aggregate, this
4824
     License does not apply to the other works in the aggregate which
4825
     are not themselves derivative works of the Document.
4826
 
4827
     If the Cover Text requirement of section 3 is applicable to these
4828
     copies of the Document, then if the Document is less than one half
4829
     of the entire aggregate, the Document's Cover Texts may be placed
4830
     on covers that bracket the Document within the aggregate, or the
4831
     electronic equivalent of covers if the Document is in electronic
4832
     form.  Otherwise they must appear on printed covers that bracket
4833
     the whole aggregate.
4834
 
4835
  8. TRANSLATION
4836
 
4837
     Translation is considered a kind of modification, so you may
4838
     distribute translations of the Document under the terms of section
4839
     4.  Replacing Invariant Sections with translations requires special
4840
     permission from their copyright holders, but you may include
4841
     translations of some or all Invariant Sections in addition to the
4842
     original versions of these Invariant Sections.  You may include a
4843
     translation of this License, and all the license notices in the
4844
     Document, and any Warranty Disclaimers, provided that you also
4845
     include the original English version of this License and the
4846
     original versions of those notices and disclaimers.  In case of a
4847
     disagreement between the translation and the original version of
4848
     this License or a notice or disclaimer, the original version will
4849
     prevail.
4850
 
4851
     If a section in the Document is Entitled "Acknowledgements",
4852
     "Dedications", or "History", the requirement (section 4) to
4853
     Preserve its Title (section 1) will typically require changing the
4854
     actual title.
4855
 
4856
  9. TERMINATION
4857
 
4858
     You may not copy, modify, sublicense, or distribute the Document
4859
     except as expressly provided for under this License.  Any other
4860
     attempt to copy, modify, sublicense or distribute the Document is
4861
     void, and will automatically terminate your rights under this
4862
     License.  However, parties who have received copies, or rights,
4863
     from you under this License will not have their licenses
4864
     terminated so long as such parties remain in full compliance.
4865
 
4866
 10. FUTURE REVISIONS OF THIS LICENSE
4867
 
4868
     The Free Software Foundation may publish new, revised versions of
4869
     the GNU Free Documentation License from time to time.  Such new
4870
     versions will be similar in spirit to the present version, but may
4871
     differ in detail to address new problems or concerns.  See
4872
     `http://www.gnu.org/copyleft/'.
4873
 
4874
     Each version of the License is given a distinguishing version
4875
     number.  If the Document specifies that a particular numbered
4876
     version of this License "or any later version" applies to it, you
4877
     have the option of following the terms and conditions either of
4878
     that specified version or of any later version that has been
4879
     published (not as a draft) by the Free Software Foundation.  If
4880
     the Document does not specify a version number of this License,
4881
     you may choose any version ever published (not as a draft) by the
4882
     Free Software Foundation.
4883
 
4884
ADDENDUM: How to use this License for your documents
4885
====================================================
4886
 
4887
To use this License in a document you have written, include a copy of
4888
the License in the document and put the following copyright and license
4889
notices just after the title page:
4890
 
4891
       Copyright (C)  YEAR  YOUR NAME.
4892
       Permission is granted to copy, distribute and/or modify this document
4893
       under the terms of the GNU Free Documentation License, Version 1.2
4894
       or any later version published by the Free Software Foundation;
4895
       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
4896
       Texts.  A copy of the license is included in the section entitled ``GNU
4897
       Free Documentation License''.
4898
 
4899
   If you have Invariant Sections, Front-Cover Texts and Back-Cover
4900
Texts, replace the "with...Texts." line with this:
4901
 
4902
         with the Invariant Sections being LIST THEIR TITLES, with
4903
         the Front-Cover Texts being LIST, and with the Back-Cover Texts
4904
         being LIST.
4905
 
4906
   If you have Invariant Sections without Cover Texts, or some other
4907
combination of the three, merge those two alternatives to suit the
4908
situation.
4909
 
4910
   If your document contains nontrivial examples of program code, we
4911
recommend releasing these examples in parallel under your choice of
4912
free software license, such as the GNU General Public License, to
4913
permit their use in free software.
4914
 
4915

4916
File: cpp.info,  Node: Index of Directives,  Next: Option Index,  Prev: GNU Free Documentation License,  Up: Top
4917
 
4918
Index of Directives
4919
*******************
4920
 
4921
 
4922
* Menu:
4923
4924
* #assert:                               Assertions.           (line 41)
4925
* #define:                               Object-like Macros.   (line 11)
4926
* #elif:                                 Elif.                 (line  6)
4927
* #else:                                 Else.                 (line  6)
4928
* #endif:                                Ifdef.                (line  6)
4929
* #error:                                Diagnostics.          (line  6)
4930
* #ident:                                Other Directives.     (line  6)
4931
* #if:                                   Conditional Syntax.   (line  6)
4932
* #ifdef:                                Ifdef.                (line  6)
4933
* #ifndef:                               Ifdef.                (line 40)
4934
* #import:                               Obsolete once-only headers.
4935
                                                               (line 10)
4936
* #include:                              Include Syntax.       (line  6)
4937
* #include_next:                         Wrapper Headers.      (line  6)
4938
* #line:                                 Line Control.         (line 20)
4939
* #pragma GCC dependency:                Pragmas.              (line 53)
4940
* #pragma GCC poison:                    Pragmas.              (line 65)
4941
* #pragma GCC system_header <1>:         Pragmas.              (line 92)
4942
* #pragma GCC system_header:             System Headers.       (line 31)
4943
* #sccs:                                 Other Directives.     (line  6)
4944
* #unassert:                             Assertions.           (line 52)
4945
 
4946
                                                               (line  6)
4947
* #warning:                              Diagnostics.          (line 27)
4948
 
4949

4950
File: cpp.info,  Node: Option Index,  Next: Concept Index,  Prev: Index of Directives,  Up: Top
4951
 
4952
Option Index
4953
************
4954
 
4955
 
4956
without any initial `-' or `--'.
4957
4958
[index]
4959
* Menu:
4960
4961
* A:                                     Invocation.          (line 494)
4962
* ansi:                                  Invocation.          (line 307)
4963
* C:                                     Invocation.          (line 542)
4964
* C_INCLUDE_PATH:                        Environment Variables.
4965
                                                              (line  16)
4966
* CPATH:                                 Environment Variables.
4967
                                                              (line  15)
4968
* CPLUS_INCLUDE_PATH:                    Environment Variables.
4969
                                                              (line  17)
4970
* D:                                     Invocation.          (line  39)
4971
* dD:                                    Invocation.          (line 522)
4972
* DEPENDENCIES_OUTPUT:                   Environment Variables.
4973
                                                              (line  44)
4974
* dI:                                    Invocation.          (line 531)
4975
* dM:                                    Invocation.          (line 510)
4976
* dN:                                    Invocation.          (line 528)
4977
* fdollars-in-identifiers:               Invocation.          (line 424)
4978
* fexec-charset:                         Invocation.          (line 451)
4979
* fextended-identifiers:                 Invocation.          (line 427)
4980
* finput-charset:                        Invocation.          (line 464)
4981
* fno-show-column:                       Invocation.          (line 489)
4982
* fno-working-directory:                 Invocation.          (line 474)
4983
* fpreprocessed:                         Invocation.          (line 432)
4984
* ftabstop:                              Invocation.          (line 445)
4985
* fwide-exec-charset:                    Invocation.          (line 456)
4986
* fworking-directory:                    Invocation.          (line 474)
4987
* H:                                     Invocation.          (line 587)
4988
* help:                                  Invocation.          (line 579)
4989
* I:                                     Invocation.          (line  71)
4990
* I-:                                    Invocation.          (line 344)
4991
* idirafter:                             Invocation.          (line 386)
4992
* imacros:                               Invocation.          (line 377)
4993
* imultilib:                             Invocation.          (line 407)
4994
* include:                               Invocation.          (line 366)
4995
* iprefix:                               Invocation.          (line 391)
4996
* iquote:                                Invocation.          (line 418)
4997
* isysroot:                              Invocation.          (line 403)
4998
* isystem:                               Invocation.          (line 411)
4999
* iwithprefix:                           Invocation.          (line 397)
5000
* iwithprefixbefore:                     Invocation.          (line 397)
5001
* M:                                     Invocation.          (line 181)
5002
* MD:                                    Invocation.          (line 269)
5003
* MF:                                    Invocation.          (line 215)
5004
* MG:                                    Invocation.          (line 224)
5005
* MM:                                    Invocation.          (line 205)
5006
* MMD:                                   Invocation.          (line 284)
5007
* MP:                                    Invocation.          (line 234)
5008
* MQ:                                    Invocation.          (line 260)
5009
* MT:                                    Invocation.          (line 246)
5010
* nostdinc:                              Invocation.          (line 356)
5011
* nostdinc++:                            Invocation.          (line 361)
5012
* o:                                     Invocation.          (line  80)
5013
* OBJC_INCLUDE_PATH:                     Environment Variables.
5014
                                                              (line  18)
5015
* P:                                     Invocation.          (line 535)
5016
* pedantic:                              Invocation.          (line 171)
5017
* pedantic-errors:                       Invocation.          (line 176)
5018
* remap:                                 Invocation.          (line 574)
5019
* std=:                                  Invocation.          (line 307)
5020
* SUNPRO_DEPENDENCIES:                   Environment Variables.
5021
                                                              (line  60)
5022
* target-help:                           Invocation.          (line 579)
5023
* traditional-cpp:                       Invocation.          (line 567)
5024
* trigraphs:                             Invocation.          (line 571)
5025
* U:                                     Invocation.          (line  62)
5026
* undef:                                 Invocation.          (line  66)
5027
* v:                                     Invocation.          (line 583)
5028
* version:                               Invocation.          (line 596)
5029
* w:                                     Invocation.          (line 167)
5030
* Wall:                                  Invocation.          (line  86)
5031
* Wcomment:                              Invocation.          (line  94)
5032
* Wcomments:                             Invocation.          (line  94)
5033
* Wendif-labels:                         Invocation.          (line 144)
5034
* Werror:                                Invocation.          (line 157)
5035
* Wimport:                               Invocation.          (line 117)
5036
 
5037
* Wtraditional:                          Invocation.          (line 111)
5038
* Wtrigraphs:                            Invocation.          (line  99)
5039
 
5040
* Wunused-macros:                        Invocation.          (line 125)
5041
* x:                                     Invocation.          (line 291)
5042
 
5043
 
5044
File: cpp.info,  Node: Concept Index,  Prev: Option Index,  Up: Top
5045
5046
Concept Index
5047
*************
5048
5049
[index]
5050
* Menu:
5051
5052
* # operator:                            Stringification.     (line   6)
5053
* ## operator:                           Concatenation.       (line   6)
5054
* _Pragma:                               Pragmas.             (line  25)
5055
* alternative tokens:                    Tokenization.        (line 106)
5056
* arguments:                             Macro Arguments.     (line   6)
5057
* arguments in macro definitions:        Macro Arguments.     (line   6)
5058
* assertions:                            Assertions.          (line   6)
5059
* assertions, canceling:                 Assertions.          (line  52)
5060
* backslash-newline:                     Initial processing.  (line  61)
5061
* block comments:                        Initial processing.  (line  77)
5062
* C++ named operators:                   C++ Named Operators. (line   6)
5063
* character constants:                   Tokenization.        (line  85)
5064
* character set, execution:              Invocation.          (line 451)
5065
* character set, input:                  Invocation.          (line 464)
5066
* character set, wide execution:         Invocation.          (line 456)
5067
* command line:                          Invocation.          (line   6)
5068
* commenting out code:                   Deleted Code.        (line   6)
5069
* comments:                              Initial processing.  (line  77)
5070
* common predefined macros:              Common Predefined Macros.
5071
                                                              (line   6)
5072
* computed includes:                     Computed Includes.   (line   6)
5073
* concatenation:                         Concatenation.       (line   6)
5074
* conditional group:                     Ifdef.               (line  14)
5075
* conditionals:                          Conditionals.        (line   6)
5076
* continued lines:                       Initial processing.  (line  61)
5077
* controlling macro:                     Once-Only Headers.   (line  35)
5078
* defined:                               Defined.             (line   6)
5079
* dependencies for make as output:       Environment Variables.
5080
                                                              (line  45)
5081
* dependencies, make:                    Invocation.          (line 181)
5082
* diagnostic:                            Diagnostics.         (line   6)
5083
* differences from previous versions:    Differences from previous versions.
5084
                                                              (line   6)
5085
* digraphs:                              Tokenization.        (line 106)
5086
* directive line:                        The preprocessing language.
5087
                                                              (line   6)
5088
* directive name:                        The preprocessing language.
5089
                                                              (line   6)
5090
* directives:                            The preprocessing language.
5091
                                                              (line   6)
5092
* empty macro arguments:                 Macro Arguments.     (line  66)
5093
* environment variables:                 Environment Variables.
5094
                                                              (line   6)
5095
* expansion of arguments:                Argument Prescan.    (line   6)
5096
* FDL, GNU Free Documentation License:   GNU Free Documentation License.
5097
                                                              (line   6)
5098
* function-like macros:                  Function-like Macros.
5099
                                                              (line   6)
5100
* grouping options:                      Invocation.          (line  34)
5101
* guard macro:                           Once-Only Headers.   (line  35)
5102
* header file:                           Header Files.        (line   6)
5103
* header file names:                     Tokenization.        (line  85)
5104
* identifiers:                           Tokenization.        (line  34)
5105
* implementation limits:                 Implementation limits.
5106
                                                              (line   6)
5107
* implementation-defined behavior:       Implementation-defined behavior.
5108
                                                              (line   6)
5109
* including just once:                   Once-Only Headers.   (line   6)
5110
* invocation:                            Invocation.          (line   6)
5111
* iso646.h:                              C++ Named Operators. (line   6)
5112
* line comments:                         Initial processing.  (line  77)
5113
* line control:                          Line Control.        (line   6)
5114
* line endings:                          Initial processing.  (line  14)
5115
* linemarkers:                           Preprocessor Output. (line  28)
5116
* macro argument expansion:              Argument Prescan.    (line   6)
5117
* macro arguments and directives:        Directives Within Macro Arguments.
5118
                                                              (line   6)
5119
* macros in include:                     Computed Includes.   (line   6)
5120
* macros with arguments:                 Macro Arguments.     (line   6)
5121
* macros with variable arguments:        Variadic Macros.     (line   6)
5122
* make:                                  Invocation.          (line 181)
5123
* manifest constants:                    Object-like Macros.  (line   6)
5124
* named operators:                       C++ Named Operators. (line   6)
5125
* newlines in macro arguments:           Newlines in Arguments.
5126
                                                              (line   6)
5127
* null directive:                        Other Directives.    (line  15)
5128
* numbers:                               Tokenization.        (line  61)
5129
* object-like macro:                     Object-like Macros.  (line   6)
5130
* options:                               Invocation.          (line  38)
5131
* options, grouping:                     Invocation.          (line  34)
5132
* other tokens:                          Tokenization.        (line 120)
5133
* output format:                         Preprocessor Output. (line  12)
5134
* overriding a header file:              Wrapper Headers.     (line   6)
5135
* parentheses in macro bodies:           Operator Precedence Problems.
5136
                                                              (line   6)
5137
* pitfalls of macros:                    Macro Pitfalls.      (line   6)
5138
* predefined macros:                     Predefined Macros.   (line   6)
5139
* predefined macros, system-specific:    System-specific Predefined Macros.
5140
                                                              (line   6)
5141
* predicates:                            Assertions.          (line  19)
5142
* preprocessing directives:              The preprocessing language.
5143
                                                              (line   6)
5144
* preprocessing numbers:                 Tokenization.        (line  61)
5145
* preprocessing tokens:                  Tokenization.        (line   6)
5146
* prescan of macro arguments:            Argument Prescan.    (line   6)
5147
* problems with macros:                  Macro Pitfalls.      (line   6)
5148
* punctuators:                           Tokenization.        (line 106)
5149
* redefining macros:                     Undefining and Redefining Macros.
5150
                                                              (line   6)
5151
* repeated inclusion:                    Once-Only Headers.   (line   6)
5152
* reporting errors:                      Diagnostics.         (line   6)
5153
* reporting warnings:                    Diagnostics.         (line   6)
5154
* reserved namespace:                    System-specific Predefined Macros.
5155
                                                              (line   6)
5156
* self-reference:                        Self-Referential Macros.
5157
                                                              (line   6)
5158
* semicolons (after macro calls):        Swallowing the Semicolon.
5159
                                                              (line   6)
5160
* side effects (in macro arguments):     Duplication of Side Effects.
5161
                                                              (line   6)
5162
* standard predefined macros.:           Standard Predefined Macros.
5163
                                                              (line   6)
5164
* string constants:                      Tokenization.        (line  85)
5165
* string literals:                       Tokenization.        (line  85)
5166
* stringification:                       Stringification.     (line   6)
5167
* symbolic constants:                    Object-like Macros.  (line   6)
5168
* system header files <1>:               System Headers.      (line   6)
5169
* system header files:                   Header Files.        (line  13)
5170
* system-specific predefined macros:     System-specific Predefined Macros.
5171
                                                              (line   6)
5172
* testing predicates:                    Assertions.          (line  30)
5173
* token concatenation:                   Concatenation.       (line   6)
5174
* token pasting:                         Concatenation.       (line   6)
5175
* tokens:                                Tokenization.        (line   6)
5176
 
5177
 
5178
                                                              (line   6)
5179
* unsafe macros:                         Duplication of Side Effects.
5180
                                                              (line   6)
5181
* variable number of arguments:          Variadic Macros.     (line   6)
5182
* variadic macros:                       Variadic Macros.     (line   6)
5183
* wrapper #ifndef:                       Once-Only Headers.   (line   6)
5184
* wrapper headers:                       Wrapper Headers.     (line   6)
5185
5186
5187

5188
Tag Table:
5189
Node: Top1094
5190
Node: Overview3778
5191
Node: Character sets6599
5192
Ref: Character sets-Footnote-18782
5193
Node: Initial processing8963
5194
Ref: trigraphs10522
5195
Node: Tokenization14724
5196
Ref: Tokenization-Footnote-121860
5197
Node: The preprocessing language21971
5198
Node: Header Files24849
5199
Node: Include Syntax26729
5200
Node: Include Operation28366
5201
Node: Search Path30214
5202
Node: Once-Only Headers33404
5203
Node: Computed Includes35049
5204
Node: Wrapper Headers38193
5205
Node: System Headers40619
5206
Node: Macros42669
5207
Node: Object-like Macros43810
5208
Node: Function-like Macros47400
5209
Node: Macro Arguments49016
5210
Node: Stringification53161
5211
Node: Concatenation56367
5212
Node: Variadic Macros59475
5213
Node: Predefined Macros64262
5214
Node: Standard Predefined Macros64850
5215
Node: Common Predefined Macros70786
5216
Node: System-specific Predefined Macros81678
5217
Node: C++ Named Operators83699
5218
Node: Undefining and Redefining Macros84663
5219
Node: Directives Within Macro Arguments86767
5220
Node: Macro Pitfalls88315
5221
Node: Misnesting88848
5222
Node: Operator Precedence Problems89960
5223
Node: Swallowing the Semicolon91826
5224
Node: Duplication of Side Effects93849
5225
Node: Self-Referential Macros96032
5226
Node: Argument Prescan98441
5227
Node: Newlines in Arguments102195
5228
Node: Conditionals103146
5229
Node: Conditional Uses104976
5230
Node: Conditional Syntax106334
5231
Node: Ifdef106654
5232
Node: If109815
5233
Node: Defined112119
5234
Node: Else113402
5235
Node: Elif113972
5236
Node: Deleted Code115261
5237
Node: Diagnostics116508
5238
Node: Line Control118125
5239
Node: Pragmas121929
5240
Node: Other Directives126199
5241
Node: Preprocessor Output127249
5242
Node: Traditional Mode130450
5243
Node: Traditional lexical analysis131508
5244
Node: Traditional macros134011
5245
Node: Traditional miscellany137813
5246
Node: Traditional warnings138810
5247
Node: Implementation Details141007
5248
Node: Implementation-defined behavior141628
5249
Ref: Identifier characters142361
5250
Node: Implementation limits145446
5251
Node: Obsolete Features148120
5252
Node: Assertions148575
5253
Node: Obsolete once-only headers151116
5254
Node: Differences from previous versions152851
5255
Node: Invocation157059
5256
Ref: Wtrigraphs161390

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.