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