![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to cpp.info-2 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 2.x] / gcc|
Return to cpp.info-2 CVS log | Up to [GCC 2.x] / gcc |
1.1.1.7 ! root 1: This is Info file cpp.info, produced by Makeinfo version 1.67 from the ! 2: input file cpp.texi. 1.1 root 3: 4: This file documents the GNU C Preprocessor. 5: 1.1.1.6 root 6: Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995 Free Software 1.1.1.5 root 7: Foundation, Inc. 1.1 root 8: 1.1.1.2 root 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. 1.1 root 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: 1.1.1.6 root 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: 1.1.1.5 root 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: 1.1 root 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: 1.1.1.2 root 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. 1.1 root 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 1.1.1.2 root 144: statement--in between the `if' condition and the `else' makes invalid C 145: code. 1.1 root 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 1.1.1.2 root 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. 1.1 root 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 1.1.1.3 root 221: definition. A special feature of ANSI Standard C is that the 1.1 root 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 1.1.1.2 root 233: + (4 + foo))'; and so on until it causes a fatal error (memory full) in 234: the preprocessor. 1.1 root 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: 1.1.1.2 root 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 1.1 root 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 1.1.1.2 root 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 1.1 root 252: 253: #define x (4 + y) 254: #define y (2 * x) 255: 256: `x' would expand into `(4 + (2 * x))'. Clear? 257: 1.1.1.2 root 258: But suppose `y' is used elsewhere, not from the definition of `x'. 1.1 root 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 1.1.1.3 root 262: self-reference now because `y' is "in progress". The result is that 263: `y' expands to `(2 * (4 + y))'. 1.1 root 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 1.1.1.2 root 280: substituted into the macro body to produce the macro expansion, and the 281: macro expansion is scanned again for macros to expand. 1.1 root 282: 1.1.1.2 root 283: The result is that the actual arguments are scanned *twice* to expand 284: macro calls in them. 1.1 root 285: 286: Most of the time, this has no effect. If the actual argument 1.1.1.3 root 287: contained any macro calls, they are expanded during the first scan. 1.1 root 288: The result therefore contains no macro calls, so the second scan does 1.1.1.3 root 289: not change it. If the actual argument were substituted as given, with 1.1 root 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 1.1.1.2 root 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. 1.1 root 300: 301: The prescan is not done when an argument is stringified or 1.1.1.3 root 302: concatenated. Thus, 1.1 root 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: 1.1.1.2 root 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 1.1 root 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 1.1.1.3 root 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 1.1 root 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 1.1.1.3 root 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. 1.1 root 344: 345: But prescan causes trouble in certain other cases of nested macro 1.1.1.3 root 346: calls. Here is an example: 1.1 root 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 1.1.1.2 root 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: 1.1 root 383: 384: #define xstr(s) str(s) 385: #define str(s) #s 386: #define foo 4 387: xstr (foo) 388: 1.1.1.2 root 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' 1.1.1.3 root 391: does not specify stringification or concatenation of the argument). 1.1.1.2 root 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'. 1.1 root 395: 396: 1.1.1.2 root 397: File: cpp.info, Node: Cascaded Macros, Next: Newlines in Args, Prev: Argument Prescan, Up: Macro Pitfalls 1.1 root 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: 1.1.1.2 root 408: This is not at all the same as defining `TABLESIZE' to be `1020'. 1.1 root 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: 1.1.1.2 root 413: It's only when you *use* `TABLESIZE' that the result of its expansion 414: is checked for more macro names. 1.1 root 415: 1.1.1.2 root 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 1.1 root 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: 1.1.1.5 root 426: Now `TABLESIZE' expands (in two stages) to `37'. (The `#undef' is to 427: prevent any warning about the nontrivial redefinition of `BUFSIZE'.) 1.1 root 428: 429: 1.1.1.2 root 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: 1.1 root 463: File: cpp.info, Node: Conditionals, Next: Combining Sources, Prev: Macros, Up: Top 464: 465: Conditionals 466: ============ 467: 1.1.1.6 root 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. 1.1 root 472: 473: A conditional in the C preprocessor resembles in some ways an `if' 1.1.1.2 root 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 1.1.1.3 root 477: differently from run to run, depending on the data it is operating on. 1.1.1.6 root 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 1.1.1.2 root 480: included in the program depending on the situation at the time of 481: compilation. 1.1 root 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. 1.1.1.2 root 489: * Assertions:: How and why to use assertions. 1.1.1.6 root 490: * Errors: #error Directive. Detecting inconsistent compilation parameters. 1.1 root 491: 492: 1.1.1.2 root 493: File: cpp.info, Node: Conditional Uses, Next: Conditional Syntax, Up: Conditionals 1.1 root 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 1.1.1.2 root 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 1.1.1.6 root 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. 1.1 root 509: 510: * You may want to be able to compile the same source file into two 1.1.1.2 root 511: different programs. Sometimes the difference between the programs 512: is that one makes frequent time-consuming consistency checks on its 1.1.1.5 root 513: intermediate data, or prints the values of those data for 514: debugging, while the other does not. 1.1 root 515: 516: * A conditional whose condition is always false is a good way to 1.1.1.2 root 517: exclude code from the program but keep it as a sort of comment for 518: future reference. 1.1 root 519: 520: Most simple programs that are intended to run on only one machine 1.1.1.6 root 521: will not need to use preprocessing conditionals. 1.1 root 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 1.1.1.6 root 530: directive": `#if', `#ifdef' or `#ifndef'. *Note Conditionals-Macros::, 1.1.1.2 root 531: for information on `#ifdef' and `#ifndef'; only `#if' is explained here. 1.1 root 532: 533: * Menu: 534: 1.1.1.6 root 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. 1.1 root 538: 539: 1.1.1.6 root 540: File: cpp.info, Node: #if Directive, Next: #else Directive, Up: Conditional Syntax 1.1 root 541: 1.1.1.6 root 542: The `#if' Directive 543: ................... 1.1 root 544: 1.1.1.6 root 545: The `#if' directive in its simplest form consists of 1.1 root 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 1.1.1.2 root 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. 1.1 root 573: 574: * Arithmetic operators for addition, subtraction, multiplication, 1.1.1.5 root 575: division, bitwise operations, shifts, comparisons, and logical 576: operations (`&&' and `||'). 1.1 root 577: 578: * Identifiers that are not macros, which are all treated as zero(!). 579: 1.1.1.2 root 580: * Macro calls. All macro calls in the expression are expanded before 581: actual computation of the expression's value begins. 1.1 root 582: 1.1.1.2 root 583: Note that `sizeof' operators and `enum'-type values are not allowed. 1.1 root 584: `enum'-type values, like all other identifiers that are not taken as 585: macro calls and expanded, are treated as zero. 586: 1.1.1.6 root 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. 1.1 root 592: 593: 1.1.1.6 root 594: File: cpp.info, Node: #else Directive, Next: #elif Directive, Prev: #if Directive, Up: Conditional Syntax 1.1 root 595: 1.1.1.6 root 596: The `#else' Directive 597: ..................... 1.1 root 598: 1.1.1.6 root 599: The `#else' directive can be added to a conditional to provide 1.1.1.2 root 600: alternative text to be used if the condition is false. This is what it 601: looks like: 1.1 root 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: 1.1.1.6 root 615: File: cpp.info, Node: #elif Directive, Prev: #else Directive, Up: Conditional Syntax 1.1 root 616: 1.1.1.6 root 617: The `#elif' Directive 618: ..................... 1.1 root 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: 1.1.1.6 root 633: Another conditional directive, `#elif', allows this to be abbreviated 1.1 root 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 1.1.1.6 root 646: matching `#endif' of its own. Like `#if', the `#elif' directive 647: includes an expression to be tested. 1.1 root 648: 649: The text following the `#elif' is processed only if the original 1.1.1.3 root 650: `#if'-condition failed and the `#elif' condition succeeds. More than 1.1 root 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 1.1.1.6 root 653: after the original `#if' and any previous `#elif' directives within it 1.1.1.2 root 654: have failed. `#else' is equivalent to `#elif 1', and `#else' is 1.1.1.6 root 655: allowed after any number of `#elif' directives, but `#elif' may not 656: follow `#else'. 1.1 root 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 1.1.1.5 root 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). 1.1 root 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: 1.1.1.5 root 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: 1.1 root 680: 1.1.1.2 root 681: File: cpp.info, Node: Conditionals-Macros, Next: Assertions, Prev: Deleted Code, Up: Conditionals 1.1 root 682: 683: Conditionals and Macros 684: ----------------------- 685: 1.1.1.2 root 686: Conditionals are useful in connection with macros or assertions, 687: because those are the only ways that an expression's value can vary 1.1.1.6 root 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. 1.1 root 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: 1.1.1.2 root 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, 1.1 root 712: 713: #if defined (vax) || defined (ns16000) 714: 1.1.1.5 root 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: 1.1.1.2 root 718: 719: #if #cpu (vax) || #cpu (ns16000) 1.1 root 720: 721: If a macro is defined and later undefined with `#undef', subsequent 1.1.1.2 root 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', 1.1 root 724: `defined' will recommence returning 1. 725: 1.1.1.5 root 726: Conditionals that test whether just one name is defined are very 1.1.1.6 root 727: common, so there are two special short conditional directives for this 1.1.1.2 root 728: case. 1.1 root 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 1.1.1.2 root 745: conditionals to avoid using a system feature on a machine where it 746: is not implemented. 1.1 root 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 1.1.1.2 root 751: program that is included as a header file in each source file. You 1.1.1.6 root 752: would use `BUFSIZE' in a preprocessing conditional in order to 1.1 root 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 1.1.1.3 root 760: the state of the macro with compiler command options. *Note 1.1 root 761: Invocation::. 762: 1.1.1.2 root 763: Assertions are usually predefined, but can be defined with 1.1.1.6 root 764: preprocessor directives or command-line options. 1.1.1.2 root 765: 1.1 root 766: 1.1.1.6 root 767: File: cpp.info, Node: Assertions, Next: #error Directive, Prev: Conditionals-Macros, Up: Conditionals 1.1.1.2 root 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 1.1.1.6 root 775: define them with preprocessing directives or command-line options. 1.1.1.2 root 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 1.1.1.3 root 783: an answer. The question is usually called the "predicate". An 1.1.1.2 root 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 1.1.1.3 root 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: 1.1.1.2 root 811: 812: #system (gnu) 813: #system (mach) 814: #system (mach 3) 815: #system (mach 3.SUBVERSION) 816: #system (hurd) 817: #system (hurd VERSION) 818: 1.1.1.4 root 819: and perhaps others. The alternatives with more or less version 1.1.1.2 root 820: information let you ask more or less detailed questions about the type 821: of system software. 822: 1.1.1.4 root 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: 1.1.1.2 root 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)' 1.1.1.3 root 837: is true. It also does not directly imply `system (mach)', but in GNU 838: C, that last will normally be asserted as well. 1.1.1.2 root 839: 1.1.1.4 root 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: 1.1.1.2 root 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: 1.1.1.6 root 867: File: cpp.info, Node: #error Directive, Prev: Assertions, Up: Conditionals 1.1 root 868: 1.1.1.6 root 869: The `#error' and `#warning' Directives 870: -------------------------------------- 1.1 root 871: 1.1.1.6 root 872: The directive `#error' causes the preprocessor to report a fatal 1.1.1.2 root 873: error. The rest of the line that follows `#error' is used as the error 874: message. 1.1 root 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: 1.1.1.5 root 881: #ifdef __vax__ 1.1 root 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 1.1.1.2 root 888: the installation in a consistent way, you can use conditionals to detect 889: an inconsistency and report it with `#error'. For example, 1.1 root 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: 1.1.1.6 root 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. 1.1 root 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: 1.1.1.6 root 904: File: cpp.info, Node: Combining Sources, Next: Other Directives, Prev: Conditionals, Up: Top 1.1 root 905: 906: Combining Source Files 907: ====================== 908: 1.1.1.2 root 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. 1.1 root 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 1.1.1.2 root 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. 1.1 root 919: 1.1.1.6 root 920: The C preprocessor builds on this feature by offering a directive by 1.1 root 921: which you can control the feature explicitly. This is useful when a 1.1.1.2 root 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 1.1.1.3 root 925: generated from scratch, other parts come from a standard parser file. 1.1.1.2 root 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 1.1.1.3 root 928: line numbers. Naturally you would like compiler error messages and 1.1.1.2 root 929: symbolic debuggers to know the original source file and line number of 930: each line in the `bison' input. 1.1 root 931: 1.1.1.6 root 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: 1.1 root 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 1.1.1.2 root 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. 1.1 root 949: 950: `#line ANYTHING ELSE' 1.1.1.3 root 951: ANYTHING ELSE is checked for macro calls, which are expanded. The 1.1.1.2 root 952: result should be a decimal integer constant followed optionally by 953: a string constant, as described above. 1.1 root 954: 1.1.1.6 root 955: `#line' directives alter the results of the `__FILE__' and 956: `__LINE__' predefined macros from that point on. *Note Standard 957: Predefined::. 1.1 root 958: 1.1.1.2 root 959: The output of the preprocessor (which is the input for the rest of 1.1.1.6 root 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::. 1.1.1.2 root 963: 1.1 root 964: 1.1.1.6 root 965: File: cpp.info, Node: Other Directives, Next: Output, Prev: Combining Sources, Up: Top 1.1 root 966: 1.1.1.6 root 967: Miscellaneous Preprocessing Directives 968: ====================================== 1.1 root 969: 1.1.1.6 root 970: This section describes three additional preprocessing directives. 971: They are not very useful, but are mentioned for completeness. 1.1 root 972: 1.1.1.6 root 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 1.1 root 976: preprocessor output. The primary significance of the existence of the 1.1.1.6 root 977: null directive is that an input line consisting of just a `#' will 1.1.1.3 root 978: produce no output, rather than a line of output containing just a `#'. 1.1.1.2 root 979: Supposedly some old C programs contain such lines. 1.1 root 980: 1.1.1.6 root 981: The ANSI standard specifies that the `#pragma' directive has an 1.1 root 982: arbitrary, implementation-defined effect. In the GNU C preprocessor, 1.1.1.6 root 983: `#pragma' directives are not used, except for `#pragma once' (*note 1.1.1.3 root 984: Once-Only::.). However, they are left in the preprocessor output, so 985: they are available to the compilation pass. 1.1 root 986: 1.1.1.6 root 987: The `#ident' directive is supported for compatibility with certain 1.1 root 988: other systems. It is followed by a line of text. On some systems, the 1.1.1.2 root 989: text is copied into a special place in the object file; on most systems, 1.1.1.6 root 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. 1.1 root 993: 994: 1.1.1.6 root 995: File: cpp.info, Node: Output, Next: Invocation, Prev: Other Directives, Up: Top 1.1 root 996: 997: C Preprocessor Output 998: ===================== 999: 1000: The output from the C preprocessor looks much like the input, except 1.1.1.6 root 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. 1.1 root 1005: 1006: Source file name and line number information is conveyed by lines of 1007: the form 1008: 1.1.1.2 root 1009: # LINENUM FILENAME FLAGS 1.1 root 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: 1.1.1.6 root 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: 1.1.1.2 root 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. 1.1 root 1029: 1.1.1.6 root 1030: `4' 1031: This indicates that the following text should be treated as C. 1032:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.