[8833] | 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 | |
---|