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