cpp.texi

早期freebsd实现

The stringification feature is limited to transforming one macro argument
into one string constant: there is no way to combine the argument with
other text and then stringify it all together.  But the example above shows
how an equivalent result can be obtained in ANSI Standard C using the
feature that adjacent string constants are concatenated as one string
constant.  The preprocessor stringifies the actual value of @samp{EXP} 
into a separate string constant, resulting in text like

@smallexample
do @{ if (x == 0) \
        fprintf (stderr, "Warning: " "x == 0" "\n"); @} \
while (0)
@end smallexample

@noindent
but the C compiler then sees three consecutive string constants and
concatenates them into one, producing effectively

@smallexample
do @{ if (x == 0) \
        fprintf (stderr, "Warning: x == 0\n"); @} \
while (0)
@end smallexample

Stringification in C involves more than putting doublequote characters
around the fragment; it is necessary to put backslashes in front of all
doublequote characters, and all backslashes in string and character
constants, in order to get a valid C string constant with the proper
contents.  Thus, stringifying @samp{p = "foo\n";} results in @samp{"p =
\"foo\\n\";"}.  However, backslashes that are not inside of string or
character constants are not duplicated: @samp{\n} by itself stringifies to
@samp{"\n"}.

Whitespace (including comments) in the text being stringified is handled
according to precise rules.  All leading and trailing whitespace is ignored.
Any sequence of whitespace in the middle of the text is converted to
a single space in the stringified result.

@node Concatenation, Undefining, Stringification, Macros
@subsection Concatenation

@cindex concatenation
@dfn{Concatenation} means joining two strings into one.  In the context
of macro expansion, concatenation refers to joining two lexical units
into one longer one.  Specifically, an actual argument to the macro can be
concatenated with another actual argument or with fixed text to produce
a longer name.  The longer name might be the name of a function,
variable or type, or a C keyword; it might even be the name of another
macro, in which case it will be expanded.

When you define a macro, you request concatenation with the special
operator @samp{##} in the macro body.  When the macro is called,
after actual arguments are substituted, all @samp{##} operators are
deleted, and so is any whitespace next to them (including whitespace
that was part of an actual argument).  The result is to concatenate
the syntactic tokens on either side of the @samp{##}.

Consider a C program that interprets named commands.  There probably needs
to be a table of commands, perhaps an array of structures declared as
follows:

@example
struct command
@{
  char *name;
  void (*function) ();
@};

struct command commands[] =
@{
  @{ "quit", quit_command@},
  @{ "help", help_command@},
  @dots{}
@};
@end example

It would be cleaner not to have to give each command name twice, once in
the string constant and once in the function name.  A macro which takes the
name of a command as an argument can make this unnecessary.  The string
constant can be created with stringification, and the function name by
concatenating the argument with @samp{_command}.  Here is how it is done:

@example
#define COMMAND(NAME)  @{ #NAME, NAME ## _command @}

struct command commands[] =
@{
  COMMAND (quit),
  COMMAND (help),
  @dots{}
@};
@end example

The usual case of concatenation is concatenating two names (or a name and a
number) into a longer name.  But this isn't the only valid case.  It is
also possible to concatenate two numbers (or a number and a name, such as
@samp{1.5} and @samp{e3}) into a number.  Also, multi-character operators
such as @samp{+=} can be formed by concatenation.  In some cases it is even
possible to piece together a string constant.  However, two pieces of text
that don't together form a valid lexical unit cannot be concatenated.  For
example, concatenation with @samp{x} on one side and @samp{+} on the other
is not meaningful because those two characters can't fit together in any
lexical unit of C.  The ANSI standard says that such attempts at
concatenation are undefined, but in the GNU C preprocessor it is well
defined: it puts the @samp{x} and @samp{+} side by side with no particular
special results.

Keep in mind that the C preprocessor converts comments to whitespace before
macros are even considered.  Therefore, you cannot create a comment by
concatenating @samp{/} and @samp{*}: the @samp{/*} sequence that starts a
comment is not a lexical unit, but rather the beginning of a ``long'' space
character.  Also, you can freely use comments next to a @samp{##} in a
macro definition, or in actual arguments that will be concatenated, because
the comments will be converted to spaces at first sight, and concatenation
will later discard the spaces.

@node Undefining, Redefining, Concatenation, Macros
@subsection Undefining Macros

@cindex undefining macros
To @dfn{undefine} a macro means to cancel its definition.  This is done
with the @samp{#undef} command.  @samp{#undef} is followed by the macro
name to be undefined.

Like definition, undefinition occurs at a specific point in the source
file, and it applies starting from that point.  The name ceases to be a
macro name, and from that point on it is treated by the preprocessor as if
it had never been a macro name.

For example,

@example
#define FOO 4
x = FOO;
#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.
* Newlines in Args::  Sometimes line numbers get confused.
@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} objects are needed to hold a certain
number of @samp{char} objects.)  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