![[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 [Apple XNU] / GNUtools / cc|
Return to cpp.info-2 CVS log | Up to [Apple XNU] / GNUtools / cc |
1.1 root 1: This is Info file cpp.info, produced by Makeinfo-1.54 from the input
2: file cpp.texi.
3:
4: This file documents the GNU C Preprocessor.
5:
6: Copyright 1987, 1989, 1991, 1992, 1993 Free Software Foundation, Inc.
7:
8: Permission is granted to make and distribute verbatim copies of this
9: manual provided the copyright notice and this permission notice are
10: 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 must
39: be a single line, so that it resembles the way such C code would be
40: 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 C
58: 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 twice
99: into the macro expansion. As a result, `foo' might be called two times
100: when the statement is executed. If it has side effects or if it takes
101: a long time to compute, the results might not be what you intended. We
102: 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) in
147: 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. A
155: person reading the program who sees that `foo' is a variable will not
156: 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 the expansion of `y' refers to the macro `x'. The
163: resulting reference to `x' comes indirectly from the expansion of `x',
164: so it is 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 the
194: macro expansion is scanned again for macros to expand.
195:
196: The result is that the actual arguments are scanned *twice* to expand
197: 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 expanded
209: once in the first scan, and a second time in the second scan. But this
210: is not what happens. The self-references that do not expand in the
211: first scan are marked so that they will not expand in the second scan
212: 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 as
225: written, in un-prescanned form. The same actual argument would be used
226: 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 two
294: levels of macros. Let's add a new macro `xstr' to the example shown
295: 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 difference
303: is that the argument of `xstr' is expanded at prescan (because `xstr'
304: does not specify stringification or concatenation of the argument).
305: The result of prescan then forms the actual argument for `str'. `str'
306: uses its argument without prescan because it performs stringification;
307: but it cannot prevent or undo the prescanning already done by `xstr'.
308:
309:
310: File: cpp.info, Node: Cascaded Macros, Next: Newlines in Args, Prev: Argument Prescan, Up: Macro Pitfalls
311:
312: Cascaded Use of Macros
313: ......................
314:
315: A "cascade" of macros is when one macro's body contains a reference
316: to another macro. This is very common practice. For example,
317:
318: #define BUFSIZE 1020
319: #define TABLESIZE BUFSIZE
320:
321: This is not at all the same as defining `TABLESIZE' to be `1020'.
322: The `#define' for `TABLESIZE' uses exactly the body you specify--in
323: this case, `BUFSIZE'--and does not check to see whether it too is the
324: name of a macro.
325:
326: It's only when you *use* `TABLESIZE' that the result of its expansion
327: is checked for more macro names.
328:
329: This makes a difference if you change the definition of `BUFSIZE' at
330: some point in the source file. `TABLESIZE', defined as shown, will
331: always expand using the definition of `BUFSIZE' that is currently in
332: effect:
333:
334: #define BUFSIZE 1020
335: #define TABLESIZE BUFSIZE
336: #undef BUFSIZE
337: #define BUFSIZE 37
338:
339: Now `TABLESIZE' expands (in two stages) to `37'.
340:
341:
342: File: cpp.info, Node: Newlines in Args, Prev: Cascaded Macros, Up: Macro Pitfalls
343:
344: Newlines in Macro Arguments
345: ---------------------------
346:
347: Traditional macro processing carries forward all newlines in macro
348: arguments into the expansion of the macro. This means that, if some of
349: the arguments are substituted more than once, or not at all, or out of
350: order, newlines can be duplicated, lost, or moved around within the
351: expansion. If the expansion consists of multiple statements, then the
352: effect is to distort the line numbers of some of these statements. The
353: result can be incorrect line numbers, in error messages or displayed in
354: a debugger.
355:
356: The GNU C preprocessor operating in ANSI C mode adjusts appropriately
357: for multiple use of an argument--the first use expands all the
358: newlines, and subsequent uses of the same argument produce no newlines.
359: But even in this mode, it can produce incorrect line numbering if
360: arguments are used out of order, or not used at all.
361:
362: Here is an example illustrating this problem:
363:
364: #define ignore_second_arg(a,b,c) a; c
365:
366: ignore_second_arg (foo (),
367: ignored (),
368: syntax error);
369:
370: The syntax error triggered by the tokens `syntax error' results in an
371: error message citing line four, even though the statement text comes
372: from line five.
373:
374:
375: File: cpp.info, Node: Conditionals, Next: Combining Sources, Prev: Macros, Up: Top
376:
377: Conditionals
378: ============
379:
380: In a macro processor, a "conditional" is a command that allows a part
381: of the program to be ignored during compilation, on some conditions.
382: In the C preprocessor, a conditional can test either an arithmetic
383: expression or whether a name is defined as a macro.
384:
385: A conditional in the C preprocessor resembles in some ways an `if'
386: statement in C, but it is important to understand the difference between
387: them. The condition in an `if' statement is tested during the execution
388: of your program. Its purpose is to allow your program to behave
389: differently from run to run, depending on the data it is operating on.
390: The condition in a preprocessor conditional command is tested when your
391: program is compiled. Its purpose is to allow different code to be
392: included in the program depending on the situation at the time of
393: compilation.
394:
395: * Menu:
396:
397: * Uses: Conditional Uses. What conditionals are for.
398: * Syntax: Conditional Syntax. How conditionals are written.
399: * Deletion: Deleted Code. Making code into a comment.
400: * Macros: Conditionals-Macros. Why conditionals are used with macros.
401: * Assertions:: How and why to use assertions.
402: * Errors: #error Command. Detecting inconsistent compilation parameters.
403:
404:
405: File: cpp.info, Node: Conditional Uses, Next: Conditional Syntax, Up: Conditionals
406:
407: Why Conditionals are Used
408: -------------------------
409:
410: Generally there are three kinds of reason to use a conditional.
411:
412: * A program may need to use different code depending on the machine
413: or operating system it is to run on. In some cases the code for
414: one operating system may be erroneous on another operating system;
415: for example, it might refer to library routines that do not exist
416: on the other system. When this happens, it is not enough to avoid
417: executing the invalid code: merely having it in the program makes
418: it impossible to link the program and run it. With a preprocessor
419: conditional, the offending code can be effectively excised from
420: the program when it is not valid.
421:
422: * You may want to be able to compile the same source file into two
423: different programs. Sometimes the difference between the programs
424: is that one makes frequent time-consuming consistency checks on its
425: intermediate data while the other does not.
426:
427: * A conditional whose condition is always false is a good way to
428: exclude code from the program but keep it as a sort of comment for
429: future reference.
430:
431: Most simple programs that are intended to run on only one machine
432: will not need to use preprocessor conditionals.
433:
434:
435: File: cpp.info, Node: Conditional Syntax, Next: Deleted Code, Prev: Conditional Uses, Up: Conditionals
436:
437: Syntax of Conditionals
438: ----------------------
439:
440: A conditional in the C preprocessor begins with a "conditional
441: command": `#if', `#ifdef' or `#ifndef'. *Note Conditionals-Macros::,
442: for information on `#ifdef' and `#ifndef'; only `#if' is explained here.
443:
444: * Menu:
445:
446: * If: #if Command. Basic conditionals using `#if' and `#endif'.
447: * Else: #else Command. Including some text if the condition fails.
448: * Elif: #elif Command. Testing several alternative possibilities.
449:
450:
451: File: cpp.info, Node: #if Command, Next: #else Command, Up: Conditional Syntax
452:
453: The `#if' Command
454: .................
455:
456: The `#if' command in its simplest form consists of
457:
458: #if EXPRESSION
459: CONTROLLED TEXT
460: #endif /* EXPRESSION */
461:
462: The comment following the `#endif' is not required, but it is a good
463: practice because it helps people match the `#endif' to the
464: corresponding `#if'. Such comments should always be used, except in
465: short conditionals that are not nested. In fact, you can put anything
466: at all after the `#endif' and it will be ignored by the GNU C
467: preprocessor, but only comments are acceptable in ANSI Standard C.
468:
469: EXPRESSION is a C expression of integer type, subject to stringent
470: restrictions. It may contain
471:
472: * Integer constants, which are all regarded as `long' or `unsigned
473: long'.
474:
475: * Character constants, which are interpreted according to the
476: character set and conventions of the machine and operating system
477: on which the preprocessor is running. The GNU C preprocessor uses
478: the C data type `char' for these character constants; therefore,
479: whether some character codes are negative is determined by the C
480: compiler used to compile the preprocessor. If it treats `char' as
481: signed, then character codes large enough to set the sign bit will
482: be considered negative; otherwise, no character code is considered
483: negative.
484:
485: * Arithmetic operators for addition, subtraction, multiplication,
486: division, bitwise operations, shifts, comparisons, and `&&' and
487: `||'.
488:
489: * Identifiers that are not macros, which are all treated as zero(!).
490:
491: * Macro calls. All macro calls in the expression are expanded before
492: actual computation of the expression's value begins.
493:
494: Note that `sizeof' operators and `enum'-type values are not allowed.
495: `enum'-type values, like all other identifiers that are not taken as
496: macro calls and expanded, are treated as zero.
497:
498: The CONTROLLED TEXT inside of a conditional can include preprocessor
499: commands. Then the commands inside the conditional are obeyed only if
500: that branch of the conditional succeeds. The text can also contain
501: other conditional groups. However, the `#if' and `#endif' commands
502: must balance.
503:
504:
505: File: cpp.info, Node: #else Command, Next: #elif Command, Prev: #if Command, Up: Conditional Syntax
506:
507: The `#else' Command
508: ...................
509:
510: The `#else' command can be added to a conditional to provide
511: alternative text to be used if the condition is false. This is what it
512: looks like:
513:
514: #if EXPRESSION
515: TEXT-IF-TRUE
516: #else /* Not EXPRESSION */
517: TEXT-IF-FALSE
518: #endif /* Not EXPRESSION */
519:
520: If EXPRESSION is nonzero, and thus the TEXT-IF-TRUE is active, then
521: `#else' acts like a failing conditional and the TEXT-IF-FALSE is
522: ignored. Contrariwise, if the `#if' conditional fails, the
523: TEXT-IF-FALSE is considered included.
524:
525:
526: File: cpp.info, Node: #elif Command, Prev: #else Command, Up: Conditional Syntax
527:
528: The `#elif' Command
529: ...................
530:
531: One common case of nested conditionals is used to check for more
532: than two possible alternatives. For example, you might have
533:
534: #if X == 1
535: ...
536: #else /* X != 1 */
537: #if X == 2
538: ...
539: #else /* X != 2 */
540: ...
541: #endif /* X != 2 */
542: #endif /* X != 1 */
543:
544: Another conditional command, `#elif', allows this to be abbreviated
545: as follows:
546:
547: #if X == 1
548: ...
549: #elif X == 2
550: ...
551: #else /* X != 2 and X != 1*/
552: ...
553: #endif /* X != 2 and X != 1*/
554:
555: `#elif' stands for "else if". Like `#else', it goes in the middle
556: of a `#if'-`#endif' pair and subdivides it; it does not require a
557: matching `#endif' of its own. Like `#if', the `#elif' command includes
558: an expression to be tested.
559:
560: The text following the `#elif' is processed only if the original
561: `#if'-condition failed and the `#elif' condition succeeds. More than
562: one `#elif' can go in the same `#if'-`#endif' group. Then the text
563: after each `#elif' is processed only if the `#elif' condition succeeds
564: after the original `#if' and any previous `#elif' commands within it
565: have failed. `#else' is equivalent to `#elif 1', and `#else' is
566: allowed after any number of `#elif' commands, but `#elif' may not follow
567: `#else'.
568:
569:
570: File: cpp.info, Node: Deleted Code, Next: Conditionals-Macros, Prev: Conditional Syntax, Up: Conditionals
571:
572: Keeping Deleted Code for Future Reference
573: -----------------------------------------
574:
575: If you replace or delete a part of the program but want to keep the
576: old code around as a comment for future reference, the easy way to do
577: this is to put `#if 0' before it and `#endif' after it.
578:
579: This works even if the code being turned off contains conditionals,
580: but they must be entire conditionals (balanced `#if' and `#endif').
581:
582:
583: File: cpp.info, Node: Conditionals-Macros, Next: Assertions, Prev: Deleted Code, Up: Conditionals
584:
585: Conditionals and Macros
586: -----------------------
587:
588: Conditionals are useful in connection with macros or assertions,
589: because those are the only ways that an expression's value can vary
590: from one compilation to another. A `#if' command whose expression uses
591: no macros or assertions is equivalent to `#if 1' or `#if 0'; you might
592: as well determine which one, by computing the value of the expression
593: yourself, and then simplify the program.
594:
595: For example, here is a conditional that tests the expression
596: `BUFSIZE == 1020', where `BUFSIZE' must be a macro.
597:
598: #if BUFSIZE == 1020
599: printf ("Large buffers!\n");
600: #endif /* BUFSIZE is large */
601:
602: (Programmers often wish they could test the size of a variable or
603: data type in `#if', but this does not work. The preprocessor does not
604: understand `sizeof', or typedef names, or even the type keywords such
605: as `int'.)
606:
607: The special operator `defined' is used in `#if' expressions to test
608: whether a certain name is defined as a macro. Either `defined NAME' or
609: `defined (NAME)' is an expression whose value is 1 if NAME is defined
610: as macro at the current point in the program, and 0 otherwise. For the
611: `defined' operator it makes no difference what the definition of the
612: macro is; all that matters is whether there is a definition. Thus, for
613: example,
614:
615: #if defined (vax) || defined (ns16000)
616:
617: would include the following code if either of the names `vax' and
618: `ns16000' is defined as a macro. You can test the same condition using
619: assertions (*note Assertions::.), like this:
620:
621: #if #cpu (vax) || #cpu (ns16000)
622:
623: If a macro is defined and later undefined with `#undef', subsequent
624: use of the `defined' operator returns 0, because the name is no longer
625: defined. If the macro is defined again with another `#define',
626: `defined' will recommence returning 1.
627:
628: Conditionals that test just the definedness of one name are very
629: common, so there are two special short conditional commands for this
630: case.
631:
632: `#ifdef NAME'
633: is equivalent to `#if defined (NAME)'.
634:
635: `#ifndef NAME'
636: is equivalent to `#if ! defined (NAME)'.
637:
638: Macro definitions can vary between compilations for several reasons.
639:
640: * Some macros are predefined on each kind of machine. For example,
641: on a Vax, the name `vax' is a predefined macro. On other
642: machines, it would not be defined.
643:
644: * Many more macros are defined by system header files. Different
645: systems and machines define different macros, or give them
646: different values. It is useful to test these macros with
647: conditionals to avoid using a system feature on a machine where it
648: is not implemented.
649:
650: * Macros are a common way of allowing users to customize a program
651: for different machines or applications. For example, the macro
652: `BUFSIZE' might be defined in a configuration file for your
653: program that is included as a header file in each source file. You
654: would use `BUFSIZE' in a preprocessor conditional in order to
655: generate different code depending on the chosen configuration.
656:
657: * Macros can be defined or undefined with `-D' and `-U' command
658: options when you compile the program. You can arrange to compile
659: the same source file into two different programs by choosing a
660: macro name to specify which program you want, writing conditionals
661: to test whether or how this macro is defined, and then controlling
662: the state of the macro with compiler command options. *Note
663: Invocation::.
664:
665: Assertions are usually predefined, but can be defined with
666: preprocessor commands or command-line options.
667:
668:
669: File: cpp.info, Node: Assertions, Next: #error Command, Prev: Conditionals-Macros, Up: Conditionals
670:
671: Assertions
672: ----------
673:
674: "Assertions" are a more systematic alternative to macros in writing
675: conditionals to test what sort of computer or system the compiled
676: program will run on. Assertions are usually predefined, but you can
677: define them with preprocessor commands or command-line options.
678:
679: The macros traditionally used to describe the type of target are not
680: classified in any way according to which question they answer; they may
681: indicate a hardware architecture, a particular hardware model, an
682: operating system, a particular version of an operating system, or
683: specific configuration options. These are jumbled together in a single
684: namespace. In contrast, each assertion consists of a named question and
685: an answer. The question is usually called the "predicate". An
686: assertion looks like this:
687:
688: #PREDICATE (ANSWER)
689:
690: You must use a properly formed identifier for PREDICATE. The value of
691: ANSWER can be any sequence of words; all characters are significant
692: except for leading and trailing whitespace, and differences in internal
693: whitespace sequences are ignored. Thus, `x + y' is different from
694: `x+y' but equivalent to `x + y'. `)' is not allowed in an answer.
695:
696: Here is a conditional to test whether the answer ANSWER is asserted
697: for the predicate PREDICATE:
698:
699: #if #PREDICATE (ANSWER)
700:
701: There may be more than one answer asserted for a given predicate. If
702: you omit the answer, you can test whether *any* answer is asserted for
703: PREDICATE:
704:
705: #if #PREDICATE
706:
707: Most of the time, the assertions you test will be predefined
708: assertions. GNU C provides three predefined predicates: `system',
709: `cpu', and `machine'. `system' is for assertions about the type of
710: software, `cpu' describes the type of computer architecture, and
711: `machine' gives more information about the computer. For example, on a
712: GNU system, the following assertions would be true:
713:
714: #system (gnu)
715: #system (mach)
716: #system (mach 3)
717: #system (mach 3.SUBVERSION)
718: #system (hurd)
719: #system (hurd VERSION)
720:
721: and perhaps others. The alternatives with more or less version
722: information let you ask more or less detailed questions about the type
723: of system software.
724:
725: On a Unix system, you would find `#system (unix)' and perhaps one of:
726: `#system (aix)', `#system (bsd)', `#system (hpux)', `#system (lynx)',
727: `#system (mach)', `#system (posix)', `#system (svr3)', `#system
728: (svr4)', or `#system (xpg4)' with possible version numbers following.
729:
730: Other values for `system' are `#system (mvs)' and `#system (vms)'.
731:
732: *Portability note:* Many Unix C compilers provide only one answer
733: for the `system' assertion: `#system (unix)', if they support
734: assertions at all. This is less than useful.
735:
736: An assertion with a multi-word answer is completely different from
737: several assertions with individual single-word answers. For example,
738: the presence of `system (mach 3.0)' does not mean that `system (3.0)'
739: is true. It also does not directly imply `system (mach)', but in GNU
740: C, that last will normally be asserted as well.
741:
742: The current list of possible assertion values for `cpu' is: `#cpu
743: (a29k)', `#cpu (alpha)', `#cpu (arm)', `#cpu (clipper)', `#cpu
744: (convex)', `#cpu (elxsi)', `#cpu (tron)', `#cpu (h8300)', `#cpu
745: (i370)', `#cpu (i386)', `#cpu (i860)', `#cpu (i960)', `#cpu (m68k)',
746: `#cpu (m88k)', `#cpu (mips)', `#cpu (ns32k)', `#cpu (hppa)', `#cpu
747: (pyr)', `#cpu (ibm032)', `#cpu (rs6000)', `#cpu (sh)', `#cpu (sparc)',
748: `#cpu (spur)', `#cpu (tahoe)', `#cpu (vax)', `#cpu (we32000)'.
749:
750: You can create assertions within a C program using `#assert', like
751: this:
752:
753: #assert PREDICATE (ANSWER)
754:
755: (Note the absence of a `#' before PREDICATE.)
756:
757: Each time you do this, you assert a new true answer for PREDICATE.
758: Asserting one answer does not invalidate previously asserted answers;
759: they all remain true. The only way to remove an assertion is with
760: `#unassert'. `#unassert' has the same syntax as `#assert'. You can
761: also remove all assertions about PREDICATE like this:
762:
763: #unassert PREDICATE
764:
765: You can also add or cancel assertions using command options when you
766: run `gcc' or `cpp'. *Note Invocation::.
767:
768:
769: File: cpp.info, Node: #error Command, Prev: Assertions, Up: Conditionals
770:
771: The `#error' and `#warning' Commands
772: ------------------------------------
773:
774: The command `#error' causes the preprocessor to report a fatal
775: error. The rest of the line that follows `#error' is used as the error
776: message.
777:
778: You would use `#error' inside of a conditional that detects a
779: combination of parameters which you know the program does not properly
780: support. For example, if you know that the program will not run
781: properly on a Vax, you might write
782:
783: #ifdef vax
784: #error Won't work on Vaxen. See comments at get_last_object.
785: #endif
786:
787: *Note Nonstandard Predefined::, for why this works.
788:
789: If you have several configuration parameters that must be set up by
790: the installation in a consistent way, you can use conditionals to detect
791: an inconsistency and report it with `#error'. For example,
792:
793: #if HASH_TABLE_SIZE % 2 == 0 || HASH_TABLE_SIZE % 3 == 0 \
794: || HASH_TABLE_SIZE % 5 == 0
795: #error HASH_TABLE_SIZE should not be divisible by a small prime
796: #endif
797:
798: The command `#warning' is like the command `#error', but causes the
799: preprocessor to issue a warning and continue preprocessing. The rest of
800: the line that follows `#warning' is used as the warning message.
801:
802: You might use `#warning' in obsolete header files, with a message
803: directing the user to the header file which should be used instead.
804:
805:
806: File: cpp.info, Node: Combining Sources, Next: Other Commands, Prev: Conditionals, Up: Top
807:
808: Combining Source Files
809: ======================
810:
811: One of the jobs of the C preprocessor is to inform the C compiler of
812: where each line of C code came from: which source file and which line
813: number.
814:
815: C code can come from multiple source files if you use `#include';
816: both `#include' and the use of conditionals and macros can cause the
817: line number of a line in the preprocessor output to be different from
818: the line's number in the original source file. You will appreciate the
819: value of making both the C compiler (in error messages) and symbolic
820: debuggers such as GDB use the line numbers in your source file.
821:
822: The C preprocessor builds on this feature by offering a command by
823: which you can control the feature explicitly. This is useful when a
824: file for input to the C preprocessor is the output from another program
825: such as the `bison' parser generator, which operates on another file
826: that is the true source file. Parts of the output from `bison' are
827: generated from scratch, other parts come from a standard parser file.
828: The rest are copied nearly verbatim from the source file, but their
829: line numbers in the `bison' output are not the same as their original
830: line numbers. Naturally you would like compiler error messages and
831: symbolic debuggers to know the original source file and line number of
832: each line in the `bison' input.
833:
834: `bison' arranges this by writing `#line' commands into the output
835: file. `#line' is a command that specifies the original line number and
836: source file name for subsequent input in the current preprocessor input
837: file. `#line' has three variants:
838:
839: `#line LINENUM'
840: Here LINENUM is a decimal integer constant. This specifies that
841: the line number of the following line of input, in its original
842: source file, was LINENUM.
843:
844: `#line LINENUM FILENAME'
845: Here LINENUM is a decimal integer constant and FILENAME is a
846: string constant. This specifies that the following line of input
847: came originally from source file FILENAME and its line number there
848: was LINENUM. Keep in mind that FILENAME is not just a file name;
849: it is surrounded by doublequote characters so that it looks like a
850: string constant.
851:
852: `#line ANYTHING ELSE'
853: ANYTHING ELSE is checked for macro calls, which are expanded. The
854: result should be a decimal integer constant followed optionally by
855: a string constant, as described above.
856:
857: `#line' commands alter the results of the `__FILE__' and `__LINE__'
858: predefined macros from that point on. *Note Standard Predefined::.
859:
860: The output of the preprocessor (which is the input for the rest of
861: the compiler) contains commands that look much like `#line' commands.
862: They start with just `#' instead of `#line', but this is followed by a
863: line number and file name as in `#line'. *Note Output::.
864:
865:
866: File: cpp.info, Node: Other Commands, Next: Output, Prev: Combining Sources, Up: Top
867:
868: Miscellaneous Preprocessor Commands
869: ===================================
870:
871: This section describes three additional preprocessor commands. They
872: are not very useful, but are mentioned for completeness.
873:
874: The "null command" consists of a `#' followed by a Newline, with
875: only whitespace (including comments) in between. A null command is
876: understood as a preprocessor command but has no effect on the
877: preprocessor output. The primary significance of the existence of the
878: null command is that an input line consisting of just a `#' will
879: produce no output, rather than a line of output containing just a `#'.
880: Supposedly some old C programs contain such lines.
881:
882: The ANSI standard specifies that the `#pragma' command has an
883: arbitrary, implementation-defined effect. In the GNU C preprocessor,
884: `#pragma' commands are not used, except for `#pragma once' (*note
885: Once-Only::.). However, they are left in the preprocessor output, so
886: they are available to the compilation pass.
887:
888: The `#ident' command is supported for compatibility with certain
889: other systems. It is followed by a line of text. On some systems, the
890: text is copied into a special place in the object file; on most systems,
891: the text is ignored and this command has no effect. Typically `#ident'
892: is only used in header files supplied with those systems where it is
893: meaningful.
894:
895:
896: File: cpp.info, Node: Output, Next: Invocation, Prev: Other Commands, Up: Top
897:
898: C Preprocessor Output
899: =====================
900:
901: The output from the C preprocessor looks much like the input, except
902: that all preprocessor command lines have been replaced with blank lines
903: and all comments with spaces. Whitespace within a line is not altered;
904: however, a space is inserted after the expansions of most macro calls.
905:
906: Source file name and line number information is conveyed by lines of
907: the form
908:
909: # LINENUM FILENAME FLAGS
910:
911: which are inserted as needed into the middle of the input (but never
912: within a string or character constant). Such a line means that the
913: following line originated in file FILENAME at line LINENUM.
914:
915: After the file name comes zero or more flags, which are `1', `2' or
916: `3'. If there are multiple flags, spaces separate them. Here is what
917: the flags mean:
918:
919: `1'
920: This indicates the start of a new file.
921:
922: `2'
923: This indicates returning to a file (after having included another
924: file).
925:
926: `3'
927: This indicates that the following text comes from a system header
928: file, so certain warnings should be suppressed.
929:
930:
931: File: cpp.info, Node: Invocation, Next: Concept Index, Prev: Output, Up: Top
932:
933: Invoking the C Preprocessor
934: ===========================
935:
936: Most often when you use the C preprocessor you will not have to
937: invoke it explicitly: the C compiler will do so automatically.
938: However, the preprocessor is sometimes useful individually.
939:
940: The C preprocessor expects two file names as arguments, INFILE and
941: OUTFILE. The preprocessor reads INFILE together with any other files
942: it specifies with `#include'. All the output generated by the combined
943: input files is written in OUTFILE.
944:
945: Either INFILE or OUTFILE may be `-', which as INFILE means to read
946: from standard input and as OUTFILE means to write to standard output.
947: Also, if OUTFILE or both file names are omitted, the standard output
948: and standard input are used for the omitted file names.
949:
950: Here is a table of command options accepted by the C preprocessor.
951: These options can also be given when compiling a C program; they are
952: passed along automatically to the preprocessor when it is invoked by the
953: compiler.
954:
955: `-P'
956: Inhibit generation of `#'-lines with line-number information in
957: the output from the preprocessor (*note Output::.). This might be
958: useful when running the preprocessor on something that is not C
959: code and will be sent to a program which might be confused by the
960: `#'-lines.
961:
962: `-C'
963: Do not discard comments: pass them through to the output file.
964: Comments appearing in arguments of a macro call will be copied to
965: the output before the expansion of the macro call.
966:
967: `-traditional'
968: Try to imitate the behavior of old-fashioned C, as opposed to ANSI
969: C.
970:
971: * Traditional macro expansion pays no attention to singlequote
972: or doublequote characters; macro argument symbols are
973: replaced by the argument values even when they appear within
974: apparent string or character constants.
975:
976: * Traditionally, it is permissible for a macro expansion to end
977: in the middle of a string or character constant. The
978: constant continues into the text surrounding the macro call.
979:
980: * However, traditionally the end of the line terminates a
981: string or character constant, with no error.
982:
983: * In traditional C, a comment is equivalent to no text at all.
984: (In ANSI C, a comment counts as whitespace.)
985:
986: * Traditional C does not have the concept of a "preprocessing
987: number". It considers `1.0e+4' to be three tokens: `1.0e',
988: `+', and `4'.
989:
990: * A macro is not suppressed within its own definition, in
991: traditional C. Thus, any macro that is used recursively
992: inevitably causes an error.
993:
994: * The character `#' has no special meaning within a macro
995: definition in traditional C.
996:
997: * In traditional C, the text at the end of a macro expansion
998: can run together with the text after the macro call, to
999: produce a single token. (This is impossible in ANSI C.)
1000:
1001: * Traditionally, `\' inside a macro argument suppresses the
1002: syntactic significance of the following character.
1003:
1004: `-trigraphs'
1005: Process ANSI standard trigraph sequences. These are
1006: three-character sequences, all starting with `??', that are
1007: defined by ANSI C to stand for single characters. For example,
1008: `??/' stands for `\', so `'??/n'' is a character constant for a
1009: newline. Strictly speaking, the GNU C preprocessor does not
1010: support all programs in ANSI Standard C unless `-trigraphs' is
1011: used, but if you ever notice the difference it will be with relief.
1012:
1013: You don't want to know any more about trigraphs.
1014:
1015: `-pedantic'
1016: Issue warnings required by the ANSI C standard in certain cases
1017: such as when text other than a comment follows `#else' or `#endif'.
1018:
1019: `-pedantic-errors'
1020: Like `-pedantic', except that errors are produced rather than
1021: warnings.
1022:
1023: `-Wtrigraphs'
1024: Warn if any trigraphs are encountered (assuming they are enabled).
1025:
1026: `-Wcomment'
1027: Warn whenever a comment-start sequence `/*' appears in a comment.
1028:
1029: `-Wall'
1030: Requests both `-Wtrigraphs' and `-Wcomment' (but not
1031: `-Wtraditional').
1032:
1033: `-Wtraditional'
1034: Warn about certain constructs that behave differently in
1035: traditional and ANSI C.
1036:
1037: `-I DIRECTORY'
1038: Add the directory DIRECTORY to the end of the list of directories
1039: to be searched for header files (*note Include Syntax::.). This
1040: can be used to override a system header file, substituting your
1041: own version, since these directories are searched before the system
1042: header file directories. If you use more than one `-I' option,
1043: the directories are scanned in left-to-right order; the standard
1044: system directories come after.
1045:
1046: `-I-'
1047: Any directories specified with `-I' options before the `-I-'
1048: option are searched only for the case of `#include "FILE"'; they
1049: are not searched for `#include <FILE>'.
1050:
1051: If additional directories are specified with `-I' options after
1052: the `-I-', these directories are searched for all `#include'
1053: commands.
1054:
1055: In addition, the `-I-' option inhibits the use of the current
1056: directory as the first search directory for `#include "FILE"'.
1057: Therefore, the current directory is searched only if it is
1058: requested explicitly with `-I.'. Specifying both `-I-' and `-I.'
1059: allows you to control precisely which directories are searched
1060: before the current one and which are searched after.
1061:
1062: `-nostdinc'
1063: Do not search the standard system directories for header files.
1064: Only the directories you have specified with `-I' options (and the
1065: current directory, if appropriate) are searched.
1066:
1067: `-nostdinc++'
1068: Do not search for header files in the C++-specific standard
1069: directories, but do still search the other standard directories.
1070: (This option is used when building libg++.)
1071:
1072: `-D NAME'
1073: Predefine NAME as a macro, with definition `1'.
1074:
1075: `-D NAME=DEFINITION'
1076: Predefine NAME as a macro, with definition DEFINITION. There are
1077: no restrictions on the contents of DEFINITION, but if you are
1078: invoking the preprocessor from a shell or shell-like program you
1079: may need to use the shell's quoting syntax to protect characters
1080: such as spaces that have a meaning in the shell syntax. If you
1081: use more than one `-D' for the same NAME, the rightmost definition
1082: takes effect.
1083:
1084: `-U NAME'
1085: Do not predefine NAME. If both `-U' and `-D' are specified for
1086: one name, the `-U' beats the `-D' and the name is not predefined.
1087:
1088: `-undef'
1089: Do not predefine any nonstandard macros.
1090:
1091: `-A PREDICATE(ANSWER)'
1092: Make an assertion with the predicate PREDICATE and answer ANSWER.
1093: *Note Assertions::.
1094:
1095: You can use `-A-' to disable all predefined assertions; it also
1096: undefines all predefined macros that identify the type of target
1097: system.
1098:
1099: `-dM'
1100: Instead of outputting the result of preprocessing, output a list of
1101: `#define' commands for all the macros defined during the execution
1102: of the preprocessor, including predefined macros. This gives you
1103: a way of finding out what is predefined in your version of the
1104: preprocessor; assuming you have no file `foo.h', the command
1105:
1106: touch foo.h; cpp -dM foo.h
1107:
1108: will show the values of any predefined macros.
1109:
1110: `-dD'
1111: Like `-dM' except in two respects: it does *not* include the
1112: predefined macros, and it outputs *both* the `#define' commands
1113: and the result of preprocessing. Both kinds of output go to the
1114: standard output file.
1115:
1116: `-M'
1117: Instead of outputting the result of preprocessing, output a rule
1118: suitable for `make' describing the dependencies of the main source
1119: file. The preprocessor outputs one `make' rule containing the
1120: object file name for that source file, a colon, and the names of
1121: all the included files. If there are many included files then the
1122: rule is split into several lines using `\'-newline.
1123:
1124: This feature is used in automatic updating of makefiles.
1125:
1126: `-MM'
1127: Like `-M' but mention only the files included with `#include
1128: "FILE"'. System header files included with `#include <FILE>' are
1129: omitted.
1130:
1131: `-MD'
1132: Like `-M' but the dependency information is written to files with
1133: names made by replacing `.c' with `.d' at the end of the input
1134: file names. This is in addition to compiling the file as
1135: specified--`-MD' does not inhibit ordinary compilation the way
1136: `-M' does.
1137:
1138: In Mach, you can use the utility `md' to merge the `.d' files into
1139: a single dependency file suitable for using with the `make'
1140: command.
1141:
1142: `-MMD'
1143: Like `-MD' except mention only user header files, not system
1144: header files.
1145:
1146: `-H'
1147: Print the name of each header file used, in addition to other
1148: normal activities.
1149:
1150: `-imacros FILE'
1151: Process FILE as input, discarding the resulting output, before
1152: processing the regular input file. Because the output generated
1153: from FILE is discarded, the only effect of `-imacros FILE' is to
1154: make the macros defined in FILE available for use in the main
1155: input.
1156:
1157: `-include FILE'
1158: Process FILE as input, and include all the resulting output,
1159: before processing the regular input file.
1160:
1161: `-idirafter DIR'
1162: Add the directory DIR to the second include path. The directories
1163: on the second include path are searched when a header file is not
1164: found in any of the directories in the main include path (the one
1165: that `-I' adds to).
1166:
1167: `-iprefix PREFIX'
1168: Specify PREFIX as the prefix for subsequent `-iwithprefix' options.
1169:
1170: `-iwithprefix DIR'
1171: Add a directory to the second include path. The directory's name
1172: is made by concatenating PREFIX and DIR, where PREFIX was
1173: specified previously with `-iprefix'.
1174:
1175: `-lang-c'
1176: `-lang-c++'
1177: `-lang-objc'
1178: `-lang-objc++'
1179: Specify the source language. `-lang-c++' makes the preprocessor
1180: handle C++ comment syntax (comments may begin with `//', in which
1181: case they end at end of line), and includes extra default include
1182: directories for C++; and `-lang-objc' enables the Objective C
1183: `#import' command. `-lang-c' explicitly turns off both of these
1184: extensions, and `-lang-objc++' enables both.
1185:
1186: These options are generated by the compiler driver `gcc', but not
1187: passed from the `gcc' command line.
1188:
1189: `-lint'
1190: Look for commands to the program checker `lint' embedded in
1191: comments, and emit them preceded by `#pragma lint'. For example,
1192: the comment `/* NOTREACHED */' becomes `#pragma lint NOTREACHED'.
1193:
1194: This option is available only when you call `cpp' directly; `gcc'
1195: will not pass it from its command line.
1196:
1197: `-$'
1198: Forbid the use of `$' in identifiers. This is required for ANSI
1199: conformance. `gcc' automatically supplies this option to the
1200: preprocessor if you specify `-ansi', but `gcc' doesn't recognize
1201: the `-$' option itself--to use it without the other effects of
1202: `-ansi', you must call the preprocessor directly.
1203:
1204:
1205: File: cpp.info, Node: Concept Index, Next: Index, Prev: Invocation, Up: Top
1206:
1207: Concept Index
1208: *************
1209:
1210: * Menu:
1211:
1212: * assertions: Assertions.
1213: * assertions, undoing: Assertions.
1214: * cascaded macros: Cascaded Macros.
1215: * commands: Commands.
1216: * concatenation: Concatenation.
1217: * conditionals: Conditionals.
1218: * header file: Header Files.
1219: * inheritance: Inheritance.
1220: * line control: Combining Sources.
1221: * macro body uses macro: Cascaded Macros.
1222: * null command: Other Commands.
1223: * options: Invocation.
1224: * output format: Output.
1225: * overriding a header file: Inheritance.
1226: * predefined macros: Predefined.
1227: * predicates: Assertions.
1228: * preprocessor commands: Commands.
1229: * redefining macros: Redefining.
1230: * repeated inclusion: Once-Only.
1231: * retracting assertions: Assertions.
1232: * second include path: Invocation.
1233: * self-reference: Self-Reference.
1234: * semicolons (after macro calls): Swallow Semicolon.
1235: * side effects (in macro arguments): Side Effects.
1236: * stringification: Stringification.
1237: * testing predicates: Assertions.
1238: * unassert: Assertions.
1239: * undefining macros: Undefining.
1240: * unsafe macros: Side Effects.
1241:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.