| This is Info file cpp.info, produced by Makeinfo version 1.68 from the |
| input file cpp.texi. |
| |
| This file documents the GNU C Preprocessor. |
| |
| Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995 Free Software |
| Foundation, Inc. |
| |
| Permission is granted to make and distribute verbatim copies of this |
| manual provided the copyright notice and this permission notice are |
| preserved on all copies. |
| |
| Permission is granted to copy and distribute modified versions of |
| this manual under the conditions for verbatim copying, provided also |
| that the entire resulting derived work is distributed under the terms |
| of a permission notice identical to this one. |
| |
| Permission is granted to copy and distribute translations of this |
| manual into another language, under the above conditions for modified |
| versions. |
| |
| |
| File: cpp.info, Node: Macro Pitfalls, Prev: Redefining, Up: Macros |
| |
| Pitfalls and Subtleties of Macros |
| --------------------------------- |
| |
| In this section we describe some special rules that apply to macros |
| and macro expansion, and point out certain cases in which the rules have |
| counterintuitive consequences that you must watch out for. |
| |
| * Menu: |
| |
| * Misnesting:: Macros can contain unmatched parentheses. |
| * Macro Parentheses:: Why apparently superfluous parentheses |
| may be necessary to avoid incorrect grouping. |
| * Swallow Semicolon:: Macros that look like functions |
| but expand into compound statements. |
| * Side Effects:: Unsafe macros that cause trouble when |
| arguments contain side effects. |
| * Self-Reference:: Macros whose definitions use the macros' own names. |
| * Argument Prescan:: Actual arguments are checked for macro calls |
| before they are substituted. |
| * Cascaded Macros:: Macros whose definitions use other macros. |
| * Newlines in Args:: Sometimes line numbers get confused. |
| |
| |
| File: cpp.info, Node: Misnesting, Next: Macro Parentheses, Prev: Macro Pitfalls, Up: Macro Pitfalls |
| |
| Improperly Nested Constructs |
| ............................ |
| |
| Recall that when a macro is called with arguments, the arguments are |
| substituted into the macro body and the result is checked, together with |
| the rest of the input file, for more macro calls. |
| |
| It is possible to piece together a macro call coming partially from |
| the macro body and partially from the actual arguments. For example, |
| |
| #define double(x) (2*(x)) |
| #define call_with_1(x) x(1) |
| |
| would expand `call_with_1 (double)' into `(2*(1))'. |
| |
| Macro definitions do not have to have balanced parentheses. By |
| writing an unbalanced open parenthesis in a macro body, it is possible |
| to create a macro call that begins inside the macro body but ends |
| outside of it. For example, |
| |
| #define strange(file) fprintf (file, "%s %d", |
| ... |
| strange(stderr) p, 35) |
| |
| This bizarre example expands to `fprintf (stderr, "%s %d", p, 35)'! |
| |
| |
| File: cpp.info, Node: Macro Parentheses, Next: Swallow Semicolon, Prev: Misnesting, Up: Macro Pitfalls |
| |
| Unintended Grouping of Arithmetic |
| ................................. |
| |
| You may have noticed that in most of the macro definition examples |
| shown above, each occurrence of a macro argument name had parentheses |
| around it. In addition, another pair of parentheses usually surround |
| the entire macro definition. Here is why it is best to write macros |
| that way. |
| |
| Suppose you define a macro as follows, |
| |
| #define ceil_div(x, y) (x + y - 1) / y |
| |
| whose purpose is to divide, rounding up. (One use for this operation is |
| to compute how many `int' objects are needed to hold a certain number |
| of `char' objects.) Then suppose it is used as follows: |
| |
| a = ceil_div (b & c, sizeof (int)); |
| |
| This expands into |
| |
| a = (b & c + sizeof (int) - 1) / sizeof (int); |
| |
| which does not do what is intended. The operator-precedence rules of C |
| make it equivalent to this: |
| |
| a = (b & (c + sizeof (int) - 1)) / sizeof (int); |
| |
| But what we want is this: |
| |
| a = ((b & c) + sizeof (int) - 1)) / sizeof (int); |
| |
| Defining the macro as |
| |
| #define ceil_div(x, y) ((x) + (y) - 1) / (y) |
| |
| provides the desired result. |
| |
| Unintended grouping can result in another way. Consider `sizeof |
| ceil_div(1, 2)'. That has the appearance of a C expression that would |
| compute the size of the type of `ceil_div (1, 2)', but in fact it means |
| something very different. Here is what it expands to: |
| |
| sizeof ((1) + (2) - 1) / (2) |
| |
| This would take the size of an integer and divide it by two. The |
| precedence rules have put the division outside the `sizeof' when it was |
| intended to be inside. |
| |
| Parentheses around the entire macro definition can prevent such |
| problems. Here, then, is the recommended way to define `ceil_div': |
| |
| #define ceil_div(x, y) (((x) + (y) - 1) / (y)) |
| |
| |
| File: cpp.info, Node: Swallow Semicolon, Next: Side Effects, Prev: Macro Parentheses, Up: Macro Pitfalls |
| |
| Swallowing the Semicolon |
| ........................ |
| |
| Often it is desirable to define a macro that expands into a compound |
| statement. Consider, for example, the following macro, that advances a |
| pointer (the argument `p' says where to find it) across whitespace |
| characters: |
| |
| #define SKIP_SPACES (p, limit) \ |
| { register char *lim = (limit); \ |
| while (p != lim) { \ |
| if (*p++ != ' ') { \ |
| p--; break; }}} |
| |
| Here Backslash-Newline is used to split the macro definition, which must |
| be a single line, so that it resembles the way such C code would be |
| laid out if not part of a macro definition. |
| |
| A call to this macro might be `SKIP_SPACES (p, lim)'. Strictly |
| speaking, the call expands to a compound statement, which is a complete |
| statement with no need for a semicolon to end it. But it looks like a |
| function call. So it minimizes confusion if you can use it like a |
| function call, writing a semicolon afterward, as in `SKIP_SPACES (p, |
| lim);' |
| |
| But this can cause trouble before `else' statements, because the |
| semicolon is actually a null statement. Suppose you write |
| |
| if (*p != 0) |
| SKIP_SPACES (p, lim); |
| else ... |
| |
| The presence of two statements--the compound statement and a null |
| statement--in between the `if' condition and the `else' makes invalid C |
| code. |
| |
| The definition of the macro `SKIP_SPACES' can be altered to solve |
| this problem, using a `do ... while' statement. Here is how: |
| |
| #define SKIP_SPACES (p, limit) \ |
| do { register char *lim = (limit); \ |
| while (p != lim) { \ |
| if (*p++ != ' ') { \ |
| p--; break; }}} \ |
| while (0) |
| |
| Now `SKIP_SPACES (p, lim);' expands into |
| |
| do {...} while (0); |
| |
| which is one statement. |
| |
| |
| File: cpp.info, Node: Side Effects, Next: Self-Reference, Prev: Swallow Semicolon, Up: Macro Pitfalls |
| |
| Duplication of Side Effects |
| ........................... |
| |
| Many C programs define a macro `min', for "minimum", like this: |
| |
| #define min(X, Y) ((X) < (Y) ? (X) : (Y)) |
| |
| When you use this macro with an argument containing a side effect, |
| as shown here, |
| |
| next = min (x + y, foo (z)); |
| |
| it expands as follows: |
| |
| next = ((x + y) < (foo (z)) ? (x + y) : (foo (z))); |
| |
| where `x + y' has been substituted for `X' and `foo (z)' for `Y'. |
| |
| The function `foo' is used only once in the statement as it appears |
| in the program, but the expression `foo (z)' has been substituted twice |
| into the macro expansion. As a result, `foo' might be called two times |
| when the statement is executed. If it has side effects or if it takes |
| a long time to compute, the results might not be what you intended. We |
| say that `min' is an "unsafe" macro. |
| |
| The best solution to this problem is to define `min' in a way that |
| computes the value of `foo (z)' only once. The C language offers no |
| standard way to do this, but it can be done with GNU C extensions as |
| follows: |
| |
| #define min(X, Y) \ |
| ({ typeof (X) __x = (X), __y = (Y); \ |
| (__x < __y) ? __x : __y; }) |
| |
| If you do not wish to use GNU C extensions, the only solution is to |
| be careful when *using* the macro `min'. For example, you can |
| calculate the value of `foo (z)', save it in a variable, and use that |
| variable in `min': |
| |
| #define min(X, Y) ((X) < (Y) ? (X) : (Y)) |
| ... |
| { |
| int tem = foo (z); |
| next = min (x + y, tem); |
| } |
| |
| (where we assume that `foo' returns type `int'). |
| |
| |
| File: cpp.info, Node: Self-Reference, Next: Argument Prescan, Prev: Side Effects, Up: Macro Pitfalls |
| |
| Self-Referential Macros |
| ....................... |
| |
| A "self-referential" macro is one whose name appears in its |
| definition. A special feature of ANSI Standard C is that the |
| self-reference is not considered a macro call. It is passed into the |
| preprocessor output unchanged. |
| |
| Let's consider an example: |
| |
| #define foo (4 + foo) |
| |
| where `foo' is also a variable in your program. |
| |
| Following the ordinary rules, each reference to `foo' will expand |
| into `(4 + foo)'; then this will be rescanned and will expand into `(4 |
| + (4 + foo))'; and so on until it causes a fatal error (memory full) in |
| the preprocessor. |
| |
| However, the special rule about self-reference cuts this process |
| short after one step, at `(4 + foo)'. Therefore, this macro definition |
| has the possibly useful effect of causing the program to add 4 to the |
| value of `foo' wherever `foo' is referred to. |
| |
| In most cases, it is a bad idea to take advantage of this feature. A |
| person reading the program who sees that `foo' is a variable will not |
| expect that it is a macro as well. The reader will come across the |
| identifier `foo' in the program and think its value should be that of |
| the variable `foo', whereas in fact the value is four greater. |
| |
| The special rule for self-reference applies also to "indirect" |
| self-reference. This is the case where a macro X expands to use a |
| macro `y', and the expansion of `y' refers to the macro `x'. The |
| resulting reference to `x' comes indirectly from the expansion of `x', |
| so it is a self-reference and is not further expanded. Thus, after |
| |
| #define x (4 + y) |
| #define y (2 * x) |
| |
| `x' would expand into `(4 + (2 * x))'. Clear? |
| |
| But suppose `y' is used elsewhere, not from the definition of `x'. |
| Then the use of `x' in the expansion of `y' is not a self-reference |
| because `x' is not "in progress". So it does expand. However, the |
| expansion of `x' contains a reference to `y', and that is an indirect |
| self-reference now because `y' is "in progress". The result is that |
| `y' expands to `(2 * (4 + y))'. |
| |
| It is not clear that this behavior would ever be useful, but it is |
| specified by the ANSI C standard, so you may need to understand it. |
| |
| |
| File: cpp.info, Node: Argument Prescan, Next: Cascaded Macros, Prev: Self-Reference, Up: Macro Pitfalls |
| |
| Separate Expansion of Macro Arguments |
| ..................................... |
| |
| We have explained that the expansion of a macro, including the |
| substituted actual arguments, is scanned over again for macro calls to |
| be expanded. |
| |
| What really happens is more subtle: first each actual argument text |
| is scanned separately for macro calls. Then the results of this are |
| substituted into the macro body to produce the macro expansion, and the |
| macro expansion is scanned again for macros to expand. |
| |
| The result is that the actual arguments are scanned *twice* to expand |
| macro calls in them. |
| |
| Most of the time, this has no effect. If the actual argument |
| contained any macro calls, they are expanded during the first scan. |
| The result therefore contains no macro calls, so the second scan does |
| not change it. If the actual argument were substituted as given, with |
| no prescan, the single remaining scan would find the same macro calls |
| and produce the same results. |
| |
| You might expect the double scan to change the results when a |
| self-referential macro is used in an actual argument of another macro |
| (*note Self-Reference::.): the self-referential macro would be expanded |
| once in the first scan, and a second time in the second scan. But this |
| is not what happens. The self-references that do not expand in the |
| first scan are marked so that they will not expand in the second scan |
| either. |
| |
| The prescan is not done when an argument is stringified or |
| concatenated. Thus, |
| |
| #define str(s) #s |
| #define foo 4 |
| str (foo) |
| |
| expands to `"foo"'. Once more, prescan has been prevented from having |
| any noticeable effect. |
| |
| More precisely, stringification and concatenation use the argument as |
| written, in un-prescanned form. The same actual argument would be used |
| in prescanned form if it is substituted elsewhere without |
| stringification or concatenation. |
| |
| #define str(s) #s lose(s) |
| #define foo 4 |
| str (foo) |
| |
| expands to `"foo" lose(4)'. |
| |
| You might now ask, "Why mention the prescan, if it makes no |
| difference? And why not skip it and make the preprocessor faster?" |
| The answer is that the prescan does make a difference in three special |
| cases: |
| |
| * Nested calls to a macro. |
| |
| * Macros that call other macros that stringify or concatenate. |
| |
| * Macros whose expansions contain unshielded commas. |
| |
| We say that "nested" calls to a macro occur when a macro's actual |
| argument contains a call to that very macro. For example, if `f' is a |
| macro that expects one argument, `f (f (1))' is a nested pair of calls |
| to `f'. The desired expansion is made by expanding `f (1)' and |
| substituting that into the definition of `f'. The prescan causes the |
| expected result to happen. Without the prescan, `f (1)' itself would |
| be substituted as an actual argument, and the inner use of `f' would |
| appear during the main scan as an indirect self-reference and would not |
| be expanded. Here, the prescan cancels an undesirable side effect (in |
| the medical, not computational, sense of the term) of the special rule |
| for self-referential macros. |
| |
| But prescan causes trouble in certain other cases of nested macro |
| calls. Here is an example: |
| |
| #define foo a,b |
| #define bar(x) lose(x) |
| #define lose(x) (1 + (x)) |
| |
| bar(foo) |
| |
| We would like `bar(foo)' to turn into `(1 + (foo))', which would then |
| turn into `(1 + (a,b))'. But instead, `bar(foo)' expands into |
| `lose(a,b)', and you get an error because `lose' requires a single |
| argument. In this case, the problem is easily solved by the same |
| parentheses that ought to be used to prevent misnesting of arithmetic |
| operations: |
| |
| #define foo (a,b) |
| #define bar(x) lose((x)) |
| |
| The problem is more serious when the operands of the macro are not |
| expressions; for example, when they are statements. Then parentheses |
| are unacceptable because they would make for invalid C code: |
| |
| #define foo { int a, b; ... } |
| |
| In GNU C you can shield the commas using the `({...})' construct which |
| turns a compound statement into an expression: |
| |
| #define foo ({ int a, b; ... }) |
| |
| Or you can rewrite the macro definition to avoid such commas: |
| |
| #define foo { int a; int b; ... } |
| |
| There is also one case where prescan is useful. It is possible to |
| use prescan to expand an argument and then stringify it--if you use two |
| levels of macros. Let's add a new macro `xstr' to the example shown |
| above: |
| |
| #define xstr(s) str(s) |
| #define str(s) #s |
| #define foo 4 |
| xstr (foo) |
| |
| This expands into `"4"', not `"foo"'. The reason for the difference |
| is that the argument of `xstr' is expanded at prescan (because `xstr' |
| does not specify stringification or concatenation of the argument). |
| The result of prescan then forms the actual argument for `str'. `str' |
| uses its argument without prescan because it performs stringification; |
| but it cannot prevent or undo the prescanning already done by `xstr'. |
| |
| |
| File: cpp.info, Node: Cascaded Macros, Next: Newlines in Args, Prev: Argument Prescan, Up: Macro Pitfalls |
| |
| Cascaded Use of Macros |
| ...................... |
| |
| A "cascade" of macros is when one macro's body contains a reference |
| to another macro. This is very common practice. For example, |
| |
| #define BUFSIZE 1020 |
| #define TABLESIZE BUFSIZE |
| |
| This is not at all the same as defining `TABLESIZE' to be `1020'. |
| The `#define' for `TABLESIZE' uses exactly the body you specify--in |
| this case, `BUFSIZE'--and does not check to see whether it too is the |
| name of a macro. |
| |
| It's only when you *use* `TABLESIZE' that the result of its expansion |
| is checked for more macro names. |
| |
| This makes a difference if you change the definition of `BUFSIZE' at |
| some point in the source file. `TABLESIZE', defined as shown, will |
| always expand using the definition of `BUFSIZE' that is currently in |
| effect: |
| |
| #define BUFSIZE 1020 |
| #define TABLESIZE BUFSIZE |
| #undef BUFSIZE |
| #define BUFSIZE 37 |
| |
| Now `TABLESIZE' expands (in two stages) to `37'. (The `#undef' is to |
| prevent any warning about the nontrivial redefinition of `BUFSIZE'.) |
| |
| |
| File: cpp.info, Node: Newlines in Args, Prev: Cascaded Macros, Up: Macro Pitfalls |
| |
| Newlines in Macro Arguments |
| --------------------------- |
| |
| Traditional macro processing carries forward all newlines in macro |
| arguments into the expansion of the macro. This means that, if some of |
| the arguments are substituted more than once, or not at all, or out of |
| order, newlines can be duplicated, lost, or moved around within the |
| expansion. If the expansion consists of multiple statements, then the |
| effect is to distort the line numbers of some of these statements. The |
| result can be incorrect line numbers, in error messages or displayed in |
| a debugger. |
| |
| The GNU C preprocessor operating in ANSI C mode adjusts appropriately |
| for multiple use of an argument--the first use expands all the |
| newlines, and subsequent uses of the same argument produce no newlines. |
| But even in this mode, it can produce incorrect line numbering if |
| arguments are used out of order, or not used at all. |
| |
| Here is an example illustrating this problem: |
| |
| #define ignore_second_arg(a,b,c) a; c |
| |
| ignore_second_arg (foo (), |
| ignored (), |
| syntax error); |
| |
| The syntax error triggered by the tokens `syntax error' results in an |
| error message citing line four, even though the statement text comes |
| from line five. |
| |
| |
| File: cpp.info, Node: Conditionals, Next: Combining Sources, Prev: Macros, Up: Top |
| |
| Conditionals |
| ============ |
| |
| In a macro processor, a "conditional" is a directive that allows a |
| part of the program to be ignored during compilation, on some |
| conditions. In the C preprocessor, a conditional can test either an |
| arithmetic expression or whether a name is defined as a macro. |
| |
| A conditional in the C preprocessor resembles in some ways an `if' |
| statement in C, but it is important to understand the difference between |
| them. The condition in an `if' statement is tested during the execution |
| of your program. Its purpose is to allow your program to behave |
| differently from run to run, depending on the data it is operating on. |
| The condition in a preprocessing conditional directive is tested when |
| your program is compiled. Its purpose is to allow different code to be |
| included in the program depending on the situation at the time of |
| compilation. |
| |
| * Menu: |
| |
| * Uses: Conditional Uses. What conditionals are for. |
| * Syntax: Conditional Syntax. How conditionals are written. |
| * Deletion: Deleted Code. Making code into a comment. |
| * Macros: Conditionals-Macros. Why conditionals are used with macros. |
| * Assertions:: How and why to use assertions. |
| * Errors: #error Directive. Detecting inconsistent compilation parameters. |
| |
| |
| File: cpp.info, Node: Conditional Uses, Next: Conditional Syntax, Up: Conditionals |
| |
| Why Conditionals are Used |
| ------------------------- |
| |
| Generally there are three kinds of reason to use a conditional. |
| |
| * A program may need to use different code depending on the machine |
| or operating system it is to run on. In some cases the code for |
| one operating system may be erroneous on another operating system; |
| for example, it might refer to library routines that do not exist |
| on the other system. When this happens, it is not enough to avoid |
| executing the invalid code: merely having it in the program makes |
| it impossible to link the program and run it. With a |
| preprocessing conditional, the offending code can be effectively |
| excised from the program when it is not valid. |
| |
| * You may want to be able to compile the same source file into two |
| different programs. Sometimes the difference between the programs |
| is that one makes frequent time-consuming consistency checks on its |
| intermediate data, or prints the values of those data for |
| debugging, while the other does not. |
| |
| * A conditional whose condition is always false is a good way to |
| exclude code from the program but keep it as a sort of comment for |
| future reference. |
| |
| Most simple programs that are intended to run on only one machine |
| will not need to use preprocessing conditionals. |
| |
| |
| File: cpp.info, Node: Conditional Syntax, Next: Deleted Code, Prev: Conditional Uses, Up: Conditionals |
| |
| Syntax of Conditionals |
| ---------------------- |
| |
| A conditional in the C preprocessor begins with a "conditional |
| directive": `#if', `#ifdef' or `#ifndef'. *Note Conditionals-Macros::, |
| for information on `#ifdef' and `#ifndef'; only `#if' is explained here. |
| |
| * Menu: |
| |
| * If: #if Directive. Basic conditionals using `#if' and `#endif'. |
| * Else: #else Directive. Including some text if the condition fails. |
| * Elif: #elif Directive. Testing several alternative possibilities. |
| |
| |
| File: cpp.info, Node: #if Directive, Next: #else Directive, Up: Conditional Syntax |
| |
| The `#if' Directive |
| ................... |
| |
| The `#if' directive in its simplest form consists of |
| |
| #if EXPRESSION |
| CONTROLLED TEXT |
| #endif /* EXPRESSION */ |
| |
| The comment following the `#endif' is not required, but it is a good |
| practice because it helps people match the `#endif' to the |
| corresponding `#if'. Such comments should always be used, except in |
| short conditionals that are not nested. In fact, you can put anything |
| at all after the `#endif' and it will be ignored by the GNU C |
| preprocessor, but only comments are acceptable in ANSI Standard C. |
| |
| EXPRESSION is a C expression of integer type, subject to stringent |
| restrictions. It may contain |
| |
| * Integer constants, which are all regarded as `long' or `unsigned |
| long'. |
| |
| * Character constants, which are interpreted according to the |
| character set and conventions of the machine and operating system |
| on which the preprocessor is running. The GNU C preprocessor uses |
| the C data type `char' for these character constants; therefore, |
| whether some character codes are negative is determined by the C |
| compiler used to compile the preprocessor. If it treats `char' as |
| signed, then character codes large enough to set the sign bit will |
| be considered negative; otherwise, no character code is considered |
| negative. |
| |
| * Arithmetic operators for addition, subtraction, multiplication, |
| division, bitwise operations, shifts, comparisons, and logical |
| operations (`&&' and `||'). |
| |
| * Identifiers that are not macros, which are all treated as zero(!). |
| |
| * Macro calls. All macro calls in the expression are expanded before |
| actual computation of the expression's value begins. |
| |
| Note that `sizeof' operators and `enum'-type values are not allowed. |
| `enum'-type values, like all other identifiers that are not taken as |
| macro calls and expanded, are treated as zero. |
| |
| The CONTROLLED TEXT inside of a conditional can include |
| preprocessing directives. Then the directives inside the conditional |
| are obeyed only if that branch of the conditional succeeds. The text |
| can also contain other conditional groups. However, the `#if' and |
| `#endif' directives must balance. |
| |
| |
| File: cpp.info, Node: #else Directive, Next: #elif Directive, Prev: #if Directive, Up: Conditional Syntax |
| |
| The `#else' Directive |
| ..................... |
| |
| The `#else' directive can be added to a conditional to provide |
| alternative text to be used if the condition is false. This is what it |
| looks like: |
| |
| #if EXPRESSION |
| TEXT-IF-TRUE |
| #else /* Not EXPRESSION */ |
| TEXT-IF-FALSE |
| #endif /* Not EXPRESSION */ |
| |
| If EXPRESSION is nonzero, and thus the TEXT-IF-TRUE is active, then |
| `#else' acts like a failing conditional and the TEXT-IF-FALSE is |
| ignored. Contrariwise, if the `#if' conditional fails, the |
| TEXT-IF-FALSE is considered included. |
| |
| |
| File: cpp.info, Node: #elif Directive, Prev: #else Directive, Up: Conditional Syntax |
| |
| The `#elif' Directive |
| ..................... |
| |
| One common case of nested conditionals is used to check for more |
| than two possible alternatives. For example, you might have |
| |
| #if X == 1 |
| ... |
| #else /* X != 1 */ |
| #if X == 2 |
| ... |
| #else /* X != 2 */ |
| ... |
| #endif /* X != 2 */ |
| #endif /* X != 1 */ |
| |
| Another conditional directive, `#elif', allows this to be abbreviated |
| as follows: |
| |
| #if X == 1 |
| ... |
| #elif X == 2 |
| ... |
| #else /* X != 2 and X != 1*/ |
| ... |
| #endif /* X != 2 and X != 1*/ |
| |
| `#elif' stands for "else if". Like `#else', it goes in the middle |
| of a `#if'-`#endif' pair and subdivides it; it does not require a |
| matching `#endif' of its own. Like `#if', the `#elif' directive |
| includes an expression to be tested. |
| |
| The text following the `#elif' is processed only if the original |
| `#if'-condition failed and the `#elif' condition succeeds. More than |
| one `#elif' can go in the same `#if'-`#endif' group. Then the text |
| after each `#elif' is processed only if the `#elif' condition succeeds |
| after the original `#if' and any previous `#elif' directives within it |
| have failed. `#else' is equivalent to `#elif 1', and `#else' is |
| allowed after any number of `#elif' directives, but `#elif' may not |
| follow `#else'. |
| |
| |
| File: cpp.info, Node: Deleted Code, Next: Conditionals-Macros, Prev: Conditional Syntax, Up: Conditionals |
| |
| Keeping Deleted Code for Future Reference |
| ----------------------------------------- |
| |
| If you replace or delete a part of the program but want to keep the |
| old code around as a comment for future reference, the easy way to do |
| this is to put `#if 0' before it and `#endif' after it. This is better |
| than using comment delimiters `/*' and `*/' since those won't work if |
| the code already contains comments (C comments do not nest). |
| |
| This works even if the code being turned off contains conditionals, |
| but they must be entire conditionals (balanced `#if' and `#endif'). |
| |
| Conversely, do not use `#if 0' for comments which are not C code. |
| Use the comment delimiters `/*' and `*/' instead. The interior of `#if |
| 0' must consist of complete tokens; in particular, singlequote |
| characters must balance. But comments often contain unbalanced |
| singlequote characters (known in English as apostrophes). These |
| confuse `#if 0'. They do not confuse `/*'. |
| |
| |
| File: cpp.info, Node: Conditionals-Macros, Next: Assertions, Prev: Deleted Code, Up: Conditionals |
| |
| Conditionals and Macros |
| ----------------------- |
| |
| Conditionals are useful in connection with macros or assertions, |
| because those are the only ways that an expression's value can vary |
| from one compilation to another. A `#if' directive whose expression |
| uses no macros or assertions is equivalent to `#if 1' or `#if 0'; you |
| might as well determine which one, by computing the value of the |
| expression yourself, and then simplify the program. |
| |
| For example, here is a conditional that tests the expression |
| `BUFSIZE == 1020', where `BUFSIZE' must be a macro. |
| |
| #if BUFSIZE == 1020 |
| printf ("Large buffers!\n"); |
| #endif /* BUFSIZE is large */ |
| |
| (Programmers often wish they could test the size of a variable or |
| data type in `#if', but this does not work. The preprocessor does not |
| understand `sizeof', or typedef names, or even the type keywords such |
| as `int'.) |
| |
| The special operator `defined' is used in `#if' expressions to test |
| whether a certain name is defined as a macro. Either `defined NAME' or |
| `defined (NAME)' is an expression whose value is 1 if NAME is defined |
| as macro at the current point in the program, and 0 otherwise. For the |
| `defined' operator it makes no difference what the definition of the |
| macro is; all that matters is whether there is a definition. Thus, for |
| example, |
| |
| #if defined (vax) || defined (ns16000) |
| |
| would succeed if either of the names `vax' and `ns16000' is defined as |
| a macro. You can test the same condition using assertions (*note |
| Assertions::.), like this: |
| |
| #if #cpu (vax) || #cpu (ns16000) |
| |
| If a macro is defined and later undefined with `#undef', subsequent |
| use of the `defined' operator returns 0, because the name is no longer |
| defined. If the macro is defined again with another `#define', |
| `defined' will recommence returning 1. |
| |
| Conditionals that test whether just one name is defined are very |
| common, so there are two special short conditional directives for this |
| case. |
| |
| `#ifdef NAME' |
| is equivalent to `#if defined (NAME)'. |
| |
| `#ifndef NAME' |
| is equivalent to `#if ! defined (NAME)'. |
| |
| Macro definitions can vary between compilations for several reasons. |
| |
| * Some macros are predefined on each kind of machine. For example, |
| on a Vax, the name `vax' is a predefined macro. On other |
| machines, it would not be defined. |
| |
| * Many more macros are defined by system header files. Different |
| systems and machines define different macros, or give them |
| different values. It is useful to test these macros with |
| conditionals to avoid using a system feature on a machine where it |
| is not implemented. |
| |
| * Macros are a common way of allowing users to customize a program |
| for different machines or applications. For example, the macro |
| `BUFSIZE' might be defined in a configuration file for your |
| program that is included as a header file in each source file. You |
| would use `BUFSIZE' in a preprocessing conditional in order to |
| generate different code depending on the chosen configuration. |
| |
| * Macros can be defined or undefined with `-D' and `-U' command |
| options when you compile the program. You can arrange to compile |
| the same source file into two different programs by choosing a |
| macro name to specify which program you want, writing conditionals |
| to test whether or how this macro is defined, and then controlling |
| the state of the macro with compiler command options. *Note |
| Invocation::. |
| |
| Assertions are usually predefined, but can be defined with |
| preprocessor directives or command-line options. |
| |
| |
| File: cpp.info, Node: Assertions, Next: #error Directive, Prev: Conditionals-Macros, Up: Conditionals |
| |
| Assertions |
| ---------- |
| |
| "Assertions" are a more systematic alternative to macros in writing |
| conditionals to test what sort of computer or system the compiled |
| program will run on. Assertions are usually predefined, but you can |
| define them with preprocessing directives or command-line options. |
| |
| The macros traditionally used to describe the type of target are not |
| classified in any way according to which question they answer; they may |
| indicate a hardware architecture, a particular hardware model, an |
| operating system, a particular version of an operating system, or |
| specific configuration options. These are jumbled together in a single |
| namespace. In contrast, each assertion consists of a named question and |
| an answer. The question is usually called the "predicate". An |
| assertion looks like this: |
| |
| #PREDICATE (ANSWER) |
| |
| You must use a properly formed identifier for PREDICATE. The value of |
| ANSWER can be any sequence of words; all characters are significant |
| except for leading and trailing whitespace, and differences in internal |
| whitespace sequences are ignored. Thus, `x + y' is different from |
| `x+y' but equivalent to `x + y'. `)' is not allowed in an answer. |
| |
| Here is a conditional to test whether the answer ANSWER is asserted |
| for the predicate PREDICATE: |
| |
| #if #PREDICATE (ANSWER) |
| |
| There may be more than one answer asserted for a given predicate. If |
| you omit the answer, you can test whether *any* answer is asserted for |
| PREDICATE: |
| |
| #if #PREDICATE |
| |
| Most of the time, the assertions you test will be predefined |
| assertions. GNU C provides three predefined predicates: `system', |
| `cpu', and `machine'. `system' is for assertions about the type of |
| software, `cpu' describes the type of computer architecture, and |
| `machine' gives more information about the computer. For example, on a |
| GNU system, the following assertions would be true: |
| |
| #system (gnu) |
| #system (mach) |
| #system (mach 3) |
| #system (mach 3.SUBVERSION) |
| #system (hurd) |
| #system (hurd VERSION) |
| |
| and perhaps others. The alternatives with more or less version |
| information let you ask more or less detailed questions about the type |
| of system software. |
| |
| On a Unix system, you would find `#system (unix)' and perhaps one of: |
| `#system (aix)', `#system (bsd)', `#system (hpux)', `#system (lynx)', |
| `#system (mach)', `#system (posix)', `#system (svr3)', `#system |
| (svr4)', or `#system (xpg4)' with possible version numbers following. |
| |
| Other values for `system' are `#system (mvs)' and `#system (vms)'. |
| |
| *Portability note:* Many Unix C compilers provide only one answer |
| for the `system' assertion: `#system (unix)', if they support |
| assertions at all. This is less than useful. |
| |
| An assertion with a multi-word answer is completely different from |
| several assertions with individual single-word answers. For example, |
| the presence of `system (mach 3.0)' does not mean that `system (3.0)' |
| is true. It also does not directly imply `system (mach)', but in GNU |
| C, that last will normally be asserted as well. |
| |
| The current list of possible assertion values for `cpu' is: `#cpu |
| (a29k)', `#cpu (alpha)', `#cpu (arm)', `#cpu (clipper)', `#cpu |
| (convex)', `#cpu (elxsi)', `#cpu (tron)', `#cpu (h8300)', `#cpu |
| (i370)', `#cpu (i386)', `#cpu (i860)', `#cpu (i960)', `#cpu (m68k)', |
| `#cpu (m88k)', `#cpu (mips)', `#cpu (ns32k)', `#cpu (hppa)', `#cpu |
| (pyr)', `#cpu (ibm032)', `#cpu (rs6000)', `#cpu (sh)', `#cpu (sparc)', |
| `#cpu (spur)', `#cpu (tahoe)', `#cpu (vax)', `#cpu (we32000)'. |
| |
| You can create assertions within a C program using `#assert', like |
| this: |
| |
| #assert PREDICATE (ANSWER) |
| |
| (Note the absence of a `#' before PREDICATE.) |
| |
| Each time you do this, you assert a new true answer for PREDICATE. |
| Asserting one answer does not invalidate previously asserted answers; |
| they all remain true. The only way to remove an assertion is with |
| `#unassert'. `#unassert' has the same syntax as `#assert'. You can |
| also remove all assertions about PREDICATE like this: |
| |
| #unassert PREDICATE |
| |
| You can also add or cancel assertions using command options when you |
| run `gcc' or `cpp'. *Note Invocation::. |
| |
| |
| File: cpp.info, Node: #error Directive, Prev: Assertions, Up: Conditionals |
| |
| The `#error' and `#warning' Directives |
| -------------------------------------- |
| |
| The directive `#error' causes the preprocessor to report a fatal |
| error. The rest of the line that follows `#error' is used as the error |
| message. The line must consist of complete tokens. |
| |
| You would use `#error' inside of a conditional that detects a |
| combination of parameters which you know the program does not properly |
| support. For example, if you know that the program will not run |
| properly on a Vax, you might write |
| |
| #ifdef __vax__ |
| #error "Won't work on Vaxen. See comments at get_last_object." |
| #endif |
| |
| *Note Nonstandard Predefined::, for why this works. |
| |
| If you have several configuration parameters that must be set up by |
| the installation in a consistent way, you can use conditionals to detect |
| an inconsistency and report it with `#error'. For example, |
| |
| #if HASH_TABLE_SIZE % 2 == 0 || HASH_TABLE_SIZE % 3 == 0 \ |
| || HASH_TABLE_SIZE % 5 == 0 |
| #error HASH_TABLE_SIZE should not be divisible by a small prime |
| #endif |
| |
| The directive `#warning' is like the directive `#error', but causes |
| the preprocessor to issue a warning and continue preprocessing. The |
| rest of the line that follows `#warning' is used as the warning message. |
| |
| You might use `#warning' in obsolete header files, with a message |
| directing the user to the header file which should be used instead. |
| |
| |
| File: cpp.info, Node: Combining Sources, Next: Other Directives, Prev: Conditionals, Up: Top |
| |
| Combining Source Files |
| ====================== |
| |
| One of the jobs of the C preprocessor is to inform the C compiler of |
| where each line of C code came from: which source file and which line |
| number. |
| |
| C code can come from multiple source files if you use `#include'; |
| both `#include' and the use of conditionals and macros can cause the |
| line number of a line in the preprocessor output to be different from |
| the line's number in the original source file. You will appreciate the |
| value of making both the C compiler (in error messages) and symbolic |
| debuggers such as GDB use the line numbers in your source file. |
| |
| The C preprocessor builds on this feature by offering a directive by |
| which you can control the feature explicitly. This is useful when a |
| file for input to the C preprocessor is the output from another program |
| such as the `bison' parser generator, which operates on another file |
| that is the true source file. Parts of the output from `bison' are |
| generated from scratch, other parts come from a standard parser file. |
| The rest are copied nearly verbatim from the source file, but their |
| line numbers in the `bison' output are not the same as their original |
| line numbers. Naturally you would like compiler error messages and |
| symbolic debuggers to know the original source file and line number of |
| each line in the `bison' input. |
| |
| `bison' arranges this by writing `#line' directives into the output |
| file. `#line' is a directive that specifies the original line number |
| and source file name for subsequent input in the current preprocessor |
| input file. `#line' has three variants: |
| |
| `#line LINENUM' |
| Here LINENUM is a decimal integer constant. This specifies that |
| the line number of the following line of input, in its original |
| source file, was LINENUM. |
| |
| `#line LINENUM FILENAME' |
| Here LINENUM is a decimal integer constant and FILENAME is a |
| string constant. This specifies that the following line of input |
| came originally from source file FILENAME and its line number there |
| was LINENUM. Keep in mind that FILENAME is not just a file name; |
| it is surrounded by doublequote characters so that it looks like a |
| string constant. |
| |
| `#line ANYTHING ELSE' |
| ANYTHING ELSE is checked for macro calls, which are expanded. The |
| result should be a decimal integer constant followed optionally by |
| a string constant, as described above. |
| |
| `#line' directives alter the results of the `__FILE__' and |
| `__LINE__' predefined macros from that point on. *Note Standard |
| Predefined::. |
| |
| The output of the preprocessor (which is the input for the rest of |
| the compiler) contains directives that look much like `#line' |
| directives. They start with just `#' instead of `#line', but this is |
| followed by a line number and file name as in `#line'. *Note Output::. |
| |
| |
| File: cpp.info, Node: Other Directives, Next: Output, Prev: Combining Sources, Up: Top |
| |
| Miscellaneous Preprocessing Directives |
| ====================================== |
| |
| This section describes three additional preprocessing directives. |
| They are not very useful, but are mentioned for completeness. |
| |
| The "null directive" consists of a `#' followed by a Newline, with |
| only whitespace (including comments) in between. A null directive is |
| understood as a preprocessing directive but has no effect on the |
| preprocessor output. The primary significance of the existence of the |
| null directive is that an input line consisting of just a `#' will |
| produce no output, rather than a line of output containing just a `#'. |
| Supposedly some old C programs contain such lines. |
| |
| The ANSI standard specifies that the effect of the `#pragma' |
| directive is implementation-defined. In the GNU C preprocessor, |
| `#pragma' directives are not used, except for `#pragma once' (*note |
| Once-Only::.). However, they are left in the preprocessor output, so |
| they are available to the compilation pass. |
| |
| The `#ident' directive is supported for compatibility with certain |
| other systems. It is followed by a line of text. On some systems, the |
| text is copied into a special place in the object file; on most systems, |
| the text is ignored and this directive has no effect. Typically |
| `#ident' is only used in header files supplied with those systems where |
| it is meaningful. |
| |
| |
| File: cpp.info, Node: Output, Next: Invocation, Prev: Other Directives, Up: Top |
| |
| C Preprocessor Output |
| ===================== |
| |
| The output from the C preprocessor looks much like the input, except |
| that all preprocessing directive lines have been replaced with blank |
| lines and all comments with spaces. Whitespace within a line is not |
| altered; however, unless `-traditional' is used, spaces may be inserted |
| into the expansions of macro calls to prevent tokens from being |
| concatenated. |
| |
| Source file name and line number information is conveyed by lines of |
| the form |
| |
| # LINENUM FILENAME FLAGS |
| |
| which are inserted as needed into the middle of the input (but never |
| within a string or character constant). Such a line means that the |
| following line originated in file FILENAME at line LINENUM. |
| |
| After the file name comes zero or more flags, which are `1', `2', |
| `3', or `4'. If there are multiple flags, spaces separate them. Here |
| is what the flags mean: |
| |
| `1' |
| This indicates the start of a new file. |
| |
| `2' |
| This indicates returning to a file (after having included another |
| file). |
| |
| `3' |
| This indicates that the following text comes from a system header |
| file, so certain warnings should be suppressed. |
| |
| `4' |
| This indicates that the following text should be treated as C. |
| |