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

Subversion Repositories openrisc

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

Details | Compare with Previous | View Log

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

powered by: WebSVN 2.1.0

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