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