cpp.texinfo

这是完整的gcc源代码

@example
#define x (4 + y)
#define y (2 * x)
@end example

@noindent
@samp{x} would expand into @samp{(4 + (2 * x))}.  Clear?

But suppose @samp{y} is used elsewhere, not from the definition of @samp{x}.
Then the use of @samp{x} in the expansion of @samp{y} is not a self-reference
because @samp{x} is not ``in progress''.  So it does expand.  However,
the expansion of @samp{x} contains a reference to @samp{y}, and that
is an indirect self-reference now because @samp{y} is ``in progress''.
The result is that @samp{y} expands to @samp{(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 need to understand it.

@node Argument Prescan, Cascaded Macros, Self-Reference, Macro Pitfalls
@subsubsection 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 @emph{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
(@pxref{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,

@example
#define str(s) #s
#define foo 4
str (foo)
@end example

@noindent
expands to @samp{"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.

@example
#define str(s) #s lose(s)
#define foo 4
str (foo)
@end example

expands to @samp{"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:

@itemize @bullet
@item
Nested calls to a macro.

@item
Macros that call other macros that stringify or concatenate.

@item
Macros whose expansions contain unshielded commas.
@end itemize

We say that @dfn{nested} calls to a macro occur when a macro's actual
argument contains a call to that very macro.  For example, if @samp{f}
is a macro that expects one argument, @samp{f (f (1))} is a nested
pair of calls to @samp{f}.  The desired expansion is made by
expanding @samp{f (1)} and substituting that into the definition of
@samp{f}.  The prescan causes the expected result to happen.
Without the prescan, @samp{f (1)} itself would be substituted as
an actual argument, and the inner use of @samp{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:

@example
#define foo  a,b
#define bar(x) lose(x)
#define lose(x) (1 + (x))

bar(foo)
@end example

@noindent
We would like @samp{bar(foo)} to turn into @samp{(1 + (foo))}, which
would then turn into @samp{(1 + (a,b))}.  But instead, @samp{bar(foo)}
expands into @samp{lose(a,b)}, and you get an error because @code{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:

@example
#define foo (a,b)
#define bar(x) lose((x))
@end example

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:

@example
#define foo @{ int a, b; @dots{} @}
@end example

@noindent
In GNU C you can shield the commas using the @samp{(@{@dots{}@})}
construct which turns a compound statement into an expression:

@example
#define foo (@{ int a, b; @dots{} @})
@end example

Or you can rewrite the macro definition to avoid such commas:

@example
#define foo @{ int a; int b; @dots{} @}
@end example

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 @samp{xstr} to the
example shown above:

@example
#define xstr(s) str(s)
#define str(s) #s
#define foo 4
xstr (foo)
@end example

This expands into @samp{"4"}, not @samp{"foo"}.  The reason for the
difference is that the argument of @samp{xstr} is expanded at prescan
(because @samp{xstr} does not specify stringification or concatenation of
the argument).  The result of prescan then forms the actual argument for
@samp{str}.  @samp{str} uses its argument without prescan because it
performs stringification; but it cannot prevent or undo the prescanning
already done by @samp{xstr}.

@node Cascaded Macros,, Argument Prescan, Macro Pitfalls
@subsubsection Cascaded Use of Macros

@cindex cascaded macros
@cindex macro body uses macro
A @dfn{cascade} of macros is when one macro's body contains a reference
to another macro.  This is very common practice.  For example,

@example
#define BUFSIZE 1020
#define TABLESIZE BUFSIZE
@end example

This is not at all the same as defining @samp{TABLESIZE} to be @samp{1020}.
The @samp{#define} for @samp{TABLESIZE} uses exactly the body you
specify---in this case, @samp{BUFSIZE}---and does not check to see whether
it too is the name of a macro.

It's only when you @emph{use} @samp{TABLESIZE} that the result of its expansion
is checked for more macro names.

This makes a difference if you change the definition of @samp{BUFSIZE}
at some point in the source file.  @samp{TABLESIZE}, defined as shown,
will always expand using the definition of @samp{BUFSIZE} that is
currently in effect:

@example
#define BUFSIZE 1020
#define TABLESIZE BUFSIZE
#undef BUFSIZE
#define BUFSIZE 37
@end example

@noindent
Now @samp{TABLESIZE} expands (in two stages) to @samp{37}.

@node Conditionals, Combining Sources, Macros, Top
@section Conditionals

@cindex conditionals
In a macro processor, a @dfn{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 @samp{if}
statement in C, but it is important to understand the difference between
them.  The condition in an @samp{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.
@end menu

@node Conditional Uses, Conditional Syntax, Conditionals, Conditionals
@subsection Why Conditionals are Used

Generally there are three kinds of reason to use a conditional.

@itemize @bullet
@item
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.

@item
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.

@item
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.
@end itemize

Most simple programs that are intended to run on only one machine will
not need to use preprocessor conditionals.

@node Conditional Syntax, Deleted Code, Conditional Uses, Conditionals
@subsection Syntax of Conditionals

@findex #if
A conditional in the C preprocessor begins with a @dfn{conditional
command}: @samp{#if}, @samp{#ifdef} or @samp{#ifndef}.
@xref{Conditionals-Macros}, for info on @samp{#ifdef} and
@samp{#ifndef}; only @samp{#if} is explained here.

@menu
* If: #if Command.     Basic conditionals using @samp{#if} and @samp{#endif}.
* Else: #else Command. Including some text if the condition fails.
* Elif: #elif Command. Testing several alternative possibilities.
@end menu

@node #if Command, #else Command, Conditional Syntax, Conditional Syntax
@subsubsection The @samp{#if} Command

The @samp{#if} command in its simplest form consists of

@example
#if @var{expression}
@var{controlled text}
#endif /* @var{expression} */
@end example

The comment following the @samp{#endif} is not required, but it is a good
practice because it helps people match the @samp{#endif} to the
corresponding @samp{#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 @samp{#endif} and it will be ignored by the GNU C preprocessor,
but only comments are acceptable in ANSI Standard C.

@var{expression} is a C expression of integer type, subject to stringent
restrictions.  It may contain

@itemize @bullet
@item
Integer constants, which are all regarded as @code{long} or
@code{unsigned long}.

@item
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
@samp{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 @samp{char} as signed, then
character codes large enough to set the sign bit will be considered
negative; otherwise, no character code is considered negative.

@item
Arithmetic operators for addition, subtraction, multiplication,
division, bitwise operations, shifts, comparisons, and @samp{&&} and
@samp{||}.

@item
Identifiers that are not macros, which are all treated as zero(!).

@item
Macro calls.  All macro calls in the expression are expanded before
actual computation of the expression's value begins.
@end itemize

Note that @samp{sizeof} operators and @code{enum}-type values are not allowed.
@code{enum}-type values, like all other identifiers that are not taken
as macro calls and expanded, are treated as zero.

The 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 @samp{#if}'s and @samp{#endif}'s must balance.

@node #else Command, #elif Command, #if Command, Conditional Syntax
@subsubsection The @samp{#else} Command

@findex #else
The @samp{#else} command can be added to a conditional to provide alternative
text to be used if the condition is false.  This looks like

@example
#if @var{expression}
@var{text-if-true}
#else /* Not @var{expression} */
@var{text-if-false}
#endif /* Not @var{expression} */
@end example

If