![[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.5 root 1: This is Info file cpp.info, produced by Makeinfo-1.55 from the input
1.1.1.2 root 2: 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.