cpp.texinfo

这是完整的gcc源代码

#undef FOO
x = FOO;
@end example

@noindent
expands into

@example
x = 4;

x = FOO;
@end example

@noindent
In this example, @samp{FOO} had better be a variable or function as well
as (temporarily) a macro, in order for the result of the expansion to be
valid C code.

The same form of @samp{#undef} command will cancel definitions with
arguments or definitions that don't expect arguments.  The @samp{#undef}
command has no effect when used on a name not currently defined as a macro.

@node Redefining, Macro Pitfalls, Undefining, Macros
@subsection Redefining Macros

@cindex redefining macros
@dfn{Redefining} a macro means defining (with @samp{#define}) a name that
is already defined as a macro.

A redefinition is trivial if the new definition is transparently identical
to the old one.  You probably wouldn't deliberately write a trivial
redefinition, but they can happen automatically when a header file is
included more than once (@pxref{Header Files}), so they are accepted
silently and without effect.

Nontrivial redefinition is considered likely to be an error, so
it provokes a warning message from the preprocessor.  However, sometimes it
is useful to change the definition of a macro in mid-compilation.  You can
inhibit the warning by undefining the macro with @samp{#undef} before the
second definition.

In order for a redefinition to be trivial, the new definition must
exactly match the one already in effect, with two possible exceptions:

@itemize @bullet
@item
Whitespace may be added or deleted at the beginning or the end.

@item
Whitespace may be changed in the middle (but not inside strings).
However, it may not be eliminated entirely, and it may not be added
where there was no whitespace at all.
@end itemize

Recall that a comment counts as whitespace.

@node Macro Pitfalls,, Redefining, Macros
@subsection Pitfalls and Subtleties of Macros

In this section we describe some special rules that apply to macros and
macro expansion, and point out certain cases in which the rules have
counterintuitive consequences that you must watch out for.

@menu
* Misnesting::        Macros can contain unmatched parentheses.
* Macro Parentheses:: Why apparently superfluous parentheses
                         may be necessary to avoid incorrect grouping.
* Swallow Semicolon:: Macros that look like functions
                         but expand into compound statements.
* Side Effects::      Unsafe macros that cause trouble when
                         arguments contain side effects.
* Self-Reference::    Macros whose definitions use the macros' own names.
* Argument Prescan::  Actual arguments are checked for macro calls
                         before they are substituted.
* Cascaded Macros::   Macros whose definitions use other macros.
@end menu

@node Misnesting, Macro Parentheses, Macro Pitfalls, Macro Pitfalls
@subsubsection Improperly Nested Constructs

Recall that when a macro is called with arguments, the arguments are
substituted into the macro body and the result is checked, together with
the rest of the input file, for more macro calls.

It is possible to piece together a macro call coming partially from the
macro body and partially from the actual arguments.  For example,

@example
#define double(x) (2*(x))
#define call_with_1(x) x(1)
@end example

@noindent
would expand @samp{call_with_1 (double)} into @samp{(2*(1))}.

Macro definitions do not have to have balanced parentheses.  By writing an
unbalanced open parenthesis in a macro body, it is possible to create a
macro call that begins inside the macro body but ends outside of it.  For
example,

@example
#define strange(file) fprintf (file, "%s %d",
@dots{}
strange(stderr) p, 35)
@end example

@noindent
This bizarre example expands to @samp{fprintf (stderr, "%s %d", p, 35)}!

@node Macro Parentheses, Swallow Semicolon, Misnesting, Macro Pitfalls
@subsubsection Unintended Grouping of Arithmetic

You may have noticed that in most of the macro definition examples shown
above, each occurrence of a macro argument name had parentheses around it.
In addition, another pair of parentheses usually surround the entire macro
definition.  Here is why it is best to write macros that way.

Suppose you define a macro as follows,

@example
#define ceil_div(x, y) (x + y - 1) / y
@end example

@noindent
whose purpose is to divide, rounding up.  (One use for this
operation is to compute how many @samp{int}'s are needed to hold
a certain number of @samp{char}'s.)  Then suppose it is used as follows:

@example
a = ceil_div (b & c, sizeof (int));
@end example

@noindent
This expands into

@example
a = (b & c + sizeof (int) - 1) / sizeof (int);
@end example

@noindent
which does not do what is intended.  The operator-precedence rules of
C make it equivalent to this:

@example
a = (b & (c + sizeof (int) - 1)) / sizeof (int);
@end example

@noindent
But what we want is this:

@example
a = ((b & c) + sizeof (int) - 1)) / sizeof (int);
@end example

@noindent
Defining the macro as

@example
#define ceil_div(x, y) ((x) + (y) - 1) / (y)
@end example

@noindent
provides the desired result.

However, unintended grouping can result in another way.  Consider
@samp{sizeof ceil_div(1, 2)}.  That has the appearance of a C expression
that would compute the size of the type of @samp{ceil_div (1, 2)}, but in
fact it means something very different.  Here is what it expands to:

@example
sizeof ((1) + (2) - 1) / (2)
@end example

@noindent
This would take the size of an integer and divide it by two.  The precedence
rules have put the division outside the @samp{sizeof} when it was intended
to be inside.

Parentheses around the entire macro definition can prevent such problems.
Here, then, is the recommended way to define @samp{ceil_div}:

@example
#define ceil_div(x, y) (((x) + (y) - 1) / (y))
@end example

@node Swallow Semicolon, Side Effects, Macro Parentheses, Macro Pitfalls
@subsubsection Swallowing the Semicolon

@cindex semicolons (after macro calls)
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 @samp{p} says where to find it) across whitespace
characters:

@example
#define SKIP_SPACES (p, limit)  \
@{ register char *lim = (limit); \
  while (p != lim) @{            \
    if (*p++ != ' ') @{          \
      p--; break; @}@}@}
@end example

@noindent
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 @samp{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 @samp{SKIP_SPACES (p, lim);}

But this can cause trouble before @samp{else} statements, because the
semicolon is actually a null statement.  Suppose you write

@example
if (*p != 0)
  SKIP_SPACES (p, lim);
else @dots{}
@end example

@noindent
The presence of two statements---the compound statement and a null
statement---in between the @samp{if} condition and the @samp{else}
makes invalid C code.

The definition of the macro @samp{SKIP_SPACES} can be altered to solve
this problem, using a @samp{do @dots{} while} statement.  Here is how:

@example
#define SKIP_SPACES (p, limit)     \
do @{ register char *lim = (limit); \
     while (p != lim) @{            \
       if (*p++ != ' ') @{          \
         p--; break; @}@}@}           \
while (0)
@end example

Now @samp{SKIP_SPACES (p, lim);} expands into

@example
do @{@dots{}@} while (0);
@end example

@noindent
which is one statement.

@node Side Effects, Self-Reference, Swallow Semicolon, Macro Pitfalls
@subsubsection Duplication of Side Effects

@cindex side effects (in macro arguments)
@cindex unsafe macros
Many C programs define a macro @samp{min}, for ``minimum'', like this:

@example
#define min(X, Y)  ((X) < (Y) ? (X) : (Y))
@end example

When you use this macro with an argument containing a side effect,
as shown here,

@example
next = min (x + y, foo (z));
@end example

@noindent
it expands as follows:

@example
next = ((x + y) < (foo (z)) ? (x + y) : (foo (z)));
@end example

@noindent
where @samp{x + y} has been substituted for @samp{X} and @samp{foo (z)}
for @samp{Y}.

The function @samp{foo} is used only once in the statement as it appears
in the program, but the expression @samp{foo (z)} has been substituted
twice into the macro expansion.  As a result, @samp{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 @samp{min} is an @dfn{unsafe} macro.

The best solution to this problem is to define @samp{min} in a way that
computes the value of @samp{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:

@example
#define min(X, Y)                     \
(@{ typeof (X) __x = (X), __y = (Y);   \
   (__x < __y) ? __x : __y; @})
@end example

If you do not wish to use GNU C extensions, the only solution is to be
careful when @emph{using} the macro @samp{min}.  For example, you can
calculate the value of @samp{foo (z)}, save it in a variable, and use that
variable in @samp{min}:

@example
#define min(X, Y)  ((X) < (Y) ? (X) : (Y))
@dots{}
@{
  int tem = foo (z);
  next = min (x + y, tem);
@}
@end example

@noindent
(where I assume that @samp{foo} returns type @samp{int}).

@node Self-Reference, Argument Prescan, Side Effects, Macro Pitfalls
@subsubsection Self-Referential Macros

@cindex self-reference
A @dfn{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:

@example
#define foo (4 + foo)
@end example

@noindent
where @samp{foo} is also a variable in your program.

Following the ordinary rules, each reference to @samp{foo} will expand into
@samp{(4 + foo)}; then this will be rescanned and will expand into @samp{(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 @samp{(4 + foo)}.  Therefore, this macro definition
has the possibly useful effect of causing the program to add 4 to
the value of @samp{foo} wherever @samp{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 @samp{foo} is a variable will
not expect that it is a macro as well.  The reader will come across the
identifier @samp{foo} in the program and think its value should be that
of the variable @samp{foo}, whereas in fact the value is four greater.

The special rule for self-reference applies also to @dfn{indirect}
self-reference.  This is the case where a macro @var{x} expands to use a
macro @samp{y}, and @samp{y}'s expansion refers to the macro @samp{x}.  The
resulting reference to @samp{x} comes indirectly from the expansion of
@samp{x}, so it is a self-reference and is not further expanded.  Thus,
after