1084 lines
43 KiB
Plaintext
1084 lines
43 KiB
Plaintext
Info file cpp.info, produced by Makeinfo, -*- Text -*- from input file
|
||
cpp.texi.
|
||
|
||
This file documents the GNU C Preprocessor.
|
||
|
||
Copyright (C) 1987, 1989, 1991 Free Software Foundation, Inc.
|
||
|
||
Permission is granted to make and distribute verbatim copies of
|
||
this manual provided the copyright notice and this permission notice
|
||
are preserved on all copies.
|
||
|
||
Permission is granted to copy and distribute modified versions of
|
||
this manual under the conditions for verbatim copying, provided also
|
||
that the entire resulting derived work is distributed under the terms
|
||
of a permission notice identical to this one.
|
||
|
||
Permission is granted to copy and distribute translations of this
|
||
manual into another language, under the above conditions for modified
|
||
versions.
|
||
|
||
|
||
File: cpp.info, Node: Swallow Semicolon, Next: Side Effects, Prev: Macro Parentheses, Up: Macro Pitfalls
|
||
|
||
Swallowing the Semicolon
|
||
........................
|
||
|
||
Often it is desirable to define a macro that expands into a compound
|
||
statement. Consider, for example, the following macro, that advances a
|
||
pointer (the argument `p' says where to find it) across whitespace
|
||
characters:
|
||
|
||
#define SKIP_SPACES (p, limit) \
|
||
{ register char *lim = (limit); \
|
||
while (p != lim) { \
|
||
if (*p++ != ' ') { \
|
||
p--; break; }}}
|
||
|
||
Here Backslash-Newline is used to split the macro definition, which
|
||
must be a single line, so that it resembles the way such C code would
|
||
be laid out if not part of a macro definition.
|
||
|
||
A call to this macro might be `SKIP_SPACES (p, lim)'. Strictly
|
||
speaking, the call expands to a compound statement, which is a complete
|
||
statement with no need for a semicolon to end it. But it looks like a
|
||
function call. So it minimizes confusion if you can use it like a
|
||
function call, writing a semicolon afterward, as in `SKIP_SPACES (p,
|
||
lim);'
|
||
|
||
But this can cause trouble before `else' statements, because the
|
||
semicolon is actually a null statement. Suppose you write
|
||
|
||
if (*p != 0)
|
||
SKIP_SPACES (p, lim);
|
||
else ...
|
||
|
||
The presence of two statements--the compound statement and a null
|
||
statement--in between the `if' condition and the `else' makes invalid
|
||
C code.
|
||
|
||
The definition of the macro `SKIP_SPACES' can be altered to solve
|
||
this problem, using a `do ... while' statement. Here is how:
|
||
|
||
#define SKIP_SPACES (p, limit) \
|
||
do { register char *lim = (limit); \
|
||
while (p != lim) { \
|
||
if (*p++ != ' ') { \
|
||
p--; break; }}} \
|
||
while (0)
|
||
|
||
Now `SKIP_SPACES (p, lim);' expands into
|
||
|
||
do {...} while (0);
|
||
|
||
which is one statement.
|
||
|
||
|
||
File: cpp.info, Node: Side Effects, Next: Self-Reference, Prev: Swallow Semicolon, Up: Macro Pitfalls
|
||
|
||
Duplication of Side Effects
|
||
...........................
|
||
|
||
Many C programs define a macro `min', for "minimum", like this:
|
||
|
||
#define min(X, Y) ((X) < (Y) ? (X) : (Y))
|
||
|
||
When you use this macro with an argument containing a side effect,
|
||
as shown here,
|
||
|
||
next = min (x + y, foo (z));
|
||
|
||
it expands as follows:
|
||
|
||
next = ((x + y) < (foo (z)) ? (x + y) : (foo (z)));
|
||
|
||
where `x + y' has been substituted for `X' and `foo (z)' for `Y'.
|
||
|
||
The function `foo' is used only once in the statement as it appears
|
||
in the program, but the expression `foo (z)' has been substituted
|
||
twice into the macro expansion. As a result, `foo' might be called
|
||
two times when the statement is executed. If it has side effects or
|
||
if it takes a long time to compute, the results might not be what you
|
||
intended. We say that `min' is an "unsafe" macro.
|
||
|
||
The best solution to this problem is to define `min' in a way that
|
||
computes the value of `foo (z)' only once. The C language offers no
|
||
standard way to do this, but it can be done with GNU C extensions as
|
||
follows:
|
||
|
||
#define min(X, Y) \
|
||
({ typeof (X) __x = (X), __y = (Y); \
|
||
(__x < __y) ? __x : __y; })
|
||
|
||
If you do not wish to use GNU C extensions, the only solution is to
|
||
be careful when *using* the macro `min'. For example, you can
|
||
calculate the value of `foo (z)', save it in a variable, and use that
|
||
variable in `min':
|
||
|
||
#define min(X, Y) ((X) < (Y) ? (X) : (Y))
|
||
...
|
||
{
|
||
int tem = foo (z);
|
||
next = min (x + y, tem);
|
||
}
|
||
|
||
(where we assume that `foo' returns type `int').
|
||
|
||
|
||
File: cpp.info, Node: Self-Reference, Next: Argument Prescan, Prev: Side Effects, Up: Macro Pitfalls
|
||
|
||
Self-Referential Macros
|
||
.......................
|
||
|
||
A "self-referential" macro is one whose name appears in its
|
||
definition. A special feature of ANSI Standard C is that the
|
||
self-reference is not considered a macro call. It is passed into the
|
||
preprocessor output unchanged.
|
||
|
||
Let's consider an example:
|
||
|
||
#define foo (4 + foo)
|
||
|
||
where `foo' is also a variable in your program.
|
||
|
||
Following the ordinary rules, each reference to `foo' will expand
|
||
into `(4 + foo)'; then this will be rescanned and will expand into `(4
|
||
+ (4 + foo))'; and so on until it causes a fatal error (memory full)
|
||
in the preprocessor.
|
||
|
||
However, the special rule about self-reference cuts this process
|
||
short after one step, at `(4 + foo)'. Therefore, this macro definition
|
||
has the possibly useful effect of causing the program to add 4 to the
|
||
value of `foo' wherever `foo' is referred to.
|
||
|
||
In most cases, it is a bad idea to take advantage of this feature.
|
||
A person reading the program who sees that `foo' is a variable will
|
||
not expect that it is a macro as well. The reader will come across the
|
||
identifier `foo' in the program and think its value should be that of
|
||
the variable `foo', whereas in fact the value is four greater.
|
||
|
||
The special rule for self-reference applies also to "indirect"
|
||
self-reference. This is the case where a macro X expands to use a
|
||
macro `y', and `y''s expansion refers to the macro `x'. The resulting
|
||
reference to `x' comes indirectly from the expansion of `x', so it is
|
||
a self-reference and is not further expanded. Thus, after
|
||
|
||
#define x (4 + y)
|
||
#define y (2 * x)
|
||
|
||
`x' would expand into `(4 + (2 * x))'. Clear?
|
||
|
||
But suppose `y' is used elsewhere, not from the definition of `x'.
|
||
Then the use of `x' in the expansion of `y' is not a self-reference
|
||
because `x' is not "in progress". So it does expand. However, the
|
||
expansion of `x' contains a reference to `y', and that is an indirect
|
||
self-reference now because `y' is "in progress". The result is that
|
||
`y' expands to `(2 * (4 + y))'.
|
||
|
||
It is not clear that this behavior would ever be useful, but it is
|
||
specified by the ANSI C standard, so you may need to understand it.
|
||
|
||
|
||
File: cpp.info, Node: Argument Prescan, Next: Cascaded Macros, Prev: Self-Reference, Up: Macro Pitfalls
|
||
|
||
Separate Expansion of Macro Arguments
|
||
.....................................
|
||
|
||
We have explained that the expansion of a macro, including the
|
||
substituted actual arguments, is scanned over again for macro calls to
|
||
be expanded.
|
||
|
||
What really happens is more subtle: first each actual argument text
|
||
is scanned separately for macro calls. Then the results of this are
|
||
substituted into the macro body to produce the macro expansion, and
|
||
the macro expansion is scanned again for macros to expand.
|
||
|
||
The result is that the actual arguments are scanned *twice* to
|
||
expand macro calls in them.
|
||
|
||
Most of the time, this has no effect. If the actual argument
|
||
contained any macro calls, they are expanded during the first scan.
|
||
The result therefore contains no macro calls, so the second scan does
|
||
not change it. If the actual argument were substituted as given, with
|
||
no prescan, the single remaining scan would find the same macro calls
|
||
and produce the same results.
|
||
|
||
You might expect the double scan to change the results when a
|
||
self-referential macro is used in an actual argument of another macro
|
||
(*note Self-Reference::.): the self-referential macro would be
|
||
expanded once in the first scan, and a second time in the second scan.
|
||
But this is not what happens. The self-references that do not expand
|
||
in the first scan are marked so that they will not expand in the
|
||
second scan either.
|
||
|
||
The prescan is not done when an argument is stringified or
|
||
concatenated. Thus,
|
||
|
||
#define str(s) #s
|
||
#define foo 4
|
||
str (foo)
|
||
|
||
expands to `"foo"'. Once more, prescan has been prevented from having
|
||
any noticeable effect.
|
||
|
||
More precisely, stringification and concatenation use the argument
|
||
as written, in un-prescanned form. The same actual argument would be
|
||
used in prescanned form if it is substituted elsewhere without
|
||
stringification or concatenation.
|
||
|
||
#define str(s) #s lose(s)
|
||
#define foo 4
|
||
str (foo)
|
||
|
||
expands to `"foo" lose(4)'.
|
||
|
||
You might now ask, "Why mention the prescan, if it makes no
|
||
difference? And why not skip it and make the preprocessor faster?"
|
||
The answer is that the prescan does make a difference in three special
|
||
cases:
|
||
|
||
* Nested calls to a macro.
|
||
|
||
* Macros that call other macros that stringify or concatenate.
|
||
|
||
* Macros whose expansions contain unshielded commas.
|
||
|
||
We say that "nested" calls to a macro occur when a macro's actual
|
||
argument contains a call to that very macro. For example, if `f' is a
|
||
macro that expects one argument, `f (f (1))' is a nested pair of calls
|
||
to `f'. The desired expansion is made by expanding `f (1)' and
|
||
substituting that into the definition of `f'. The prescan causes the
|
||
expected result to happen. Without the prescan, `f (1)' itself would
|
||
be substituted as an actual argument, and the inner use of `f' would
|
||
appear during the main scan as an indirect self-reference and would not
|
||
be expanded. Here, the prescan cancels an undesirable side effect (in
|
||
the medical, not computational, sense of the term) of the special rule
|
||
for self-referential macros.
|
||
|
||
But prescan causes trouble in certain other cases of nested macro
|
||
calls. Here is an example:
|
||
|
||
#define foo a,b
|
||
#define bar(x) lose(x)
|
||
#define lose(x) (1 + (x))
|
||
|
||
bar(foo)
|
||
|
||
We would like `bar(foo)' to turn into `(1 + (foo))', which would then
|
||
turn into `(1 + (a,b))'. But instead, `bar(foo)' expands into
|
||
`lose(a,b)', and you get an error because `lose' requires a single
|
||
argument. In this case, the problem is easily solved by the same
|
||
parentheses that ought to be used to prevent misnesting of arithmetic
|
||
operations:
|
||
|
||
#define foo (a,b)
|
||
#define bar(x) lose((x))
|
||
|
||
The problem is more serious when the operands of the macro are not
|
||
expressions; for example, when they are statements. Then parentheses
|
||
are unacceptable because they would make for invalid C code:
|
||
|
||
#define foo { int a, b; ... }
|
||
|
||
In GNU C you can shield the commas using the `({...})' construct which
|
||
turns a compound statement into an expression:
|
||
|
||
#define foo ({ int a, b; ... })
|
||
|
||
Or you can rewrite the macro definition to avoid such commas:
|
||
|
||
#define foo { int a; int b; ... }
|
||
|
||
There is also one case where prescan is useful. It is possible to
|
||
use prescan to expand an argument and then stringify it--if you use
|
||
two levels of macros. Let's add a new macro `xstr' to the example
|
||
shown above:
|
||
|
||
#define xstr(s) str(s)
|
||
#define str(s) #s
|
||
#define foo 4
|
||
xstr (foo)
|
||
|
||
This expands into `"4"', not `"foo"'. The reason for the
|
||
difference is that the argument of `xstr' is expanded at prescan
|
||
(because `xstr' does not specify stringification or concatenation of
|
||
the argument). The result of prescan then forms the actual argument
|
||
for `str'. `str' uses its argument without prescan because it
|
||
performs stringification; but it cannot prevent or undo the prescanning
|
||
already done by `xstr'.
|
||
|
||
|
||
File: cpp.info, Node: Cascaded Macros, Prev: Argument Prescan, Up: Macro Pitfalls
|
||
|
||
Cascaded Use of Macros
|
||
......................
|
||
|
||
A "cascade" of macros is when one macro's body contains a reference
|
||
to another macro. This is very common practice. For example,
|
||
|
||
#define BUFSIZE 1020
|
||
#define TABLESIZE BUFSIZE
|
||
|
||
This is not at all the same as defining `TABLESIZE' to be `1020'.
|
||
The `#define' for `TABLESIZE' uses exactly the body you specify--in
|
||
this case, `BUFSIZE'--and does not check to see whether it too is the
|
||
name of a macro.
|
||
|
||
It's only when you *use* `TABLESIZE' that the result of its
|
||
expansion is checked for more macro names.
|
||
|
||
This makes a difference if you change the definition of `BUFSIZE'
|
||
at some point in the source file. `TABLESIZE', defined as shown, will
|
||
always expand using the definition of `BUFSIZE' that is currently in
|
||
effect:
|
||
|
||
#define BUFSIZE 1020
|
||
#define TABLESIZE BUFSIZE
|
||
#undef BUFSIZE
|
||
#define BUFSIZE 37
|
||
|
||
Now `TABLESIZE' expands (in two stages) to `37'.
|
||
|
||
|
||
File: cpp.info, Node: Conditionals, Next: Combining Sources, Prev: Macros, Up: Top
|
||
|
||
Conditionals
|
||
============
|
||
|
||
In a macro processor, a "conditional" is a command that allows a
|
||
part of the program to be ignored during compilation, on some
|
||
conditions. In the C preprocessor, a conditional can test either an
|
||
arithmetic expression or whether a name is defined as a macro.
|
||
|
||
A conditional in the C preprocessor resembles in some ways an `if'
|
||
statement in C, but it is important to understand the difference
|
||
between them. The condition in an `if' statement is tested during the
|
||
execution of your program. Its purpose is to allow your program to
|
||
behave differently from run to run, depending on the data it is
|
||
operating on. The condition in a preprocessor conditional command is
|
||
tested when your program is compiled. Its purpose is to allow
|
||
different code to be included in the program depending on the
|
||
situation at the time of compilation.
|
||
|
||
* Menu:
|
||
|
||
* Uses: Conditional Uses. What conditionals are for.
|
||
* Syntax: Conditional Syntax. How conditionals are written.
|
||
* Deletion: Deleted Code. Making code into a comment.
|
||
* Macros: Conditionals-Macros. Why conditionals are used with macros.
|
||
* Errors: #error Command. Detecting inconsistent compilation parameters.
|
||
|
||
|
||
File: cpp.info, Node: Conditional Uses, Next: Conditional Syntax, Prev: Conditionals, Up: Conditionals
|
||
|
||
Why Conditionals are Used
|
||
-------------------------
|
||
|
||
Generally there are three kinds of reason to use a conditional.
|
||
|
||
* A program may need to use different code depending on the machine
|
||
or operating system it is to run on. In some cases the code for
|
||
one operating system may be erroneous on another operating
|
||
system; for example, it might refer to library routines that do
|
||
not exist on the other system. When this happens, it is not
|
||
enough to avoid executing the invalid code: merely having it in
|
||
the program makes it impossible to link the program and run it.
|
||
With a preprocessor conditional, the offending code can be
|
||
effectively excised from the program when it is not valid.
|
||
|
||
* You may want to be able to compile the same source file into two
|
||
different programs. Sometimes the difference between the
|
||
programs is that one makes frequent time-consuming consistency
|
||
checks on its intermediate data while the other does not.
|
||
|
||
* A conditional whose condition is always false is a good way to
|
||
exclude code from the program but keep it as a sort of comment
|
||
for future reference.
|
||
|
||
Most simple programs that are intended to run on only one machine
|
||
will not need to use preprocessor conditionals.
|
||
|
||
|
||
File: cpp.info, Node: Conditional Syntax, Next: Deleted Code, Prev: Conditional Uses, Up: Conditionals
|
||
|
||
Syntax of Conditionals
|
||
----------------------
|
||
|
||
A conditional in the C preprocessor begins with a "conditional
|
||
command": `#if', `#ifdef' or `#ifndef'. *Note Conditionals-Macros::,
|
||
for information on `#ifdef' and `#ifndef'; only `#if' is explained
|
||
here.
|
||
|
||
* Menu:
|
||
|
||
* If: #if Command. Basic conditionals using `#if' and `#endif'.
|
||
* Else: #else Command. Including some text if the condition fails.
|
||
* Elif: #elif Command. Testing several alternative possibilities.
|
||
|
||
|
||
File: cpp.info, Node: #if Command, Next: #else Command, Prev: Conditional Syntax, Up: Conditional Syntax
|
||
|
||
The `#if' Command
|
||
.................
|
||
|
||
The `#if' command in its simplest form consists of
|
||
|
||
#if EXPRESSION
|
||
CONTROLLED TEXT
|
||
#endif /* EXPRESSION */
|
||
|
||
The comment following the `#endif' is not required, but it is a good
|
||
practice because it helps people match the `#endif' to the
|
||
corresponding `#if'. Such comments should always be used, except in
|
||
short conditionals that are not nested. In fact, you can put anything
|
||
at all after the `#endif' and it will be ignored by the GNU C
|
||
preprocessor, but only comments are acceptable in ANSI Standard C.
|
||
|
||
EXPRESSION is a C expression of integer type, subject to stringent
|
||
restrictions. It may contain
|
||
|
||
* Integer constants, which are all regarded as `long' or `unsigned
|
||
long'.
|
||
|
||
* Character constants, which are interpreted according to the
|
||
character set and conventions of the machine and operating system
|
||
on which the preprocessor is running. The GNU C preprocessor
|
||
uses the C data type `char' for these character constants;
|
||
therefore, whether some character codes are negative is
|
||
determined by the C compiler used to compile the preprocessor.
|
||
If it treats `char' as signed, then character codes large enough
|
||
to set the sign bit will be considered negative; otherwise, no
|
||
character code is considered negative.
|
||
|
||
* Arithmetic operators for addition, subtraction, multiplication,
|
||
division, bitwise operations, shifts, comparisons, and `&&' and
|
||
`||'.
|
||
|
||
* Identifiers that are not macros, which are all treated as zero(!).
|
||
|
||
* Macro calls. All macro calls in the expression are expanded
|
||
before actual computation of the expression's value begins.
|
||
|
||
Note that `sizeof' operators and `enum'-type values are not allowed.
|
||
`enum'-type values, like all other identifiers that are not taken as
|
||
macro calls and expanded, are treated as zero.
|
||
|
||
The CONTROLLED TEXT inside of a conditional can include
|
||
preprocessor commands. Then the commands inside the conditional are
|
||
obeyed only if that branch of the conditional succeeds. The text can
|
||
also contain other conditional groups. However, the `#if''s and
|
||
`#endif''s must balance.
|
||
|
||
|
||
File: cpp.info, Node: #else Command, Next: #elif Command, Prev: #if Command, Up: Conditional Syntax
|
||
|
||
The `#else' Command
|
||
...................
|
||
|
||
The `#else' command can be added to a conditional to provide
|
||
alternative text to be used if the condition is false. This is what
|
||
it looks like:
|
||
|
||
#if EXPRESSION
|
||
TEXT-IF-TRUE
|
||
#else /* Not EXPRESSION */
|
||
TEXT-IF-FALSE
|
||
#endif /* Not EXPRESSION */
|
||
|
||
If EXPRESSION is nonzero, and thus the TEXT-IF-TRUE is active, then
|
||
`#else' acts like a failing conditional and the TEXT-IF-FALSE is
|
||
ignored. Contrariwise, if the `#if' conditional fails, the
|
||
TEXT-IF-FALSE is considered included.
|
||
|
||
|
||
File: cpp.info, Node: #elif Command, Prev: #else Command, Up: Conditional Syntax
|
||
|
||
The `#elif' Command
|
||
...................
|
||
|
||
One common case of nested conditionals is used to check for more
|
||
than two possible alternatives. For example, you might have
|
||
|
||
#if X == 1
|
||
...
|
||
#else /* X != 1 */
|
||
#if X == 2
|
||
...
|
||
#else /* X != 2 */
|
||
...
|
||
#endif /* X != 2 */
|
||
#endif /* X != 1 */
|
||
|
||
Another conditional command, `#elif', allows this to be abbreviated
|
||
as follows:
|
||
|
||
#if X == 1
|
||
...
|
||
#elif X == 2
|
||
...
|
||
#else /* X != 2 and X != 1*/
|
||
...
|
||
#endif /* X != 2 and X != 1*/
|
||
|
||
`#elif' stands for "else if". Like `#else', it goes in the middle
|
||
of a `#if'-`#endif' pair and subdivides it; it does not require a
|
||
matching `#endif' of its own. Like `#if', the `#elif' command
|
||
includes an expression to be tested.
|
||
|
||
The text following the `#elif' is processed only if the original
|
||
`#if'-condition failed and the `#elif' condition succeeds. More than
|
||
one `#elif' can go in the same `#if'-`#endif' group. Then the text
|
||
after each `#elif' is processed only if the `#elif' condition succeeds
|
||
after the original `#if' and any previous `#elif''s within it have
|
||
failed. `#else' is equivalent to `#elif 1', and `#else' is allowed
|
||
after any number of `#elif''s, but `#elif' may not follow `#else'.
|
||
|
||
|
||
File: cpp.info, Node: Deleted Code, Next: Conditionals-Macros, Prev: Conditional Syntax, Up: Conditionals
|
||
|
||
Keeping Deleted Code for Future Reference
|
||
-----------------------------------------
|
||
|
||
If you replace or delete a part of the program but want to keep the
|
||
old code around as a comment for future reference, the easy way to do
|
||
this is to put `#if 0' before it and `#endif' after it.
|
||
|
||
This works even if the code being turned off contains conditionals,
|
||
but they must be entire conditionals (balanced `#if' and `#endif').
|
||
|
||
|
||
File: cpp.info, Node: Conditionals-Macros, Next: #error Command, Prev: Deleted Code, Up: Conditionals
|
||
|
||
Conditionals and Macros
|
||
-----------------------
|
||
|
||
Conditionals are rarely useful except in connection with macros. A
|
||
`#if' command whose expression uses no macros is equivalent to `#if 1'
|
||
or `#if 0'; you might as well determine which one, by computing the
|
||
value of the expression yourself, and then simplify the program. But
|
||
when the expression uses macros, its value can vary from compilation
|
||
to compilation.
|
||
|
||
For example, here is a conditional that tests the expression
|
||
`BUFSIZE == 1020', where `BUFSIZE' must be a macro.
|
||
|
||
#if BUFSIZE == 1020
|
||
printf ("Large buffers!\n");
|
||
#endif /* BUFSIZE is large */
|
||
|
||
The special operator `defined' may be used in `#if' expressions to
|
||
test whether a certain name is defined as a macro. Either `defined
|
||
NAME' or `defined (NAME)' is an expression whose value is 1 if NAME is
|
||
defined as macro at the current point in the program, and 0 otherwise.
|
||
For the `defined' operator it makes no difference what the definition
|
||
of the macro is; all that matters is whether there is a definition.
|
||
Thus, for example,
|
||
|
||
#if defined (vax) || defined (ns16000)
|
||
|
||
would include the following code if either of the names `vax' and
|
||
`ns16000' is defined as a macro.
|
||
|
||
If a macro is defined and later undefined with `#undef', subsequent
|
||
use of the `defined' operator will return 0, because the name is no
|
||
longer defined. If the macro is defined again with another `#define',
|
||
`defined' will recommence returning 1.
|
||
|
||
Conditionals that test just the definedness of one name are very
|
||
common, so there are two special short conditional commands for this
|
||
case. They are
|
||
|
||
`#ifdef NAME'
|
||
is equivalent to `#if defined (NAME)'.
|
||
|
||
`#ifndef NAME'
|
||
is equivalent to `#if ! defined (NAME)'.
|
||
|
||
Macro definitions can vary between compilations for several reasons.
|
||
|
||
* Some macros are predefined on each kind of machine. For example,
|
||
on a Vax, the name `vax' is a predefined macro. On other
|
||
machines, it would not be defined.
|
||
|
||
* Many more macros are defined by system header files. Different
|
||
systems and machines define different macros, or give them
|
||
different values. It is useful to test these macros with
|
||
conditionals to avoid using a system feature on a machine where
|
||
it is not implemented.
|
||
|
||
* Macros are a common way of allowing users to customize a program
|
||
for different machines or applications. For example, the macro
|
||
`BUFSIZE' might be defined in a configuration file for your
|
||
program that is included as a header file in each source file.
|
||
You would use `BUFSIZE' in a preprocessor conditional in order to
|
||
generate different code depending on the chosen configuration.
|
||
|
||
* Macros can be defined or undefined with `-D' and `-U' command
|
||
options when you compile the program. You can arrange to compile
|
||
the same source file into two different programs by choosing a
|
||
macro name to specify which program you want, writing conditionals
|
||
to test whether or how this macro is defined, and then controlling
|
||
the state of the macro with compiler command options. *Note
|
||
Invocation::.
|
||
|
||
|
||
File: cpp.info, Node: #error Command, Prev: Conditionals-Macros, Up: Conditionals
|
||
|
||
The `#error' and `#warning' Commands
|
||
------------------------------------
|
||
|
||
The command `#error' causes the preprocessor to report a fatal
|
||
error. The rest of the line that follows `#error' is used as the
|
||
error message.
|
||
|
||
You would use `#error' inside of a conditional that detects a
|
||
combination of parameters which you know the program does not properly
|
||
support. For example, if you know that the program will not run
|
||
properly on a Vax, you might write
|
||
|
||
#ifdef vax
|
||
#error Won't work on Vaxen. See comments at get_last_object.
|
||
#endif
|
||
|
||
*Note Nonstandard Predefined::, for why this works.
|
||
|
||
If you have several configuration parameters that must be set up by
|
||
the installation in a consistent way, you can use conditionals to
|
||
detect an inconsistency and report it with `#error'. For example,
|
||
|
||
#if HASH_TABLE_SIZE % 2 == 0 || HASH_TABLE_SIZE % 3 == 0 \
|
||
|| HASH_TABLE_SIZE % 5 == 0
|
||
#error HASH_TABLE_SIZE should not be divisible by a small prime
|
||
#endif
|
||
|
||
The command `#warning' is like the command `#error', but causes the
|
||
preprocessor to issue a warning and continue preprocessing. The rest
|
||
of the line that follows `#warning' is used as the warning message.
|
||
|
||
You might use `#warning' in obsolete header files, with a message
|
||
directing the user to the header file which should be used instead.
|
||
|
||
|
||
File: cpp.info, Node: Combining Sources, Next: Other Commands, Prev: Conditionals, Up: Top
|
||
|
||
Combining Source Files
|
||
======================
|
||
|
||
One of the jobs of the C preprocessor is to inform the C compiler
|
||
of where each line of C code came from: which source file and which
|
||
line number.
|
||
|
||
C code can come from multiple source files if you use `#include';
|
||
both `#include' and the use of conditionals and macros can cause the
|
||
line number of a line in the preprocessor output to be different from
|
||
the line's number in the original source file. You will appreciate
|
||
the value of making both the C compiler (in error messages) and
|
||
symbolic debuggers such as GDB use the line numbers in your source
|
||
file.
|
||
|
||
The C preprocessor builds on this feature by offering a command by
|
||
which you can control the feature explicitly. This is useful when a
|
||
file for input to the C preprocessor is the output from another
|
||
program such as the `bison' parser generator, which operates on
|
||
another file that is the true source file. Parts of the output from
|
||
`bison' are generated from scratch, other parts come from a standard
|
||
parser file. The rest are copied nearly verbatim from the source
|
||
file, but their line numbers in the `bison' output are not the same as
|
||
their original line numbers. Naturally you would like compiler error
|
||
messages and symbolic debuggers to know the original source file and
|
||
line number of each line in the `bison' input.
|
||
|
||
`bison' arranges this by writing `#line' commands into the output
|
||
file. `#line' is a command that specifies the original line number
|
||
and source file name for subsequent input in the current preprocessor
|
||
input file. `#line' has three variants:
|
||
|
||
`#line LINENUM'
|
||
Here LINENUM is a decimal integer constant. This specifies that
|
||
the line number of the following line of input, in its original
|
||
source file, was LINENUM.
|
||
|
||
`#line LINENUM FILENAME'
|
||
Here LINENUM is a decimal integer constant and FILENAME is a
|
||
string constant. This specifies that the following line of input
|
||
came originally from source file FILENAME and its line number
|
||
there was LINENUM. Keep in mind that FILENAME is not just a file
|
||
name; it is surrounded by doublequote characters so that it looks
|
||
like a string constant.
|
||
|
||
`#line ANYTHING ELSE'
|
||
ANYTHING ELSE is checked for macro calls, which are expanded.
|
||
The result should be a decimal integer constant followed
|
||
optionally by a string constant, as described above.
|
||
|
||
`#line' commands alter the results of the `__FILE__' and `__LINE__'
|
||
predefined macros from that point on. *Note Standard Predefined::.
|
||
|
||
|
||
File: cpp.info, Node: Other Commands, Next: Output, Prev: Combining Sources, Up: Top
|
||
|
||
Miscellaneous Preprocessor Commands
|
||
===================================
|
||
|
||
This section describes three additional preprocessor commands.
|
||
They are not very useful, but are mentioned for completeness.
|
||
|
||
The "null command" consists of a `#' followed by a Newline, with
|
||
only whitespace (including comments) in between. A null command is
|
||
understood as a preprocessor command but has no effect on the
|
||
preprocessor output. The primary significance of the existence of the
|
||
null command is that an input line consisting of just a `#' will
|
||
produce no output, rather than a line of output containing just a `#'.
|
||
Supposedly some old C programs contain such lines.
|
||
|
||
The ANSI standard specifies that the `#pragma' command has an
|
||
arbitrary, implementation-defined effect. In the GNU C preprocessor,
|
||
`#pragma' commands are ignored, except for `#pragma once' (*note
|
||
Once-Only::.).
|
||
|
||
The `#ident' command is supported for compatibility with certain
|
||
other systems. It is followed by a line of text. On some systems, the
|
||
text is copied into a special place in the object file; on most
|
||
systems, the text is ignored and this directive has no effect.
|
||
Typically `#ident' is only used in header files supplied with those
|
||
systems where it is meaningful.
|
||
|
||
|
||
File: cpp.info, Node: Output, Next: Invocation, Prev: Other Commands, Up: Top
|
||
|
||
C Preprocessor Output
|
||
=====================
|
||
|
||
The output from the C preprocessor looks much like the input, except
|
||
that all preprocessor command lines have been replaced with blank lines
|
||
and all comments with spaces. Whitespace within a line is not altered;
|
||
however, a space is inserted after the expansions of most macro calls.
|
||
|
||
Source file name and line number information is conveyed by lines of
|
||
the form
|
||
|
||
# LINENUM FILENAME FLAG
|
||
|
||
which are inserted as needed into the middle of the input (but never
|
||
within a string or character constant). Such a line means that the
|
||
following line originated in file FILENAME at line LINENUM.
|
||
|
||
The third field, FLAG, may be a number, or may be absent. It is
|
||
`1' for the beginning of a new source file, and `2' for return to an
|
||
old source file at the end of an included file. It is absent
|
||
otherwise.
|
||
|
||
|
||
File: cpp.info, Node: Invocation, Next: Concept Index, Prev: Output, Up: Top
|
||
|
||
Invoking the C Preprocessor
|
||
===========================
|
||
|
||
Most often when you use the C preprocessor you will not have to
|
||
invoke it explicitly: the C compiler will do so automatically.
|
||
However, the preprocessor is sometimes useful individually.
|
||
|
||
The C preprocessor expects two file names as arguments, INFILE and
|
||
OUTFILE. The preprocessor reads INFILE together with any other files
|
||
it specifies with `#include'. All the output generated by the
|
||
combined input files is written in OUTFILE.
|
||
|
||
Either INFILE or OUTFILE may be `-', which as INFILE means to read
|
||
from standard input and as OUTFILE means to write to standard output.
|
||
Also, if OUTFILE or both file names are omitted, the standard output
|
||
and standard input are used for the omitted file names.
|
||
|
||
Here is a table of command options accepted by the C preprocessor.
|
||
These options can also be given when compiling a C program; they are
|
||
passed along automatically to the preprocessor when it is invoked by
|
||
the compiler.
|
||
|
||
`-P'
|
||
Inhibit generation of `#'-lines with line-number information in
|
||
the output from the preprocessor (*note Output::.). This might be
|
||
useful when running the preprocessor on something that is not C
|
||
code and will be sent to a program which might be confused by the
|
||
`#'-lines.
|
||
|
||
`-C'
|
||
Do not discard comments: pass them through to the output file.
|
||
Comments appearing in arguments of a macro call will be copied to
|
||
the output before the expansion of the macro call.
|
||
|
||
`-trigraphs'
|
||
Process ANSI standard trigraph sequences. These are
|
||
three-character sequences, all starting with `??', that are
|
||
defined by ANSI C to stand for single characters. For example,
|
||
`??/' stands for `\', so `'??/n'' is a character constant for a
|
||
newline. Strictly speaking, the GNU C preprocessor does not
|
||
support all programs in ANSI Standard C unless `-trigraphs' is
|
||
used, but if you ever notice the difference it will be with
|
||
relief.
|
||
|
||
You don't want to know any more about trigraphs.
|
||
|
||
`-pedantic'
|
||
Issue warnings required by the ANSI C standard in certain cases
|
||
such as when text other than a comment follows `#else' or
|
||
`#endif'.
|
||
|
||
`-pedantic-errors'
|
||
Like `-pedantic', except that errors are produced rather than
|
||
warnings.
|
||
|
||
`-Wtrigraphs'
|
||
Warn if any trigraphs are encountered (assuming they are enabled).
|
||
|
||
`-Wcomment'
|
||
Warn whenever a comment-start sequence `/*' appears in a comment.
|
||
|
||
`-Wall'
|
||
Requests both `-Wtrigraphs' and `-Wcomment' (but not
|
||
`-Wtraditional').
|
||
|
||
`-Wtraditional'
|
||
Warn about certain constructs that behave differently in
|
||
traditional and ANSI C.
|
||
|
||
`-I DIRECTORY'
|
||
Add the directory DIRECTORY to the end of the list of directories
|
||
to be searched for header files (*note Include Syntax::.). This
|
||
can be used to override a system header file, substituting your
|
||
own version, since these directories are searched before the
|
||
system header file directories. If you use more than one `-I'
|
||
option, the directories are scanned in left-to-right order; the
|
||
standard system directories come after.
|
||
|
||
`-I-'
|
||
Any directories specified with `-I' options before the `-I-'
|
||
option are searched only for the case of `#include "FILE"'; they
|
||
are not searched for `#include <FILE>'.
|
||
|
||
If additional directories are specified with `-I' options after
|
||
the `-I-', these directories are searched for all `#include'
|
||
directives.
|
||
|
||
In addition, the `-I-' option inhibits the use of the current
|
||
directory as the first search directory for `#include "FILE"'.
|
||
Therefore, the current directory is searched only if it is
|
||
requested explicitly with `-I.'. Specifying both `-I-' and `-I.'
|
||
allows you to control precisely which directories are searched
|
||
before the current one and which are searched after.
|
||
|
||
`-nostdinc'
|
||
Do not search the standard system directories for header files.
|
||
Only the directories you have specified with `-I' options (and
|
||
the current directory, if appropriate) are searched.
|
||
|
||
`-nostdinc++'
|
||
Do not search for header files in the C++-specific standard
|
||
directories, but do still search the other standard directories.
|
||
(This option is used when building `libg++'.)
|
||
|
||
`-D NAME'
|
||
Predefine NAME as a macro, with definition `1'.
|
||
|
||
`-D NAME=DEFINITION'
|
||
Predefine NAME as a macro, with definition DEFINITION. There are
|
||
no restrictions on the contents of DEFINITION, but if you are
|
||
invoking the preprocessor from a shell or shell-like program you
|
||
may need to use the shell's quoting syntax to protect characters
|
||
such as spaces that have a meaning in the shell syntax. If you
|
||
use more than one `-D' for the same NAME, the rightmost
|
||
definition takes effect.
|
||
|
||
`-U NAME'
|
||
Do not predefine NAME. If both `-U' and `-D' are specified for
|
||
one name, the `-U' beats the `-D' and the name is not predefined.
|
||
|
||
`-undef'
|
||
Do not predefine any nonstandard macros.
|
||
|
||
`-dM'
|
||
Instead of outputting the result of preprocessing, output a list
|
||
of `#define' commands for all the macros defined during the
|
||
execution of the preprocessor, including predefined macros. This
|
||
gives you a way of finding out what is predefined in your version
|
||
of the preprocessor; assuming you have no file `foo.h', the
|
||
command
|
||
|
||
touch foo.h; cpp -dM foo.h
|
||
|
||
will show the values of any predefined macros.
|
||
|
||
`-dD'
|
||
Like `-dM' except in two respects: it does *not* include the
|
||
predefined macros, and it outputs *both* the `#define' commands
|
||
and the result of preprocessing. Both kinds of output go to the
|
||
standard output file.
|
||
|
||
`-M'
|
||
Instead of outputting the result of preprocessing, output a rule
|
||
suitable for `make' describing the dependencies of the main
|
||
source file. The preprocessor outputs one `make' rule containing
|
||
the object file name for that source file, a colon, and the names
|
||
of all the included files. If there are many included files then
|
||
the rule is split into several lines using `\'-newline.
|
||
|
||
This feature is used in automatic updating of makefiles.
|
||
|
||
`-MM'
|
||
Like `-M' but mention only the files included with `#include
|
||
"FILE"'. System header files included with `#include <FILE>' are
|
||
omitted.
|
||
|
||
`-MD'
|
||
Like `-M' but the dependency information is written to files with
|
||
names made by replacing `.c' with `.d' at the end of the input
|
||
file names. This is in addition to compiling the file as
|
||
specified--`-MD' does not inhibit ordinary compilation the way
|
||
`-M' does.
|
||
|
||
In Mach, you can use the utility `md' to merge the `.d' files
|
||
into a single dependency file suitable for using with the `make'
|
||
command.
|
||
|
||
`-MMD'
|
||
Like `-MD' except mention only user header files, not system
|
||
header files.
|
||
|
||
`-H'
|
||
Print the name of each header file used, in addition to other
|
||
normal activities.
|
||
|
||
`-imacros FILE'
|
||
Process FILE as input, discarding the resulting output, before
|
||
processing the regular input file. Because the output generated
|
||
from FILE is discarded, the only effect of `-imacros FILE' is to
|
||
make the macros defined in FILE available for use in the main
|
||
input.
|
||
|
||
`-include FILE'
|
||
Process FILE as input, and include all the resulting output,
|
||
before processing the regular input file.
|
||
|
||
`-lang-c'
|
||
`-lang-c++'
|
||
`-lang-objc'
|
||
`-lang-objc++'
|
||
Specify the source language. `-lang-c++' makes the preprocessor
|
||
handle C++ comment syntax, and includes extra default include
|
||
directories for C++, and `-lang-objc' enables the Objective C
|
||
`#import' directive. `-lang-c' explicitly turns off both of
|
||
these extensions, and `-lang-objc++' enables both.
|
||
|
||
These options are generated by the compiler driver `gcc', but not
|
||
passed from the `gcc' command line.
|
||
|
||
`-lint'
|
||
Look for commands to the program checker `lint' embedded in
|
||
comments, and emit them preceded by `#pragma lint'. For example,
|
||
the comment `/* NOTREACHED */' becomes `#pragma lint NOTREACHED'.
|
||
|
||
This option is available only when you call `cpp' directly; `gcc'
|
||
will not pass it from its command line.
|
||
|
||
`-$'
|
||
Forbid the use of `$' in identifiers. This is required for ANSI
|
||
conformance. `gcc' automatically supplies this option to the
|
||
preprocessor if you specify `-ansi', but `gcc' doesn't recognize
|
||
the `-$' option itself--to use it without the other effects of
|
||
`-ansi', you must call the preprocessor directly.
|
||
|
||
|
||
File: cpp.info, Node: Concept Index, Next: Index, Prev: Invocation, Up: Top
|
||
|
||
Concept Index
|
||
*************
|
||
|
||
* Menu:
|
||
|
||
* cascaded macros: Cascaded Macros.
|
||
* commands: Commands.
|
||
* concatenation: Concatenation.
|
||
* conditionals: Conditionals.
|
||
* header file: Header Files.
|
||
* inheritance: Inheritance.
|
||
* line control: Combining Sources.
|
||
* macro body uses macro: Cascaded Macros.
|
||
* null command: Other Commands.
|
||
* options: Invocation.
|
||
* output format: Output.
|
||
* overriding a header file: Inheritance.
|
||
* predefined macros: Predefined.
|
||
* preprocessor commands: Commands.
|
||
* redefining macros: Redefining.
|
||
* repeated inclusion: Once-Only.
|
||
* self-reference: Self-Reference.
|
||
* semicolons (after macro calls): Swallow Semicolon.
|
||
* side effects (in macro arguments): Side Effects.
|
||
* stringification: Stringification.
|
||
* undefining macros: Undefining.
|
||
* unsafe macros: Side Effects.
|
||
|
||
|
||
File: cpp.info, Node: Index, Prev: Concept Index, Up: Top
|
||
|
||
Index of Commands, Macros and Options
|
||
*************************************
|
||
|
||
* Menu:
|
||
|
||
* #elif: #elif Command.
|
||
* #else: #else Command.
|
||
* #error: #error Command.
|
||
* #ident: Other Commands.
|
||
* #if: Conditional Syntax.
|
||
* #ifdef: Conditionals-Macros.
|
||
* #ifndef: Conditionals-Macros.
|
||
* #include: Include Syntax.
|
||
* #include_next: Inheritance.
|
||
* #line: Combining Sources.
|
||
* #pragma: Other Commands.
|
||
* #pragma once: Once-Only.
|
||
* #warning: #error Command.
|
||
* -C: Invocation.
|
||
* -D: Invocation.
|
||
* -H: Invocation.
|
||
* -I: Invocation.
|
||
* -M: Invocation.
|
||
* -MD: Invocation.
|
||
* -MM: Invocation.
|
||
* -MMD: Invocation.
|
||
* -P: Invocation.
|
||
* -U: Invocation.
|
||
* -Wall: Invocation.
|
||
* -Wcomment: Invocation.
|
||
* -Wtraditional: Invocation.
|
||
* -dD: Invocation.
|
||
* -dM: Invocation.
|
||
* -imacros: Invocation.
|
||
* -include: Invocation.
|
||
* -pedantic: Invocation.
|
||
* -pedantic-errors: Invocation.
|
||
* -trigraphs: Invocation.
|
||
* -undef: Invocation.
|
||
* BSD: Nonstandard Predefined.
|
||
* M68020: Nonstandard Predefined.
|
||
* _AM29000: Nonstandard Predefined.
|
||
* _AM29K: Nonstandard Predefined.
|
||
* __BASE_FILE__: Standard Predefined.
|
||
* __DATE__: Standard Predefined.
|
||
* __FILE__: Standard Predefined.
|
||
* __INCLUDE_LEVEL_: Standard Predefined.
|
||
* __LINE__: Standard Predefined.
|
||
* __STDC__: Standard Predefined.
|
||
* __TIME__: Standard Predefined.
|
||
* defined: Conditionals-Macros.
|
||
* m68k: Nonstandard Predefined.
|
||
* mc68000: Nonstandard Predefined.
|
||
* ns32000: Nonstandard Predefined.
|
||
* pyr: Nonstandard Predefined.
|
||
* sequent: Nonstandard Predefined.
|
||
* sun: Nonstandard Predefined.
|
||
* system header files: Header Uses.
|
||
* unix: Nonstandard Predefined.
|
||
* vax: Nonstandard Predefined.
|
||
|
||
|