1 This is Info file cpp.info, produced by Makeinfo version 1.67 from the
4 This file documents the GNU C Preprocessor.
6 Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995 Free Software
9 Permission is granted to make and distribute verbatim copies of this
10 manual provided the copyright notice and this permission notice are
11 preserved on all copies.
13 Permission is granted to copy and distribute modified versions of
14 this manual under the conditions for verbatim copying, provided also
15 that the entire resulting derived work is distributed under the terms
16 of a permission notice identical to this one.
18 Permission is granted to copy and distribute translations of this
19 manual into another language, under the above conditions for modified
23 File: cpp.info, Node: Misnesting, Next: Macro Parentheses, Prev: Macro Pitfalls, Up: Macro Pitfalls
25 Improperly Nested Constructs
26 ............................
28 Recall that when a macro is called with arguments, the arguments are
29 substituted into the macro body and the result is checked, together with
30 the rest of the input file, for more macro calls.
32 It is possible to piece together a macro call coming partially from
33 the macro body and partially from the actual arguments. For example,
35 #define double(x) (2*(x))
36 #define call_with_1(x) x(1)
38 would expand `call_with_1 (double)' into `(2*(1))'.
40 Macro definitions do not have to have balanced parentheses. By
41 writing an unbalanced open parenthesis in a macro body, it is possible
42 to create a macro call that begins inside the macro body but ends
43 outside of it. For example,
45 #define strange(file) fprintf (file, "%s %d",
47 strange(stderr) p, 35)
49 This bizarre example expands to `fprintf (stderr, "%s %d", p, 35)'!
52 File: cpp.info, Node: Macro Parentheses, Next: Swallow Semicolon, Prev: Misnesting, Up: Macro Pitfalls
54 Unintended Grouping of Arithmetic
55 .................................
57 You may have noticed that in most of the macro definition examples
58 shown above, each occurrence of a macro argument name had parentheses
59 around it. In addition, another pair of parentheses usually surround
60 the entire macro definition. Here is why it is best to write macros
63 Suppose you define a macro as follows,
65 #define ceil_div(x, y) (x + y - 1) / y
67 whose purpose is to divide, rounding up. (One use for this operation is
68 to compute how many `int' objects are needed to hold a certain number
69 of `char' objects.) Then suppose it is used as follows:
71 a = ceil_div (b & c, sizeof (int));
75 a = (b & c + sizeof (int) - 1) / sizeof (int);
77 which does not do what is intended. The operator-precedence rules of C
78 make it equivalent to this:
80 a = (b & (c + sizeof (int) - 1)) / sizeof (int);
82 But what we want is this:
84 a = ((b & c) + sizeof (int) - 1)) / sizeof (int);
88 #define ceil_div(x, y) ((x) + (y) - 1) / (y)
90 provides the desired result.
92 However, unintended grouping can result in another way. Consider
93 `sizeof ceil_div(1, 2)'. That has the appearance of a C expression
94 that would compute the size of the type of `ceil_div (1, 2)', but in
95 fact it means something very different. Here is what it expands to:
97 sizeof ((1) + (2) - 1) / (2)
99 This would take the size of an integer and divide it by two. The
100 precedence rules have put the division outside the `sizeof' when it was
101 intended to be inside.
103 Parentheses around the entire macro definition can prevent such
104 problems. Here, then, is the recommended way to define `ceil_div':
106 #define ceil_div(x, y) (((x) + (y) - 1) / (y))
109 File: cpp.info, Node: Swallow Semicolon, Next: Side Effects, Prev: Macro Parentheses, Up: Macro Pitfalls
111 Swallowing the Semicolon
112 ........................
114 Often it is desirable to define a macro that expands into a compound
115 statement. Consider, for example, the following macro, that advances a
116 pointer (the argument `p' says where to find it) across whitespace
119 #define SKIP_SPACES (p, limit) \
120 { register char *lim = (limit); \
125 Here Backslash-Newline is used to split the macro definition, which must
126 be a single line, so that it resembles the way such C code would be
127 laid out if not part of a macro definition.
129 A call to this macro might be `SKIP_SPACES (p, lim)'. Strictly
130 speaking, the call expands to a compound statement, which is a complete
131 statement with no need for a semicolon to end it. But it looks like a
132 function call. So it minimizes confusion if you can use it like a
133 function call, writing a semicolon afterward, as in `SKIP_SPACES (p,
136 But this can cause trouble before `else' statements, because the
137 semicolon is actually a null statement. Suppose you write
140 SKIP_SPACES (p, lim);
143 The presence of two statements--the compound statement and a null
144 statement--in between the `if' condition and the `else' makes invalid C
147 The definition of the macro `SKIP_SPACES' can be altered to solve
148 this problem, using a `do ... while' statement. Here is how:
150 #define SKIP_SPACES (p, limit) \
151 do { register char *lim = (limit); \
157 Now `SKIP_SPACES (p, lim);' expands into
161 which is one statement.
164 File: cpp.info, Node: Side Effects, Next: Self-Reference, Prev: Swallow Semicolon, Up: Macro Pitfalls
166 Duplication of Side Effects
167 ...........................
169 Many C programs define a macro `min', for "minimum", like this:
171 #define min(X, Y) ((X) < (Y) ? (X) : (Y))
173 When you use this macro with an argument containing a side effect,
176 next = min (x + y, foo (z));
178 it expands as follows:
180 next = ((x + y) < (foo (z)) ? (x + y) : (foo (z)));
182 where `x + y' has been substituted for `X' and `foo (z)' for `Y'.
184 The function `foo' is used only once in the statement as it appears
185 in the program, but the expression `foo (z)' has been substituted twice
186 into the macro expansion. As a result, `foo' might be called two times
187 when the statement is executed. If it has side effects or if it takes
188 a long time to compute, the results might not be what you intended. We
189 say that `min' is an "unsafe" macro.
191 The best solution to this problem is to define `min' in a way that
192 computes the value of `foo (z)' only once. The C language offers no
193 standard way to do this, but it can be done with GNU C extensions as
197 ({ typeof (X) __x = (X), __y = (Y); \
198 (__x < __y) ? __x : __y; })
200 If you do not wish to use GNU C extensions, the only solution is to
201 be careful when *using* the macro `min'. For example, you can
202 calculate the value of `foo (z)', save it in a variable, and use that
205 #define min(X, Y) ((X) < (Y) ? (X) : (Y))
209 next = min (x + y, tem);
212 (where we assume that `foo' returns type `int').
215 File: cpp.info, Node: Self-Reference, Next: Argument Prescan, Prev: Side Effects, Up: Macro Pitfalls
217 Self-Referential Macros
218 .......................
220 A "self-referential" macro is one whose name appears in its
221 definition. A special feature of ANSI Standard C is that the
222 self-reference is not considered a macro call. It is passed into the
223 preprocessor output unchanged.
225 Let's consider an example:
227 #define foo (4 + foo)
229 where `foo' is also a variable in your program.
231 Following the ordinary rules, each reference to `foo' will expand
232 into `(4 + foo)'; then this will be rescanned and will expand into `(4
233 + (4 + foo))'; and so on until it causes a fatal error (memory full) in
236 However, the special rule about self-reference cuts this process
237 short after one step, at `(4 + foo)'. Therefore, this macro definition
238 has the possibly useful effect of causing the program to add 4 to the
239 value of `foo' wherever `foo' is referred to.
241 In most cases, it is a bad idea to take advantage of this feature. A
242 person reading the program who sees that `foo' is a variable will not
243 expect that it is a macro as well. The reader will come across the
244 identifier `foo' in the program and think its value should be that of
245 the variable `foo', whereas in fact the value is four greater.
247 The special rule for self-reference applies also to "indirect"
248 self-reference. This is the case where a macro X expands to use a
249 macro `y', and the expansion of `y' refers to the macro `x'. The
250 resulting reference to `x' comes indirectly from the expansion of `x',
251 so it is a self-reference and is not further expanded. Thus, after
256 `x' would expand into `(4 + (2 * x))'. Clear?
258 But suppose `y' is used elsewhere, not from the definition of `x'.
259 Then the use of `x' in the expansion of `y' is not a self-reference
260 because `x' is not "in progress". So it does expand. However, the
261 expansion of `x' contains a reference to `y', and that is an indirect
262 self-reference now because `y' is "in progress". The result is that
263 `y' expands to `(2 * (4 + y))'.
265 It is not clear that this behavior would ever be useful, but it is
266 specified by the ANSI C standard, so you may need to understand it.
269 File: cpp.info, Node: Argument Prescan, Next: Cascaded Macros, Prev: Self-Reference, Up: Macro Pitfalls
271 Separate Expansion of Macro Arguments
272 .....................................
274 We have explained that the expansion of a macro, including the
275 substituted actual arguments, is scanned over again for macro calls to
278 What really happens is more subtle: first each actual argument text
279 is scanned separately for macro calls. Then the results of this are
280 substituted into the macro body to produce the macro expansion, and the
281 macro expansion is scanned again for macros to expand.
283 The result is that the actual arguments are scanned *twice* to expand
286 Most of the time, this has no effect. If the actual argument
287 contained any macro calls, they are expanded during the first scan.
288 The result therefore contains no macro calls, so the second scan does
289 not change it. If the actual argument were substituted as given, with
290 no prescan, the single remaining scan would find the same macro calls
291 and produce the same results.
293 You might expect the double scan to change the results when a
294 self-referential macro is used in an actual argument of another macro
295 (*note Self-Reference::.): the self-referential macro would be expanded
296 once in the first scan, and a second time in the second scan. But this
297 is not what happens. The self-references that do not expand in the
298 first scan are marked so that they will not expand in the second scan
301 The prescan is not done when an argument is stringified or
308 expands to `"foo"'. Once more, prescan has been prevented from having
309 any noticeable effect.
311 More precisely, stringification and concatenation use the argument as
312 written, in un-prescanned form. The same actual argument would be used
313 in prescanned form if it is substituted elsewhere without
314 stringification or concatenation.
316 #define str(s) #s lose(s)
320 expands to `"foo" lose(4)'.
322 You might now ask, "Why mention the prescan, if it makes no
323 difference? And why not skip it and make the preprocessor faster?"
324 The answer is that the prescan does make a difference in three special
327 * Nested calls to a macro.
329 * Macros that call other macros that stringify or concatenate.
331 * Macros whose expansions contain unshielded commas.
333 We say that "nested" calls to a macro occur when a macro's actual
334 argument contains a call to that very macro. For example, if `f' is a
335 macro that expects one argument, `f (f (1))' is a nested pair of calls
336 to `f'. The desired expansion is made by expanding `f (1)' and
337 substituting that into the definition of `f'. The prescan causes the
338 expected result to happen. Without the prescan, `f (1)' itself would
339 be substituted as an actual argument, and the inner use of `f' would
340 appear during the main scan as an indirect self-reference and would not
341 be expanded. Here, the prescan cancels an undesirable side effect (in
342 the medical, not computational, sense of the term) of the special rule
343 for self-referential macros.
345 But prescan causes trouble in certain other cases of nested macro
346 calls. Here is an example:
349 #define bar(x) lose(x)
350 #define lose(x) (1 + (x))
354 We would like `bar(foo)' to turn into `(1 + (foo))', which would then
355 turn into `(1 + (a,b))'. But instead, `bar(foo)' expands into
356 `lose(a,b)', and you get an error because `lose' requires a single
357 argument. In this case, the problem is easily solved by the same
358 parentheses that ought to be used to prevent misnesting of arithmetic
362 #define bar(x) lose((x))
364 The problem is more serious when the operands of the macro are not
365 expressions; for example, when they are statements. Then parentheses
366 are unacceptable because they would make for invalid C code:
368 #define foo { int a, b; ... }
370 In GNU C you can shield the commas using the `({...})' construct which
371 turns a compound statement into an expression:
373 #define foo ({ int a, b; ... })
375 Or you can rewrite the macro definition to avoid such commas:
377 #define foo { int a; int b; ... }
379 There is also one case where prescan is useful. It is possible to
380 use prescan to expand an argument and then stringify it--if you use two
381 levels of macros. Let's add a new macro `xstr' to the example shown
384 #define xstr(s) str(s)
389 This expands into `"4"', not `"foo"'. The reason for the difference
390 is that the argument of `xstr' is expanded at prescan (because `xstr'
391 does not specify stringification or concatenation of the argument).
392 The result of prescan then forms the actual argument for `str'. `str'
393 uses its argument without prescan because it performs stringification;
394 but it cannot prevent or undo the prescanning already done by `xstr'.
397 File: cpp.info, Node: Cascaded Macros, Next: Newlines in Args, Prev: Argument Prescan, Up: Macro Pitfalls
399 Cascaded Use of Macros
400 ......................
402 A "cascade" of macros is when one macro's body contains a reference
403 to another macro. This is very common practice. For example,
406 #define TABLESIZE BUFSIZE
408 This is not at all the same as defining `TABLESIZE' to be `1020'.
409 The `#define' for `TABLESIZE' uses exactly the body you specify--in
410 this case, `BUFSIZE'--and does not check to see whether it too is the
413 It's only when you *use* `TABLESIZE' that the result of its expansion
414 is checked for more macro names.
416 This makes a difference if you change the definition of `BUFSIZE' at
417 some point in the source file. `TABLESIZE', defined as shown, will
418 always expand using the definition of `BUFSIZE' that is currently in
422 #define TABLESIZE BUFSIZE
426 Now `TABLESIZE' expands (in two stages) to `37'. (The `#undef' is to
427 prevent any warning about the nontrivial redefinition of `BUFSIZE'.)
430 File: cpp.info, Node: Newlines in Args, Prev: Cascaded Macros, Up: Macro Pitfalls
432 Newlines in Macro Arguments
433 ---------------------------
435 Traditional macro processing carries forward all newlines in macro
436 arguments into the expansion of the macro. This means that, if some of
437 the arguments are substituted more than once, or not at all, or out of
438 order, newlines can be duplicated, lost, or moved around within the
439 expansion. If the expansion consists of multiple statements, then the
440 effect is to distort the line numbers of some of these statements. The
441 result can be incorrect line numbers, in error messages or displayed in
444 The GNU C preprocessor operating in ANSI C mode adjusts appropriately
445 for multiple use of an argument--the first use expands all the
446 newlines, and subsequent uses of the same argument produce no newlines.
447 But even in this mode, it can produce incorrect line numbering if
448 arguments are used out of order, or not used at all.
450 Here is an example illustrating this problem:
452 #define ignore_second_arg(a,b,c) a; c
454 ignore_second_arg (foo (),
458 The syntax error triggered by the tokens `syntax error' results in an
459 error message citing line four, even though the statement text comes
463 File: cpp.info, Node: Conditionals, Next: Combining Sources, Prev: Macros, Up: Top
468 In a macro processor, a "conditional" is a directive that allows a
469 part of the program to be ignored during compilation, on some
470 conditions. In the C preprocessor, a conditional can test either an
471 arithmetic expression or whether a name is defined as a macro.
473 A conditional in the C preprocessor resembles in some ways an `if'
474 statement in C, but it is important to understand the difference between
475 them. The condition in an `if' statement is tested during the execution
476 of your program. Its purpose is to allow your program to behave
477 differently from run to run, depending on the data it is operating on.
478 The condition in a preprocessing conditional directive is tested when
479 your program is compiled. Its purpose is to allow different code to be
480 included in the program depending on the situation at the time of
485 * Uses: Conditional Uses. What conditionals are for.
486 * Syntax: Conditional Syntax. How conditionals are written.
487 * Deletion: Deleted Code. Making code into a comment.
488 * Macros: Conditionals-Macros. Why conditionals are used with macros.
489 * Assertions:: How and why to use assertions.
490 * Errors: #error Directive. Detecting inconsistent compilation parameters.
493 File: cpp.info, Node: Conditional Uses, Next: Conditional Syntax, Up: Conditionals
495 Why Conditionals are Used
496 -------------------------
498 Generally there are three kinds of reason to use a conditional.
500 * A program may need to use different code depending on the machine
501 or operating system it is to run on. In some cases the code for
502 one operating system may be erroneous on another operating system;
503 for example, it might refer to library routines that do not exist
504 on the other system. When this happens, it is not enough to avoid
505 executing the invalid code: merely having it in the program makes
506 it impossible to link the program and run it. With a
507 preprocessing conditional, the offending code can be effectively
508 excised from the program when it is not valid.
510 * You may want to be able to compile the same source file into two
511 different programs. Sometimes the difference between the programs
512 is that one makes frequent time-consuming consistency checks on its
513 intermediate data, or prints the values of those data for
514 debugging, while the other does not.
516 * A conditional whose condition is always false is a good way to
517 exclude code from the program but keep it as a sort of comment for
520 Most simple programs that are intended to run on only one machine
521 will not need to use preprocessing conditionals.
524 File: cpp.info, Node: Conditional Syntax, Next: Deleted Code, Prev: Conditional Uses, Up: Conditionals
526 Syntax of Conditionals
527 ----------------------
529 A conditional in the C preprocessor begins with a "conditional
530 directive": `#if', `#ifdef' or `#ifndef'. *Note Conditionals-Macros::,
531 for information on `#ifdef' and `#ifndef'; only `#if' is explained here.
535 * If: #if Directive. Basic conditionals using `#if' and `#endif'.
536 * Else: #else Directive. Including some text if the condition fails.
537 * Elif: #elif Directive. Testing several alternative possibilities.
540 File: cpp.info, Node: #if Directive, Next: #else Directive, Up: Conditional Syntax
545 The `#if' directive in its simplest form consists of
549 #endif /* EXPRESSION */
551 The comment following the `#endif' is not required, but it is a good
552 practice because it helps people match the `#endif' to the
553 corresponding `#if'. Such comments should always be used, except in
554 short conditionals that are not nested. In fact, you can put anything
555 at all after the `#endif' and it will be ignored by the GNU C
556 preprocessor, but only comments are acceptable in ANSI Standard C.
558 EXPRESSION is a C expression of integer type, subject to stringent
559 restrictions. It may contain
561 * Integer constants, which are all regarded as `long' or `unsigned
564 * Character constants, which are interpreted according to the
565 character set and conventions of the machine and operating system
566 on which the preprocessor is running. The GNU C preprocessor uses
567 the C data type `char' for these character constants; therefore,
568 whether some character codes are negative is determined by the C
569 compiler used to compile the preprocessor. If it treats `char' as
570 signed, then character codes large enough to set the sign bit will
571 be considered negative; otherwise, no character code is considered
574 * Arithmetic operators for addition, subtraction, multiplication,
575 division, bitwise operations, shifts, comparisons, and logical
576 operations (`&&' and `||').
578 * Identifiers that are not macros, which are all treated as zero(!).
580 * Macro calls. All macro calls in the expression are expanded before
581 actual computation of the expression's value begins.
583 Note that `sizeof' operators and `enum'-type values are not allowed.
584 `enum'-type values, like all other identifiers that are not taken as
585 macro calls and expanded, are treated as zero.
587 The CONTROLLED TEXT inside of a conditional can include
588 preprocessing directives. Then the directives inside the conditional
589 are obeyed only if that branch of the conditional succeeds. The text
590 can also contain other conditional groups. However, the `#if' and
591 `#endif' directives must balance.
594 File: cpp.info, Node: #else Directive, Next: #elif Directive, Prev: #if Directive, Up: Conditional Syntax
596 The `#else' Directive
597 .....................
599 The `#else' directive can be added to a conditional to provide
600 alternative text to be used if the condition is false. This is what it
605 #else /* Not EXPRESSION */
607 #endif /* Not EXPRESSION */
609 If EXPRESSION is nonzero, and thus the TEXT-IF-TRUE is active, then
610 `#else' acts like a failing conditional and the TEXT-IF-FALSE is
611 ignored. Contrariwise, if the `#if' conditional fails, the
612 TEXT-IF-FALSE is considered included.
615 File: cpp.info, Node: #elif Directive, Prev: #else Directive, Up: Conditional Syntax
617 The `#elif' Directive
618 .....................
620 One common case of nested conditionals is used to check for more
621 than two possible alternatives. For example, you might have
633 Another conditional directive, `#elif', allows this to be abbreviated
640 #else /* X != 2 and X != 1*/
642 #endif /* X != 2 and X != 1*/
644 `#elif' stands for "else if". Like `#else', it goes in the middle
645 of a `#if'-`#endif' pair and subdivides it; it does not require a
646 matching `#endif' of its own. Like `#if', the `#elif' directive
647 includes an expression to be tested.
649 The text following the `#elif' is processed only if the original
650 `#if'-condition failed and the `#elif' condition succeeds. More than
651 one `#elif' can go in the same `#if'-`#endif' group. Then the text
652 after each `#elif' is processed only if the `#elif' condition succeeds
653 after the original `#if' and any previous `#elif' directives within it
654 have failed. `#else' is equivalent to `#elif 1', and `#else' is
655 allowed after any number of `#elif' directives, but `#elif' may not
659 File: cpp.info, Node: Deleted Code, Next: Conditionals-Macros, Prev: Conditional Syntax, Up: Conditionals
661 Keeping Deleted Code for Future Reference
662 -----------------------------------------
664 If you replace or delete a part of the program but want to keep the
665 old code around as a comment for future reference, the easy way to do
666 this is to put `#if 0' before it and `#endif' after it. This is better
667 than using comment delimiters `/*' and `*/' since those won't work if
668 the code already contains comments (C comments do not nest).
670 This works even if the code being turned off contains conditionals,
671 but they must be entire conditionals (balanced `#if' and `#endif').
673 Conversely, do not use `#if 0' for comments which are not C code.
674 Use the comment delimiters `/*' and `*/' instead. The interior of `#if
675 0' must consist of complete tokens; in particular, singlequote
676 characters must balance. But comments often contain unbalanced
677 singlequote characters (known in English as apostrophes). These
678 confuse `#if 0'. They do not confuse `/*'.
681 File: cpp.info, Node: Conditionals-Macros, Next: Assertions, Prev: Deleted Code, Up: Conditionals
683 Conditionals and Macros
684 -----------------------
686 Conditionals are useful in connection with macros or assertions,
687 because those are the only ways that an expression's value can vary
688 from one compilation to another. A `#if' directive whose expression
689 uses no macros or assertions is equivalent to `#if 1' or `#if 0'; you
690 might as well determine which one, by computing the value of the
691 expression yourself, and then simplify the program.
693 For example, here is a conditional that tests the expression
694 `BUFSIZE == 1020', where `BUFSIZE' must be a macro.
697 printf ("Large buffers!\n");
698 #endif /* BUFSIZE is large */
700 (Programmers often wish they could test the size of a variable or
701 data type in `#if', but this does not work. The preprocessor does not
702 understand `sizeof', or typedef names, or even the type keywords such
705 The special operator `defined' is used in `#if' expressions to test
706 whether a certain name is defined as a macro. Either `defined NAME' or
707 `defined (NAME)' is an expression whose value is 1 if NAME is defined
708 as macro at the current point in the program, and 0 otherwise. For the
709 `defined' operator it makes no difference what the definition of the
710 macro is; all that matters is whether there is a definition. Thus, for
713 #if defined (vax) || defined (ns16000)
715 would succeed if either of the names `vax' and `ns16000' is defined as
716 a macro. You can test the same condition using assertions (*note
717 Assertions::.), like this:
719 #if #cpu (vax) || #cpu (ns16000)
721 If a macro is defined and later undefined with `#undef', subsequent
722 use of the `defined' operator returns 0, because the name is no longer
723 defined. If the macro is defined again with another `#define',
724 `defined' will recommence returning 1.
726 Conditionals that test whether just one name is defined are very
727 common, so there are two special short conditional directives for this
731 is equivalent to `#if defined (NAME)'.
734 is equivalent to `#if ! defined (NAME)'.
736 Macro definitions can vary between compilations for several reasons.
738 * Some macros are predefined on each kind of machine. For example,
739 on a Vax, the name `vax' is a predefined macro. On other
740 machines, it would not be defined.
742 * Many more macros are defined by system header files. Different
743 systems and machines define different macros, or give them
744 different values. It is useful to test these macros with
745 conditionals to avoid using a system feature on a machine where it
748 * Macros are a common way of allowing users to customize a program
749 for different machines or applications. For example, the macro
750 `BUFSIZE' might be defined in a configuration file for your
751 program that is included as a header file in each source file. You
752 would use `BUFSIZE' in a preprocessing conditional in order to
753 generate different code depending on the chosen configuration.
755 * Macros can be defined or undefined with `-D' and `-U' command
756 options when you compile the program. You can arrange to compile
757 the same source file into two different programs by choosing a
758 macro name to specify which program you want, writing conditionals
759 to test whether or how this macro is defined, and then controlling
760 the state of the macro with compiler command options. *Note
763 Assertions are usually predefined, but can be defined with
764 preprocessor directives or command-line options.
767 File: cpp.info, Node: Assertions, Next: #error Directive, Prev: Conditionals-Macros, Up: Conditionals
772 "Assertions" are a more systematic alternative to macros in writing
773 conditionals to test what sort of computer or system the compiled
774 program will run on. Assertions are usually predefined, but you can
775 define them with preprocessing directives or command-line options.
777 The macros traditionally used to describe the type of target are not
778 classified in any way according to which question they answer; they may
779 indicate a hardware architecture, a particular hardware model, an
780 operating system, a particular version of an operating system, or
781 specific configuration options. These are jumbled together in a single
782 namespace. In contrast, each assertion consists of a named question and
783 an answer. The question is usually called the "predicate". An
784 assertion looks like this:
788 You must use a properly formed identifier for PREDICATE. The value of
789 ANSWER can be any sequence of words; all characters are significant
790 except for leading and trailing whitespace, and differences in internal
791 whitespace sequences are ignored. Thus, `x + y' is different from
792 `x+y' but equivalent to `x + y'. `)' is not allowed in an answer.
794 Here is a conditional to test whether the answer ANSWER is asserted
795 for the predicate PREDICATE:
797 #if #PREDICATE (ANSWER)
799 There may be more than one answer asserted for a given predicate. If
800 you omit the answer, you can test whether *any* answer is asserted for
805 Most of the time, the assertions you test will be predefined
806 assertions. GNU C provides three predefined predicates: `system',
807 `cpu', and `machine'. `system' is for assertions about the type of
808 software, `cpu' describes the type of computer architecture, and
809 `machine' gives more information about the computer. For example, on a
810 GNU system, the following assertions would be true:
815 #system (mach 3.SUBVERSION)
817 #system (hurd VERSION)
819 and perhaps others. The alternatives with more or less version
820 information let you ask more or less detailed questions about the type
823 On a Unix system, you would find `#system (unix)' and perhaps one of:
824 `#system (aix)', `#system (bsd)', `#system (hpux)', `#system (lynx)',
825 `#system (mach)', `#system (posix)', `#system (svr3)', `#system
826 (svr4)', or `#system (xpg4)' with possible version numbers following.
828 Other values for `system' are `#system (mvs)' and `#system (vms)'.
830 *Portability note:* Many Unix C compilers provide only one answer
831 for the `system' assertion: `#system (unix)', if they support
832 assertions at all. This is less than useful.
834 An assertion with a multi-word answer is completely different from
835 several assertions with individual single-word answers. For example,
836 the presence of `system (mach 3.0)' does not mean that `system (3.0)'
837 is true. It also does not directly imply `system (mach)', but in GNU
838 C, that last will normally be asserted as well.
840 The current list of possible assertion values for `cpu' is: `#cpu
841 (a29k)', `#cpu (alpha)', `#cpu (arm)', `#cpu (clipper)', `#cpu
842 (convex)', `#cpu (elxsi)', `#cpu (tron)', `#cpu (h8300)', `#cpu
843 (i370)', `#cpu (i386)', `#cpu (i860)', `#cpu (i960)', `#cpu (m68k)',
844 `#cpu (m88k)', `#cpu (mips)', `#cpu (ns32k)', `#cpu (hppa)', `#cpu
845 (pyr)', `#cpu (ibm032)', `#cpu (rs6000)', `#cpu (sh)', `#cpu (sparc)',
846 `#cpu (spur)', `#cpu (tahoe)', `#cpu (vax)', `#cpu (we32000)'.
848 You can create assertions within a C program using `#assert', like
851 #assert PREDICATE (ANSWER)
853 (Note the absence of a `#' before PREDICATE.)
855 Each time you do this, you assert a new true answer for PREDICATE.
856 Asserting one answer does not invalidate previously asserted answers;
857 they all remain true. The only way to remove an assertion is with
858 `#unassert'. `#unassert' has the same syntax as `#assert'. You can
859 also remove all assertions about PREDICATE like this:
863 You can also add or cancel assertions using command options when you
864 run `gcc' or `cpp'. *Note Invocation::.
867 File: cpp.info, Node: #error Directive, Prev: Assertions, Up: Conditionals
869 The `#error' and `#warning' Directives
870 --------------------------------------
872 The directive `#error' causes the preprocessor to report a fatal
873 error. The rest of the line that follows `#error' is used as the error
876 You would use `#error' inside of a conditional that detects a
877 combination of parameters which you know the program does not properly
878 support. For example, if you know that the program will not run
879 properly on a Vax, you might write
882 #error Won't work on Vaxen. See comments at get_last_object.
885 *Note Nonstandard Predefined::, for why this works.
887 If you have several configuration parameters that must be set up by
888 the installation in a consistent way, you can use conditionals to detect
889 an inconsistency and report it with `#error'. For example,
891 #if HASH_TABLE_SIZE % 2 == 0 || HASH_TABLE_SIZE % 3 == 0 \
892 || HASH_TABLE_SIZE % 5 == 0
893 #error HASH_TABLE_SIZE should not be divisible by a small prime
896 The directive `#warning' is like the directive `#error', but causes
897 the preprocessor to issue a warning and continue preprocessing. The
898 rest of the line that follows `#warning' is used as the warning message.
900 You might use `#warning' in obsolete header files, with a message
901 directing the user to the header file which should be used instead.
904 File: cpp.info, Node: Combining Sources, Next: Other Directives, Prev: Conditionals, Up: Top
906 Combining Source Files
907 ======================
909 One of the jobs of the C preprocessor is to inform the C compiler of
910 where each line of C code came from: which source file and which line
913 C code can come from multiple source files if you use `#include';
914 both `#include' and the use of conditionals and macros can cause the
915 line number of a line in the preprocessor output to be different from
916 the line's number in the original source file. You will appreciate the
917 value of making both the C compiler (in error messages) and symbolic
918 debuggers such as GDB use the line numbers in your source file.
920 The C preprocessor builds on this feature by offering a directive by
921 which you can control the feature explicitly. This is useful when a
922 file for input to the C preprocessor is the output from another program
923 such as the `bison' parser generator, which operates on another file
924 that is the true source file. Parts of the output from `bison' are
925 generated from scratch, other parts come from a standard parser file.
926 The rest are copied nearly verbatim from the source file, but their
927 line numbers in the `bison' output are not the same as their original
928 line numbers. Naturally you would like compiler error messages and
929 symbolic debuggers to know the original source file and line number of
930 each line in the `bison' input.
932 `bison' arranges this by writing `#line' directives into the output
933 file. `#line' is a directive that specifies the original line number
934 and source file name for subsequent input in the current preprocessor
935 input file. `#line' has three variants:
938 Here LINENUM is a decimal integer constant. This specifies that
939 the line number of the following line of input, in its original
940 source file, was LINENUM.
942 `#line LINENUM FILENAME'
943 Here LINENUM is a decimal integer constant and FILENAME is a
944 string constant. This specifies that the following line of input
945 came originally from source file FILENAME and its line number there
946 was LINENUM. Keep in mind that FILENAME is not just a file name;
947 it is surrounded by doublequote characters so that it looks like a
950 `#line ANYTHING ELSE'
951 ANYTHING ELSE is checked for macro calls, which are expanded. The
952 result should be a decimal integer constant followed optionally by
953 a string constant, as described above.
955 `#line' directives alter the results of the `__FILE__' and
956 `__LINE__' predefined macros from that point on. *Note Standard
959 The output of the preprocessor (which is the input for the rest of
960 the compiler) contains directives that look much like `#line'
961 directives. They start with just `#' instead of `#line', but this is
962 followed by a line number and file name as in `#line'. *Note Output::.
965 File: cpp.info, Node: Other Directives, Next: Output, Prev: Combining Sources, Up: Top
967 Miscellaneous Preprocessing Directives
968 ======================================
970 This section describes three additional preprocessing directives.
971 They are not very useful, but are mentioned for completeness.
973 The "null directive" consists of a `#' followed by a Newline, with
974 only whitespace (including comments) in between. A null directive is
975 understood as a preprocessing directive but has no effect on the
976 preprocessor output. The primary significance of the existence of the
977 null directive is that an input line consisting of just a `#' will
978 produce no output, rather than a line of output containing just a `#'.
979 Supposedly some old C programs contain such lines.
981 The ANSI standard specifies that the `#pragma' directive has an
982 arbitrary, implementation-defined effect. In the GNU C preprocessor,
983 `#pragma' directives are not used, except for `#pragma once' (*note
984 Once-Only::.). However, they are left in the preprocessor output, so
985 they are available to the compilation pass.
987 The `#ident' directive is supported for compatibility with certain
988 other systems. It is followed by a line of text. On some systems, the
989 text is copied into a special place in the object file; on most systems,
990 the text is ignored and this directive has no effect. Typically
991 `#ident' is only used in header files supplied with those systems where
995 File: cpp.info, Node: Output, Next: Invocation, Prev: Other Directives, Up: Top
997 C Preprocessor Output
998 =====================
1000 The output from the C preprocessor looks much like the input, except
1001 that all preprocessing directive lines have been replaced with blank
1002 lines and all comments with spaces. Whitespace within a line is not
1003 altered; however, a space is inserted after the expansions of most
1006 Source file name and line number information is conveyed by lines of
1009 # LINENUM FILENAME FLAGS
1011 which are inserted as needed into the middle of the input (but never
1012 within a string or character constant). Such a line means that the
1013 following line originated in file FILENAME at line LINENUM.
1015 After the file name comes zero or more flags, which are `1', `2',
1016 `3', or `4'. If there are multiple flags, spaces separate them. Here
1017 is what the flags mean:
1020 This indicates the start of a new file.
1023 This indicates returning to a file (after having included another
1027 This indicates that the following text comes from a system header
1028 file, so certain warnings should be suppressed.
1031 This indicates that the following text should be treated as C.