1 | This is Info file cpp.info, produced by Makeinfo-1.55 from the input |
---|
2 | file cpp.texi. |
---|
3 | |
---|
4 | This file documents the GNU C Preprocessor. |
---|
5 | |
---|
6 | Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995 Free Software |
---|
7 | Foundation, Inc. |
---|
8 | |
---|
9 | Permission is granted to make and distribute verbatim copies of this |
---|
10 | manual provided the copyright notice and this permission notice are |
---|
11 | preserved on all copies. |
---|
12 | |
---|
13 | Permission is granted to copy and distribute modified versions of |
---|
14 | this manual under the conditions for verbatim copying, provided also |
---|
15 | that the entire resulting derived work is distributed under the terms |
---|
16 | of a permission notice identical to this one. |
---|
17 | |
---|
18 | Permission is granted to copy and distribute translations of this |
---|
19 | manual into another language, under the above conditions for modified |
---|
20 | versions. |
---|
21 | |
---|
22 | |
---|
23 | File: cpp.info, Node: Misnesting, Next: Macro Parentheses, Prev: Macro Pitfalls, Up: Macro Pitfalls |
---|
24 | |
---|
25 | Improperly Nested Constructs |
---|
26 | ............................ |
---|
27 | |
---|
28 | Recall that when a macro is called with arguments, the arguments are |
---|
29 | substituted into the macro body and the result is checked, together with |
---|
30 | the rest of the input file, for more macro calls. |
---|
31 | |
---|
32 | It is possible to piece together a macro call coming partially from |
---|
33 | the macro body and partially from the actual arguments. For example, |
---|
34 | |
---|
35 | #define double(x) (2*(x)) |
---|
36 | #define call_with_1(x) x(1) |
---|
37 | |
---|
38 | would expand `call_with_1 (double)' into `(2*(1))'. |
---|
39 | |
---|
40 | Macro definitions do not have to have balanced parentheses. By |
---|
41 | writing an unbalanced open parenthesis in a macro body, it is possible |
---|
42 | to create a macro call that begins inside the macro body but ends |
---|
43 | outside of it. For example, |
---|
44 | |
---|
45 | #define strange(file) fprintf (file, "%s %d", |
---|
46 | ... |
---|
47 | strange(stderr) p, 35) |
---|
48 | |
---|
49 | This bizarre example expands to `fprintf (stderr, "%s %d", p, 35)'! |
---|
50 | |
---|
51 | |
---|
52 | File: cpp.info, Node: Macro Parentheses, Next: Swallow Semicolon, Prev: Misnesting, Up: Macro Pitfalls |
---|
53 | |
---|
54 | Unintended Grouping of Arithmetic |
---|
55 | ................................. |
---|
56 | |
---|
57 | You may have noticed that in most of the macro definition examples |
---|
58 | shown above, each occurrence of a macro argument name had parentheses |
---|
59 | around it. In addition, another pair of parentheses usually surround |
---|
60 | the entire macro definition. Here is why it is best to write macros |
---|
61 | that way. |
---|
62 | |
---|
63 | Suppose you define a macro as follows, |
---|
64 | |
---|
65 | #define ceil_div(x, y) (x + y - 1) / y |
---|
66 | |
---|
67 | whose purpose is to divide, rounding up. (One use for this operation is |
---|
68 | to compute how many `int' objects are needed to hold a certain number |
---|
69 | of `char' objects.) Then suppose it is used as follows: |
---|
70 | |
---|
71 | a = ceil_div (b & c, sizeof (int)); |
---|
72 | |
---|
73 | This expands into |
---|
74 | |
---|
75 | a = (b & c + sizeof (int) - 1) / sizeof (int); |
---|
76 | |
---|
77 | which does not do what is intended. The operator-precedence rules of C |
---|
78 | make it equivalent to this: |
---|
79 | |
---|
80 | a = (b & (c + sizeof (int) - 1)) / sizeof (int); |
---|
81 | |
---|
82 | But what we want is this: |
---|
83 | |
---|
84 | a = ((b & c) + sizeof (int) - 1)) / sizeof (int); |
---|
85 | |
---|
86 | Defining the macro as |
---|
87 | |
---|
88 | #define ceil_div(x, y) ((x) + (y) - 1) / (y) |
---|
89 | |
---|
90 | provides the desired result. |
---|
91 | |
---|
92 | However, unintended grouping can result in another way. Consider |
---|
93 | `sizeof ceil_div(1, 2)'. That has the appearance of a C expression |
---|
94 | that would compute the size of the type of `ceil_div (1, 2)', but in |
---|
95 | fact it means something very different. Here is what it expands to: |
---|
96 | |
---|
97 | sizeof ((1) + (2) - 1) / (2) |
---|
98 | |
---|
99 | This would take the size of an integer and divide it by two. The |
---|
100 | precedence rules have put the division outside the `sizeof' when it was |
---|
101 | intended to be inside. |
---|
102 | |
---|
103 | Parentheses around the entire macro definition can prevent such |
---|
104 | problems. Here, then, is the recommended way to define `ceil_div': |
---|
105 | |
---|
106 | #define ceil_div(x, y) (((x) + (y) - 1) / (y)) |
---|
107 | |
---|
108 | |
---|
109 | File: cpp.info, Node: Swallow Semicolon, Next: Side Effects, Prev: Macro Parentheses, Up: Macro Pitfalls |
---|
110 | |
---|
111 | Swallowing the Semicolon |
---|
112 | ........................ |
---|
113 | |
---|
114 | Often it is desirable to define a macro that expands into a compound |
---|
115 | statement. Consider, for example, the following macro, that advances a |
---|
116 | pointer (the argument `p' says where to find it) across whitespace |
---|
117 | characters: |
---|
118 | |
---|
119 | #define SKIP_SPACES (p, limit) \ |
---|
120 | { register char *lim = (limit); \ |
---|
121 | while (p != lim) { \ |
---|
122 | if (*p++ != ' ') { \ |
---|
123 | p--; break; }}} |
---|
124 | |
---|
125 | Here Backslash-Newline is used to split the macro definition, which must |
---|
126 | be a single line, so that it resembles the way such C code would be |
---|
127 | laid out if not part of a macro definition. |
---|
128 | |
---|
129 | A call to this macro might be `SKIP_SPACES (p, lim)'. Strictly |
---|
130 | speaking, the call expands to a compound statement, which is a complete |
---|
131 | statement with no need for a semicolon to end it. But it looks like a |
---|
132 | function call. So it minimizes confusion if you can use it like a |
---|
133 | function call, writing a semicolon afterward, as in `SKIP_SPACES (p, |
---|
134 | lim);' |
---|
135 | |
---|
136 | But this can cause trouble before `else' statements, because the |
---|
137 | semicolon is actually a null statement. Suppose you write |
---|
138 | |
---|
139 | if (*p != 0) |
---|
140 | SKIP_SPACES (p, lim); |
---|
141 | else ... |
---|
142 | |
---|
143 | The presence of two statements--the compound statement and a null |
---|
144 | statement--in between the `if' condition and the `else' makes invalid C |
---|
145 | code. |
---|
146 | |
---|
147 | The definition of the macro `SKIP_SPACES' can be altered to solve |
---|
148 | this problem, using a `do ... while' statement. Here is how: |
---|
149 | |
---|
150 | #define SKIP_SPACES (p, limit) \ |
---|
151 | do { register char *lim = (limit); \ |
---|
152 | while (p != lim) { \ |
---|
153 | if (*p++ != ' ') { \ |
---|
154 | p--; break; }}} \ |
---|
155 | while (0) |
---|
156 | |
---|
157 | Now `SKIP_SPACES (p, lim);' expands into |
---|
158 | |
---|
159 | do {...} while (0); |
---|
160 | |
---|
161 | which is one statement. |
---|
162 | |
---|
163 | |
---|
164 | File: cpp.info, Node: Side Effects, Next: Self-Reference, Prev: Swallow Semicolon, Up: Macro Pitfalls |
---|
165 | |
---|
166 | Duplication of Side Effects |
---|
167 | ........................... |
---|
168 | |
---|
169 | Many C programs define a macro `min', for "minimum", like this: |
---|
170 | |
---|
171 | #define min(X, Y) ((X) < (Y) ? (X) : (Y)) |
---|
172 | |
---|
173 | When you use this macro with an argument containing a side effect, |
---|
174 | as shown here, |
---|
175 | |
---|
176 | next = min (x + y, foo (z)); |
---|
177 | |
---|
178 | it expands as follows: |
---|
179 | |
---|
180 | next = ((x + y) < (foo (z)) ? (x + y) : (foo (z))); |
---|
181 | |
---|
182 | where `x + y' has been substituted for `X' and `foo (z)' for `Y'. |
---|
183 | |
---|
184 | The function `foo' is used only once in the statement as it appears |
---|
185 | in the program, but the expression `foo (z)' has been substituted twice |
---|
186 | into the macro expansion. As a result, `foo' might be called two times |
---|
187 | when the statement is executed. If it has side effects or if it takes |
---|
188 | a long time to compute, the results might not be what you intended. We |
---|
189 | say that `min' is an "unsafe" macro. |
---|
190 | |
---|
191 | The best solution to this problem is to define `min' in a way that |
---|
192 | computes the value of `foo (z)' only once. The C language offers no |
---|
193 | standard way to do this, but it can be done with GNU C extensions as |
---|
194 | follows: |
---|
195 | |
---|
196 | #define min(X, Y) \ |
---|
197 | ({ typeof (X) __x = (X), __y = (Y); \ |
---|
198 | (__x < __y) ? __x : __y; }) |
---|
199 | |
---|
200 | If you do not wish to use GNU C extensions, the only solution is to |
---|
201 | be careful when *using* the macro `min'. For example, you can |
---|
202 | calculate the value of `foo (z)', save it in a variable, and use that |
---|
203 | variable in `min': |
---|
204 | |
---|
205 | #define min(X, Y) ((X) < (Y) ? (X) : (Y)) |
---|
206 | ... |
---|
207 | { |
---|
208 | int tem = foo (z); |
---|
209 | next = min (x + y, tem); |
---|
210 | } |
---|
211 | |
---|
212 | (where we assume that `foo' returns type `int'). |
---|
213 | |
---|
214 | |
---|
215 | File: cpp.info, Node: Self-Reference, Next: Argument Prescan, Prev: Side Effects, Up: Macro Pitfalls |
---|
216 | |
---|
217 | Self-Referential Macros |
---|
218 | ....................... |
---|
219 | |
---|
220 | A "self-referential" macro is one whose name appears in its |
---|
221 | definition. A special feature of ANSI Standard C is that the |
---|
222 | self-reference is not considered a macro call. It is passed into the |
---|
223 | preprocessor output unchanged. |
---|
224 | |
---|
225 | Let's consider an example: |
---|
226 | |
---|
227 | #define foo (4 + foo) |
---|
228 | |
---|
229 | where `foo' is also a variable in your program. |
---|
230 | |
---|
231 | Following the ordinary rules, each reference to `foo' will expand |
---|
232 | into `(4 + foo)'; then this will be rescanned and will expand into `(4 |
---|
233 | + (4 + foo))'; and so on until it causes a fatal error (memory full) in |
---|
234 | the preprocessor. |
---|
235 | |
---|
236 | However, the special rule about self-reference cuts this process |
---|
237 | short after one step, at `(4 + foo)'. Therefore, this macro definition |
---|
238 | has the possibly useful effect of causing the program to add 4 to the |
---|
239 | value of `foo' wherever `foo' is referred to. |
---|
240 | |
---|
241 | In most cases, it is a bad idea to take advantage of this feature. A |
---|
242 | person reading the program who sees that `foo' is a variable will not |
---|
243 | expect that it is a macro as well. The reader will come across the |
---|
244 | identifier `foo' in the program and think its value should be that of |
---|
245 | the variable `foo', whereas in fact the value is four greater. |
---|
246 | |
---|
247 | The special rule for self-reference applies also to "indirect" |
---|
248 | self-reference. This is the case where a macro X expands to use a |
---|
249 | macro `y', and the expansion of `y' refers to the macro `x'. The |
---|
250 | resulting reference to `x' comes indirectly from the expansion of `x', |
---|
251 | so it is a self-reference and is not further expanded. Thus, after |
---|
252 | |
---|
253 | #define x (4 + y) |
---|
254 | #define y (2 * x) |
---|
255 | |
---|
256 | `x' would expand into `(4 + (2 * x))'. Clear? |
---|
257 | |
---|
258 | But suppose `y' is used elsewhere, not from the definition of `x'. |
---|
259 | Then the use of `x' in the expansion of `y' is not a self-reference |
---|
260 | because `x' is not "in progress". So it does expand. However, the |
---|
261 | expansion of `x' contains a reference to `y', and that is an indirect |
---|
262 | self-reference now because `y' is "in progress". The result is that |
---|
263 | `y' expands to `(2 * (4 + y))'. |
---|
264 | |
---|
265 | It is not clear that this behavior would ever be useful, but it is |
---|
266 | specified by the ANSI C standard, so you may need to understand it. |
---|
267 | |
---|
268 | |
---|
269 | File: cpp.info, Node: Argument Prescan, Next: Cascaded Macros, Prev: Self-Reference, Up: Macro Pitfalls |
---|
270 | |
---|
271 | Separate Expansion of Macro Arguments |
---|
272 | ..................................... |
---|
273 | |
---|
274 | We have explained that the expansion of a macro, including the |
---|
275 | substituted actual arguments, is scanned over again for macro calls to |
---|
276 | be expanded. |
---|
277 | |
---|
278 | What really happens is more subtle: first each actual argument text |
---|
279 | is scanned separately for macro calls. Then the results of this are |
---|
280 | substituted into the macro body to produce the macro expansion, and the |
---|
281 | macro expansion is scanned again for macros to expand. |
---|
282 | |
---|
283 | The result is that the actual arguments are scanned *twice* to expand |
---|
284 | macro calls in them. |
---|
285 | |
---|
286 | Most of the time, this has no effect. If the actual argument |
---|
287 | contained any macro calls, they are expanded during the first scan. |
---|
288 | The result therefore contains no macro calls, so the second scan does |
---|
289 | not change it. If the actual argument were substituted as given, with |
---|
290 | no prescan, the single remaining scan would find the same macro calls |
---|
291 | and produce the same results. |
---|
292 | |
---|
293 | You might expect the double scan to change the results when a |
---|
294 | self-referential macro is used in an actual argument of another macro |
---|
295 | (*note Self-Reference::.): the self-referential macro would be expanded |
---|
296 | once in the first scan, and a second time in the second scan. But this |
---|
297 | is not what happens. The self-references that do not expand in the |
---|
298 | first scan are marked so that they will not expand in the second scan |
---|
299 | either. |
---|
300 | |
---|
301 | The prescan is not done when an argument is stringified or |
---|
302 | concatenated. Thus, |
---|
303 | |
---|
304 | #define str(s) #s |
---|
305 | #define foo 4 |
---|
306 | str (foo) |
---|
307 | |
---|
308 | expands to `"foo"'. Once more, prescan has been prevented from having |
---|
309 | any noticeable effect. |
---|
310 | |
---|
311 | More precisely, stringification and concatenation use the argument as |
---|
312 | written, in un-prescanned form. The same actual argument would be used |
---|
313 | in prescanned form if it is substituted elsewhere without |
---|
314 | stringification or concatenation. |
---|
315 | |
---|
316 | #define str(s) #s lose(s) |
---|
317 | #define foo 4 |
---|
318 | str (foo) |
---|
319 | |
---|
320 | expands to `"foo" lose(4)'. |
---|
321 | |
---|
322 | You might now ask, "Why mention the prescan, if it makes no |
---|
323 | difference? And why not skip it and make the preprocessor faster?" |
---|
324 | The answer is that the prescan does make a difference in three special |
---|
325 | cases: |
---|
326 | |
---|
327 | * Nested calls to a macro. |
---|
328 | |
---|
329 | * Macros that call other macros that stringify or concatenate. |
---|
330 | |
---|
331 | * Macros whose expansions contain unshielded commas. |
---|
332 | |
---|
333 | We say that "nested" calls to a macro occur when a macro's actual |
---|
334 | argument contains a call to that very macro. For example, if `f' is a |
---|
335 | macro that expects one argument, `f (f (1))' is a nested pair of calls |
---|
336 | to `f'. The desired expansion is made by expanding `f (1)' and |
---|
337 | substituting that into the definition of `f'. The prescan causes the |
---|
338 | expected result to happen. Without the prescan, `f (1)' itself would |
---|
339 | be substituted as an actual argument, and the inner use of `f' would |
---|
340 | appear during the main scan as an indirect self-reference and would not |
---|
341 | be expanded. Here, the prescan cancels an undesirable side effect (in |
---|
342 | the medical, not computational, sense of the term) of the special rule |
---|
343 | for self-referential macros. |
---|
344 | |
---|
345 | But prescan causes trouble in certain other cases of nested macro |
---|
346 | calls. Here is an example: |
---|
347 | |
---|
348 | #define foo a,b |
---|
349 | #define bar(x) lose(x) |
---|
350 | #define lose(x) (1 + (x)) |
---|
351 | |
---|
352 | bar(foo) |
---|
353 | |
---|
354 | We would like `bar(foo)' to turn into `(1 + (foo))', which would then |
---|
355 | turn into `(1 + (a,b))'. But instead, `bar(foo)' expands into |
---|
356 | `lose(a,b)', and you get an error because `lose' requires a single |
---|
357 | argument. In this case, the problem is easily solved by the same |
---|
358 | parentheses that ought to be used to prevent misnesting of arithmetic |
---|
359 | operations: |
---|
360 | |
---|
361 | #define foo (a,b) |
---|
362 | #define bar(x) lose((x)) |
---|
363 | |
---|
364 | The problem is more serious when the operands of the macro are not |
---|
365 | expressions; for example, when they are statements. Then parentheses |
---|
366 | are unacceptable because they would make for invalid C code: |
---|
367 | |
---|
368 | #define foo { int a, b; ... } |
---|
369 | |
---|
370 | In GNU C you can shield the commas using the `({...})' construct which |
---|
371 | turns a compound statement into an expression: |
---|
372 | |
---|
373 | #define foo ({ int a, b; ... }) |
---|
374 | |
---|
375 | Or you can rewrite the macro definition to avoid such commas: |
---|
376 | |
---|
377 | #define foo { int a; int b; ... } |
---|
378 | |
---|
379 | There is also one case where prescan is useful. It is possible to |
---|
380 | use prescan to expand an argument and then stringify it--if you use two |
---|
381 | levels of macros. Let's add a new macro `xstr' to the example shown |
---|
382 | above: |
---|
383 | |
---|
384 | #define xstr(s) str(s) |
---|
385 | #define str(s) #s |
---|
386 | #define foo 4 |
---|
387 | xstr (foo) |
---|
388 | |
---|
389 | This expands into `"4"', not `"foo"'. The reason for the difference |
---|
390 | is that the argument of `xstr' is expanded at prescan (because `xstr' |
---|
391 | does not specify stringification or concatenation of the argument). |
---|
392 | The result of prescan then forms the actual argument for `str'. `str' |
---|
393 | uses its argument without prescan because it performs stringification; |
---|
394 | but it cannot prevent or undo the prescanning already done by `xstr'. |
---|
395 | |
---|
396 | |
---|
397 | File: cpp.info, Node: Cascaded Macros, Next: Newlines in Args, Prev: Argument Prescan, Up: Macro Pitfalls |
---|
398 | |
---|
399 | Cascaded Use of Macros |
---|
400 | ...................... |
---|
401 | |
---|
402 | A "cascade" of macros is when one macro's body contains a reference |
---|
403 | to another macro. This is very common practice. For example, |
---|
404 | |
---|
405 | #define BUFSIZE 1020 |
---|
406 | #define TABLESIZE BUFSIZE |
---|
407 | |
---|
408 | This is not at all the same as defining `TABLESIZE' to be `1020'. |
---|
409 | The `#define' for `TABLESIZE' uses exactly the body you specify--in |
---|
410 | this case, `BUFSIZE'--and does not check to see whether it too is the |
---|
411 | name of a macro. |
---|
412 | |
---|
413 | It's only when you *use* `TABLESIZE' that the result of its expansion |
---|
414 | is checked for more macro names. |
---|
415 | |
---|
416 | This makes a difference if you change the definition of `BUFSIZE' at |
---|
417 | some point in the source file. `TABLESIZE', defined as shown, will |
---|
418 | always expand using the definition of `BUFSIZE' that is currently in |
---|
419 | effect: |
---|
420 | |
---|
421 | #define BUFSIZE 1020 |
---|
422 | #define TABLESIZE BUFSIZE |
---|
423 | #undef BUFSIZE |
---|
424 | #define BUFSIZE 37 |
---|
425 | |
---|
426 | Now `TABLESIZE' expands (in two stages) to `37'. (The `#undef' is to |
---|
427 | prevent any warning about the nontrivial redefinition of `BUFSIZE'.) |
---|
428 | |
---|
429 | |
---|
430 | File: cpp.info, Node: Newlines in Args, Prev: Cascaded Macros, Up: Macro Pitfalls |
---|
431 | |
---|
432 | Newlines in Macro Arguments |
---|
433 | --------------------------- |
---|
434 | |
---|
435 | Traditional macro processing carries forward all newlines in macro |
---|
436 | arguments into the expansion of the macro. This means that, if some of |
---|
437 | the arguments are substituted more than once, or not at all, or out of |
---|
438 | order, newlines can be duplicated, lost, or moved around within the |
---|
439 | expansion. If the expansion consists of multiple statements, then the |
---|
440 | effect is to distort the line numbers of some of these statements. The |
---|
441 | result can be incorrect line numbers, in error messages or displayed in |
---|
442 | a debugger. |
---|
443 | |
---|
444 | The GNU C preprocessor operating in ANSI C mode adjusts appropriately |
---|
445 | for multiple use of an argument--the first use expands all the |
---|
446 | newlines, and subsequent uses of the same argument produce no newlines. |
---|
447 | But even in this mode, it can produce incorrect line numbering if |
---|
448 | arguments are used out of order, or not used at all. |
---|
449 | |
---|
450 | Here is an example illustrating this problem: |
---|
451 | |
---|
452 | #define ignore_second_arg(a,b,c) a; c |
---|
453 | |
---|
454 | ignore_second_arg (foo (), |
---|
455 | ignored (), |
---|
456 | syntax error); |
---|
457 | |
---|
458 | The syntax error triggered by the tokens `syntax error' results in an |
---|
459 | error message citing line four, even though the statement text comes |
---|
460 | from line five. |
---|
461 | |
---|
462 | |
---|
463 | File: cpp.info, Node: Conditionals, Next: Combining Sources, Prev: Macros, Up: Top |
---|
464 | |
---|
465 | Conditionals |
---|
466 | ============ |
---|
467 | |
---|
468 | In a macro processor, a "conditional" is a directive that allows a |
---|
469 | part of the program to be ignored during compilation, on some |
---|
470 | conditions. In the C preprocessor, a conditional can test either an |
---|
471 | arithmetic expression or whether a name is defined as a macro. |
---|
472 | |
---|
473 | A conditional in the C preprocessor resembles in some ways an `if' |
---|
474 | statement in C, but it is important to understand the difference between |
---|
475 | them. The condition in an `if' statement is tested during the execution |
---|
476 | of your program. Its purpose is to allow your program to behave |
---|
477 | differently from run to run, depending on the data it is operating on. |
---|
478 | The condition in a preprocessing conditional directive is tested when |
---|
479 | your program is compiled. Its purpose is to allow different code to be |
---|
480 | included in the program depending on the situation at the time of |
---|
481 | compilation. |
---|
482 | |
---|
483 | * Menu: |
---|
484 | |
---|
485 | * Uses: Conditional Uses. What conditionals are for. |
---|
486 | * Syntax: Conditional Syntax. How conditionals are written. |
---|
487 | * Deletion: Deleted Code. Making code into a comment. |
---|
488 | * Macros: Conditionals-Macros. Why conditionals are used with macros. |
---|
489 | * Assertions:: How and why to use assertions. |
---|
490 | * Errors: #error Directive. Detecting inconsistent compilation parameters. |
---|
491 | |
---|
492 | |
---|
493 | File: cpp.info, Node: Conditional Uses, Next: Conditional Syntax, Up: Conditionals |
---|
494 | |
---|
495 | Why Conditionals are Used |
---|
496 | ------------------------- |
---|
497 | |
---|
498 | Generally there are three kinds of reason to use a conditional. |
---|
499 | |
---|
500 | * A program may need to use different code depending on the machine |
---|
501 | or operating system it is to run on. In some cases the code for |
---|
502 | one operating system may be erroneous on another operating system; |
---|
503 | for example, it might refer to library routines that do not exist |
---|
504 | on the other system. When this happens, it is not enough to avoid |
---|
505 | executing the invalid code: merely having it in the program makes |
---|
506 | it impossible to link the program and run it. With a |
---|
507 | preprocessing conditional, the offending code can be effectively |
---|
508 | excised from the program when it is not valid. |
---|
509 | |
---|
510 | * You may want to be able to compile the same source file into two |
---|
511 | different programs. Sometimes the difference between the programs |
---|
512 | is that one makes frequent time-consuming consistency checks on its |
---|
513 | intermediate data, or prints the values of those data for |
---|
514 | debugging, while the other does not. |
---|
515 | |
---|
516 | * A conditional whose condition is always false is a good way to |
---|
517 | exclude code from the program but keep it as a sort of comment for |
---|
518 | future reference. |
---|
519 | |
---|
520 | Most simple programs that are intended to run on only one machine |
---|
521 | will not need to use preprocessing conditionals. |
---|
522 | |
---|
523 | |
---|
524 | File: cpp.info, Node: Conditional Syntax, Next: Deleted Code, Prev: Conditional Uses, Up: Conditionals |
---|
525 | |
---|
526 | Syntax of Conditionals |
---|
527 | ---------------------- |
---|
528 | |
---|
529 | A conditional in the C preprocessor begins with a "conditional |
---|
530 | directive": `#if', `#ifdef' or `#ifndef'. *Note Conditionals-Macros::, |
---|
531 | for information on `#ifdef' and `#ifndef'; only `#if' is explained here. |
---|
532 | |
---|
533 | * Menu: |
---|
534 | |
---|
535 | * If: #if Directive. Basic conditionals using `#if' and `#endif'. |
---|
536 | * Else: #else Directive. Including some text if the condition fails. |
---|
537 | * Elif: #elif Directive. Testing several alternative possibilities. |
---|
538 | |
---|
539 | |
---|
540 | File: cpp.info, Node: #if Directive, Next: #else Directive, Up: Conditional Syntax |
---|
541 | |
---|
542 | The `#if' Directive |
---|
543 | ................... |
---|
544 | |
---|
545 | The `#if' directive in its simplest form consists of |
---|
546 | |
---|
547 | #if EXPRESSION |
---|
548 | CONTROLLED TEXT |
---|
549 | #endif /* EXPRESSION */ |
---|
550 | |
---|
551 | The comment following the `#endif' is not required, but it is a good |
---|
552 | practice because it helps people match the `#endif' to the |
---|
553 | corresponding `#if'. Such comments should always be used, except in |
---|
554 | short conditionals that are not nested. In fact, you can put anything |
---|
555 | at all after the `#endif' and it will be ignored by the GNU C |
---|
556 | preprocessor, but only comments are acceptable in ANSI Standard C. |
---|
557 | |
---|
558 | EXPRESSION is a C expression of integer type, subject to stringent |
---|
559 | restrictions. It may contain |
---|
560 | |
---|
561 | * Integer constants, which are all regarded as `long' or `unsigned |
---|
562 | long'. |
---|
563 | |
---|
564 | * Character constants, which are interpreted according to the |
---|
565 | character set and conventions of the machine and operating system |
---|
566 | on which the preprocessor is running. The GNU C preprocessor uses |
---|
567 | the C data type `char' for these character constants; therefore, |
---|
568 | whether some character codes are negative is determined by the C |
---|
569 | compiler used to compile the preprocessor. If it treats `char' as |
---|
570 | signed, then character codes large enough to set the sign bit will |
---|
571 | be considered negative; otherwise, no character code is considered |
---|
572 | negative. |
---|
573 | |
---|
574 | * Arithmetic operators for addition, subtraction, multiplication, |
---|
575 | division, bitwise operations, shifts, comparisons, and logical |
---|
576 | operations (`&&' and `||'). |
---|
577 | |
---|
578 | * Identifiers that are not macros, which are all treated as zero(!). |
---|
579 | |
---|
580 | * Macro calls. All macro calls in the expression are expanded before |
---|
581 | actual computation of the expression's value begins. |
---|
582 | |
---|
583 | Note that `sizeof' operators and `enum'-type values are not allowed. |
---|
584 | `enum'-type values, like all other identifiers that are not taken as |
---|
585 | macro calls and expanded, are treated as zero. |
---|
586 | |
---|
587 | The CONTROLLED TEXT inside of a conditional can include |
---|
588 | preprocessing directives. Then the directives inside the conditional |
---|
589 | are obeyed only if that branch of the conditional succeeds. The text |
---|
590 | can also contain other conditional groups. However, the `#if' and |
---|
591 | `#endif' directives must balance. |
---|
592 | |
---|
593 | |
---|
594 | File: cpp.info, Node: #else Directive, Next: #elif Directive, Prev: #if Directive, Up: Conditional Syntax |
---|
595 | |
---|
596 | The `#else' Directive |
---|
597 | ..................... |
---|
598 | |
---|
599 | The `#else' directive can be added to a conditional to provide |
---|
600 | alternative text to be used if the condition is false. This is what it |
---|
601 | looks like: |
---|
602 | |
---|
603 | #if EXPRESSION |
---|
604 | TEXT-IF-TRUE |
---|
605 | #else /* Not EXPRESSION */ |
---|
606 | TEXT-IF-FALSE |
---|
607 | #endif /* Not EXPRESSION */ |
---|
608 | |
---|
609 | If EXPRESSION is nonzero, and thus the TEXT-IF-TRUE is active, then |
---|
610 | `#else' acts like a failing conditional and the TEXT-IF-FALSE is |
---|
611 | ignored. Contrariwise, if the `#if' conditional fails, the |
---|
612 | TEXT-IF-FALSE is considered included. |
---|
613 | |
---|
614 | |
---|
615 | File: cpp.info, Node: #elif Directive, Prev: #else Directive, Up: Conditional Syntax |
---|
616 | |
---|
617 | The `#elif' Directive |
---|
618 | ..................... |
---|
619 | |
---|
620 | One common case of nested conditionals is used to check for more |
---|
621 | than two possible alternatives. For example, you might have |
---|
622 | |
---|
623 | #if X == 1 |
---|
624 | ... |
---|
625 | #else /* X != 1 */ |
---|
626 | #if X == 2 |
---|
627 | ... |
---|
628 | #else /* X != 2 */ |
---|
629 | ... |
---|
630 | #endif /* X != 2 */ |
---|
631 | #endif /* X != 1 */ |
---|
632 | |
---|
633 | Another conditional directive, `#elif', allows this to be abbreviated |
---|
634 | as follows: |
---|
635 | |
---|
636 | #if X == 1 |
---|
637 | ... |
---|
638 | #elif X == 2 |
---|
639 | ... |
---|
640 | #else /* X != 2 and X != 1*/ |
---|
641 | ... |
---|
642 | #endif /* X != 2 and X != 1*/ |
---|
643 | |
---|
644 | `#elif' stands for "else if". Like `#else', it goes in the middle |
---|
645 | of a `#if'-`#endif' pair and subdivides it; it does not require a |
---|
646 | matching `#endif' of its own. Like `#if', the `#elif' directive |
---|
647 | includes an expression to be tested. |
---|
648 | |
---|
649 | The text following the `#elif' is processed only if the original |
---|
650 | `#if'-condition failed and the `#elif' condition succeeds. More than |
---|
651 | one `#elif' can go in the same `#if'-`#endif' group. Then the text |
---|
652 | after each `#elif' is processed only if the `#elif' condition succeeds |
---|
653 | after the original `#if' and any previous `#elif' directives within it |
---|
654 | have failed. `#else' is equivalent to `#elif 1', and `#else' is |
---|
655 | allowed after any number of `#elif' directives, but `#elif' may not |
---|
656 | follow `#else'. |
---|
657 | |
---|
658 | |
---|
659 | File: cpp.info, Node: Deleted Code, Next: Conditionals-Macros, Prev: Conditional Syntax, Up: Conditionals |
---|
660 | |
---|
661 | Keeping Deleted Code for Future Reference |
---|
662 | ----------------------------------------- |
---|
663 | |
---|
664 | If you replace or delete a part of the program but want to keep the |
---|
665 | old code around as a comment for future reference, the easy way to do |
---|
666 | this is to put `#if 0' before it and `#endif' after it. This is better |
---|
667 | than using comment delimiters `/*' and `*/' since those won't work if |
---|
668 | the code already contains comments (C comments do not nest). |
---|
669 | |
---|
670 | This works even if the code being turned off contains conditionals, |
---|
671 | but they must be entire conditionals (balanced `#if' and `#endif'). |
---|
672 | |
---|
673 | Conversely, do not use `#if 0' for comments which are not C code. |
---|
674 | Use the comment delimiters `/*' and `*/' instead. The interior of `#if |
---|
675 | 0' must consist of complete tokens; in particular, singlequote |
---|
676 | characters must balance. But comments often contain unbalanced |
---|
677 | singlequote characters (known in English as apostrophes). These |
---|
678 | confuse `#if 0'. They do not confuse `/*'. |
---|
679 | |
---|
680 | |
---|
681 | File: cpp.info, Node: Conditionals-Macros, Next: Assertions, Prev: Deleted Code, Up: Conditionals |
---|
682 | |
---|
683 | Conditionals and Macros |
---|
684 | ----------------------- |
---|
685 | |
---|
686 | Conditionals are useful in connection with macros or assertions, |
---|
687 | because those are the only ways that an expression's value can vary |
---|
688 | from one compilation to another. A `#if' directive whose expression |
---|
689 | uses no macros or assertions is equivalent to `#if 1' or `#if 0'; you |
---|
690 | might as well determine which one, by computing the value of the |
---|
691 | expression yourself, and then simplify the program. |
---|
692 | |
---|
693 | For example, here is a conditional that tests the expression |
---|
694 | `BUFSIZE == 1020', where `BUFSIZE' must be a macro. |
---|
695 | |
---|
696 | #if BUFSIZE == 1020 |
---|
697 | printf ("Large buffers!\n"); |
---|
698 | #endif /* BUFSIZE is large */ |
---|
699 | |
---|
700 | (Programmers often wish they could test the size of a variable or |
---|
701 | data type in `#if', but this does not work. The preprocessor does not |
---|
702 | understand `sizeof', or typedef names, or even the type keywords such |
---|
703 | as `int'.) |
---|
704 | |
---|
705 | The special operator `defined' is used in `#if' expressions to test |
---|
706 | whether a certain name is defined as a macro. Either `defined NAME' or |
---|
707 | `defined (NAME)' is an expression whose value is 1 if NAME is defined |
---|
708 | as macro at the current point in the program, and 0 otherwise. For the |
---|
709 | `defined' operator it makes no difference what the definition of the |
---|
710 | macro is; all that matters is whether there is a definition. Thus, for |
---|
711 | example, |
---|
712 | |
---|
713 | #if defined (vax) || defined (ns16000) |
---|
714 | |
---|
715 | would succeed if either of the names `vax' and `ns16000' is defined as |
---|
716 | a macro. You can test the same condition using assertions (*note |
---|
717 | Assertions::.), like this: |
---|
718 | |
---|
719 | #if #cpu (vax) || #cpu (ns16000) |
---|
720 | |
---|
721 | If a macro is defined and later undefined with `#undef', subsequent |
---|
722 | use of the `defined' operator returns 0, because the name is no longer |
---|
723 | defined. If the macro is defined again with another `#define', |
---|
724 | `defined' will recommence returning 1. |
---|
725 | |
---|
726 | Conditionals that test whether just one name is defined are very |
---|
727 | common, so there are two special short conditional directives for this |
---|
728 | case. |
---|
729 | |
---|
730 | `#ifdef NAME' |
---|
731 | is equivalent to `#if defined (NAME)'. |
---|
732 | |
---|
733 | `#ifndef NAME' |
---|
734 | is equivalent to `#if ! defined (NAME)'. |
---|
735 | |
---|
736 | Macro definitions can vary between compilations for several reasons. |
---|
737 | |
---|
738 | * Some macros are predefined on each kind of machine. For example, |
---|
739 | on a Vax, the name `vax' is a predefined macro. On other |
---|
740 | machines, it would not be defined. |
---|
741 | |
---|
742 | * Many more macros are defined by system header files. Different |
---|
743 | systems and machines define different macros, or give them |
---|
744 | different values. It is useful to test these macros with |
---|
745 | conditionals to avoid using a system feature on a machine where it |
---|
746 | is not implemented. |
---|
747 | |
---|
748 | * Macros are a common way of allowing users to customize a program |
---|
749 | for different machines or applications. For example, the macro |
---|
750 | `BUFSIZE' might be defined in a configuration file for your |
---|
751 | program that is included as a header file in each source file. You |
---|
752 | would use `BUFSIZE' in a preprocessing conditional in order to |
---|
753 | generate different code depending on the chosen configuration. |
---|
754 | |
---|
755 | * Macros can be defined or undefined with `-D' and `-U' command |
---|
756 | options when you compile the program. You can arrange to compile |
---|
757 | the same source file into two different programs by choosing a |
---|
758 | macro name to specify which program you want, writing conditionals |
---|
759 | to test whether or how this macro is defined, and then controlling |
---|
760 | the state of the macro with compiler command options. *Note |
---|
761 | Invocation::. |
---|
762 | |
---|
763 | Assertions are usually predefined, but can be defined with |
---|
764 | preprocessor directives or command-line options. |
---|
765 | |
---|
766 | |
---|
767 | File: cpp.info, Node: Assertions, Next: #error Directive, Prev: Conditionals-Macros, Up: Conditionals |
---|
768 | |
---|
769 | Assertions |
---|
770 | ---------- |
---|
771 | |
---|
772 | "Assertions" are a more systematic alternative to macros in writing |
---|
773 | conditionals to test what sort of computer or system the compiled |
---|
774 | program will run on. Assertions are usually predefined, but you can |
---|
775 | define them with preprocessing directives or command-line options. |
---|
776 | |
---|
777 | The macros traditionally used to describe the type of target are not |
---|
778 | classified in any way according to which question they answer; they may |
---|
779 | indicate a hardware architecture, a particular hardware model, an |
---|
780 | operating system, a particular version of an operating system, or |
---|
781 | specific configuration options. These are jumbled together in a single |
---|
782 | namespace. In contrast, each assertion consists of a named question and |
---|
783 | an answer. The question is usually called the "predicate". An |
---|
784 | assertion looks like this: |
---|
785 | |
---|
786 | #PREDICATE (ANSWER) |
---|
787 | |
---|
788 | You must use a properly formed identifier for PREDICATE. The value of |
---|
789 | ANSWER can be any sequence of words; all characters are significant |
---|
790 | except for leading and trailing whitespace, and differences in internal |
---|
791 | whitespace sequences are ignored. Thus, `x + y' is different from |
---|
792 | `x+y' but equivalent to `x + y'. `)' is not allowed in an answer. |
---|
793 | |
---|
794 | Here is a conditional to test whether the answer ANSWER is asserted |
---|
795 | for the predicate PREDICATE: |
---|
796 | |
---|
797 | #if #PREDICATE (ANSWER) |
---|
798 | |
---|
799 | There may be more than one answer asserted for a given predicate. If |
---|
800 | you omit the answer, you can test whether *any* answer is asserted for |
---|
801 | PREDICATE: |
---|
802 | |
---|
803 | #if #PREDICATE |
---|
804 | |
---|
805 | Most of the time, the assertions you test will be predefined |
---|
806 | assertions. GNU C provides three predefined predicates: `system', |
---|
807 | `cpu', and `machine'. `system' is for assertions about the type of |
---|
808 | software, `cpu' describes the type of computer architecture, and |
---|
809 | `machine' gives more information about the computer. For example, on a |
---|
810 | GNU system, the following assertions would be true: |
---|
811 | |
---|
812 | #system (gnu) |
---|
813 | #system (mach) |
---|
814 | #system (mach 3) |
---|
815 | #system (mach 3.SUBVERSION) |
---|
816 | #system (hurd) |
---|
817 | #system (hurd VERSION) |
---|
818 | |
---|
819 | and perhaps others. The alternatives with more or less version |
---|
820 | information let you ask more or less detailed questions about the type |
---|
821 | of system software. |
---|
822 | |
---|
823 | On a Unix system, you would find `#system (unix)' and perhaps one of: |
---|
824 | `#system (aix)', `#system (bsd)', `#system (hpux)', `#system (lynx)', |
---|
825 | `#system (mach)', `#system (posix)', `#system (svr3)', `#system |
---|
826 | (svr4)', or `#system (xpg4)' with possible version numbers following. |
---|
827 | |
---|
828 | Other values for `system' are `#system (mvs)' and `#system (vms)'. |
---|
829 | |
---|
830 | *Portability note:* Many Unix C compilers provide only one answer |
---|
831 | for the `system' assertion: `#system (unix)', if they support |
---|
832 | assertions at all. This is less than useful. |
---|
833 | |
---|
834 | An assertion with a multi-word answer is completely different from |
---|
835 | several assertions with individual single-word answers. For example, |
---|
836 | the presence of `system (mach 3.0)' does not mean that `system (3.0)' |
---|
837 | is true. It also does not directly imply `system (mach)', but in GNU |
---|
838 | C, that last will normally be asserted as well. |
---|
839 | |
---|
840 | The current list of possible assertion values for `cpu' is: `#cpu |
---|
841 | (a29k)', `#cpu (alpha)', `#cpu (arm)', `#cpu (clipper)', `#cpu |
---|
842 | (convex)', `#cpu (elxsi)', `#cpu (tron)', `#cpu (h8300)', `#cpu |
---|
843 | (i370)', `#cpu (i386)', `#cpu (i860)', `#cpu (i960)', `#cpu (m68k)', |
---|
844 | `#cpu (m88k)', `#cpu (mips)', `#cpu (ns32k)', `#cpu (hppa)', `#cpu |
---|
845 | (pyr)', `#cpu (ibm032)', `#cpu (rs6000)', `#cpu (sh)', `#cpu (sparc)', |
---|
846 | `#cpu (spur)', `#cpu (tahoe)', `#cpu (vax)', `#cpu (we32000)'. |
---|
847 | |
---|
848 | You can create assertions within a C program using `#assert', like |
---|
849 | this: |
---|
850 | |
---|
851 | #assert PREDICATE (ANSWER) |
---|
852 | |
---|
853 | (Note the absence of a `#' before PREDICATE.) |
---|
854 | |
---|
855 | Each time you do this, you assert a new true answer for PREDICATE. |
---|
856 | Asserting one answer does not invalidate previously asserted answers; |
---|
857 | they all remain true. The only way to remove an assertion is with |
---|
858 | `#unassert'. `#unassert' has the same syntax as `#assert'. You can |
---|
859 | also remove all assertions about PREDICATE like this: |
---|
860 | |
---|
861 | #unassert PREDICATE |
---|
862 | |
---|
863 | You can also add or cancel assertions using command options when you |
---|
864 | run `gcc' or `cpp'. *Note Invocation::. |
---|
865 | |
---|
866 | |
---|
867 | File: cpp.info, Node: #error Directive, Prev: Assertions, Up: Conditionals |
---|
868 | |
---|
869 | The `#error' and `#warning' Directives |
---|
870 | -------------------------------------- |
---|
871 | |
---|
872 | The directive `#error' causes the preprocessor to report a fatal |
---|
873 | error. The rest of the line that follows `#error' is used as the error |
---|
874 | message. |
---|
875 | |
---|
876 | You would use `#error' inside of a conditional that detects a |
---|
877 | combination of parameters which you know the program does not properly |
---|
878 | support. For example, if you know that the program will not run |
---|
879 | properly on a Vax, you might write |
---|
880 | |
---|
881 | #ifdef __vax__ |
---|
882 | #error Won't work on Vaxen. See comments at get_last_object. |
---|
883 | #endif |
---|
884 | |
---|
885 | *Note Nonstandard Predefined::, for why this works. |
---|
886 | |
---|
887 | If you have several configuration parameters that must be set up by |
---|
888 | the installation in a consistent way, you can use conditionals to detect |
---|
889 | an inconsistency and report it with `#error'. For example, |
---|
890 | |
---|
891 | #if HASH_TABLE_SIZE % 2 == 0 || HASH_TABLE_SIZE % 3 == 0 \ |
---|
892 | || HASH_TABLE_SIZE % 5 == 0 |
---|
893 | #error HASH_TABLE_SIZE should not be divisible by a small prime |
---|
894 | #endif |
---|
895 | |
---|
896 | The directive `#warning' is like the directive `#error', but causes |
---|
897 | the preprocessor to issue a warning and continue preprocessing. The |
---|
898 | rest of the line that follows `#warning' is used as the warning message. |
---|
899 | |
---|
900 | You might use `#warning' in obsolete header files, with a message |
---|
901 | directing the user to the header file which should be used instead. |
---|
902 | |
---|
903 | |
---|
904 | File: cpp.info, Node: Combining Sources, Next: Other Directives, Prev: Conditionals, Up: Top |
---|
905 | |
---|
906 | Combining Source Files |
---|
907 | ====================== |
---|
908 | |
---|
909 | One of the jobs of the C preprocessor is to inform the C compiler of |
---|
910 | where each line of C code came from: which source file and which line |
---|
911 | number. |
---|
912 | |
---|
913 | C code can come from multiple source files if you use `#include'; |
---|
914 | both `#include' and the use of conditionals and macros can cause the |
---|
915 | line number of a line in the preprocessor output to be different from |
---|
916 | the line's number in the original source file. You will appreciate the |
---|
917 | value of making both the C compiler (in error messages) and symbolic |
---|
918 | debuggers such as GDB use the line numbers in your source file. |
---|
919 | |
---|
920 | The C preprocessor builds on this feature by offering a directive by |
---|
921 | which you can control the feature explicitly. This is useful when a |
---|
922 | file for input to the C preprocessor is the output from another program |
---|
923 | such as the `bison' parser generator, which operates on another file |
---|
924 | that is the true source file. Parts of the output from `bison' are |
---|
925 | generated from scratch, other parts come from a standard parser file. |
---|
926 | The rest are copied nearly verbatim from the source file, but their |
---|
927 | line numbers in the `bison' output are not the same as their original |
---|
928 | line numbers. Naturally you would like compiler error messages and |
---|
929 | symbolic debuggers to know the original source file and line number of |
---|
930 | each line in the `bison' input. |
---|
931 | |
---|
932 | `bison' arranges this by writing `#line' directives into the output |
---|
933 | file. `#line' is a directive that specifies the original line number |
---|
934 | and source file name for subsequent input in the current preprocessor |
---|
935 | input file. `#line' has three variants: |
---|
936 | |
---|
937 | `#line LINENUM' |
---|
938 | Here LINENUM is a decimal integer constant. This specifies that |
---|
939 | the line number of the following line of input, in its original |
---|
940 | source file, was LINENUM. |
---|
941 | |
---|
942 | `#line LINENUM FILENAME' |
---|
943 | Here LINENUM is a decimal integer constant and FILENAME is a |
---|
944 | string constant. This specifies that the following line of input |
---|
945 | came originally from source file FILENAME and its line number there |
---|
946 | was LINENUM. Keep in mind that FILENAME is not just a file name; |
---|
947 | it is surrounded by doublequote characters so that it looks like a |
---|
948 | string constant. |
---|
949 | |
---|
950 | `#line ANYTHING ELSE' |
---|
951 | ANYTHING ELSE is checked for macro calls, which are expanded. The |
---|
952 | result should be a decimal integer constant followed optionally by |
---|
953 | a string constant, as described above. |
---|
954 | |
---|
955 | `#line' directives alter the results of the `__FILE__' and |
---|
956 | `__LINE__' predefined macros from that point on. *Note Standard |
---|
957 | Predefined::. |
---|
958 | |
---|
959 | The output of the preprocessor (which is the input for the rest of |
---|
960 | the compiler) contains directives that look much like `#line' |
---|
961 | directives. They start with just `#' instead of `#line', but this is |
---|
962 | followed by a line number and file name as in `#line'. *Note Output::. |
---|
963 | |
---|
964 | |
---|
965 | File: cpp.info, Node: Other Directives, Next: Output, Prev: Combining Sources, Up: Top |
---|
966 | |
---|
967 | Miscellaneous Preprocessing Directives |
---|
968 | ====================================== |
---|
969 | |
---|
970 | This section describes three additional preprocessing directives. |
---|
971 | They are not very useful, but are mentioned for completeness. |
---|
972 | |
---|
973 | The "null directive" consists of a `#' followed by a Newline, with |
---|
974 | only whitespace (including comments) in between. A null directive is |
---|
975 | understood as a preprocessing directive but has no effect on the |
---|
976 | preprocessor output. The primary significance of the existence of the |
---|
977 | null directive is that an input line consisting of just a `#' will |
---|
978 | produce no output, rather than a line of output containing just a `#'. |
---|
979 | Supposedly some old C programs contain such lines. |
---|
980 | |
---|
981 | The ANSI standard specifies that the `#pragma' directive has an |
---|
982 | arbitrary, implementation-defined effect. In the GNU C preprocessor, |
---|
983 | `#pragma' directives are not used, except for `#pragma once' (*note |
---|
984 | Once-Only::.). However, they are left in the preprocessor output, so |
---|
985 | they are available to the compilation pass. |
---|
986 | |
---|
987 | The `#ident' directive is supported for compatibility with certain |
---|
988 | other systems. It is followed by a line of text. On some systems, the |
---|
989 | text is copied into a special place in the object file; on most systems, |
---|
990 | the text is ignored and this directive has no effect. Typically |
---|
991 | `#ident' is only used in header files supplied with those systems where |
---|
992 | it is meaningful. |
---|
993 | |
---|
994 | |
---|
995 | File: cpp.info, Node: Output, Next: Invocation, Prev: Other Directives, Up: Top |
---|
996 | |
---|
997 | C Preprocessor Output |
---|
998 | ===================== |
---|
999 | |
---|
1000 | The output from the C preprocessor looks much like the input, except |
---|
1001 | that all preprocessing directive lines have been replaced with blank |
---|
1002 | lines and all comments with spaces. Whitespace within a line is not |
---|
1003 | altered; however, a space is inserted after the expansions of most |
---|
1004 | macro calls. |
---|
1005 | |
---|
1006 | Source file name and line number information is conveyed by lines of |
---|
1007 | the form |
---|
1008 | |
---|
1009 | # LINENUM FILENAME FLAGS |
---|
1010 | |
---|
1011 | which are inserted as needed into the middle of the input (but never |
---|
1012 | within a string or character constant). Such a line means that the |
---|
1013 | following line originated in file FILENAME at line LINENUM. |
---|
1014 | |
---|
1015 | After the file name comes zero or more flags, which are `1', `2', |
---|
1016 | `3', or `4'. If there are multiple flags, spaces separate them. Here |
---|
1017 | is what the flags mean: |
---|
1018 | |
---|
1019 | `1' |
---|
1020 | This indicates the start of a new file. |
---|
1021 | |
---|
1022 | `2' |
---|
1023 | This indicates returning to a file (after having included another |
---|
1024 | file). |
---|
1025 | |
---|
1026 | `3' |
---|
1027 | This indicates that the following text comes from a system header |
---|
1028 | file, so certain warnings should be suppressed. |
---|
1029 | |
---|
1030 | `4' |
---|
1031 | This indicates that the following text should be treated as C. |
---|
1032 | |
---|