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