cpp.texi

理解和实践操作系统的一本好书

@end smallexample

@noindent
passes two arguments to @code{macro}: @code{array[x = y} and @code{x +
1]}.  If you want to supply @code{array[x = y, x + 1]} as an argument,
you can write it as @code{array[(x = y, x + 1)]}, which is equivalent C
code.

All arguments to a macro are completely macro-expanded before they are
substituted into the macro body.  After substitution, the complete text
is scanned again for macros to expand, including the arguments.  This rule
may seem strange, but it is carefully designed so you need not worry
about whether any function call is actually a macro invocation.  You can
run into trouble if you try to be too clever, though.  @xref{Argument
Prescan}, for detailed discussion.

For example, @code{min (min (a, b), c)} is first expanded to

@smallexample
  min (((a) < (b) ? (a) : (b)), (c))
@end smallexample

@noindent
and then to

@smallexample
@group
((((a) < (b) ? (a) : (b))) < (c)
 ? (((a) < (b) ? (a) : (b)))
 : (c))
@end group
@end smallexample

@noindent
(Line breaks shown here for clarity would not actually be generated.)

@cindex empty macro arguments
You can leave macro arguments empty; this is not an error to the
preprocessor (but many macros will then expand to invalid code).
You cannot leave out arguments entirely; if a macro takes two arguments,
there must be exactly one comma at the top level of its argument list.
Here are some silly examples using @code{min}:

@smallexample
min(, b)        @expansion{} ((   ) < (b) ? (   ) : (b))
min(a, )        @expansion{} ((a  ) < ( ) ? (a  ) : ( ))
min(,)          @expansion{} ((   ) < ( ) ? (   ) : ( ))
min((,),)       @expansion{} (((,)) < ( ) ? ((,)) : ( ))

min()      @error{} macro "min" requires 2 arguments, but only 1 given
min(,,)    @error{} macro "min" passed 3 arguments, but takes just 2
@end smallexample

Whitespace is not a preprocessing token, so if a macro @code{foo} takes
one argument, @code{@w{foo ()}} and @code{@w{foo ( )}} both supply it an
empty argument.  Previous GNU preprocessor implementations and
documentation were incorrect on this point, insisting that a
function-like macro that takes a single argument be passed a space if an
empty argument was required.

Macro parameters appearing inside string literals are not replaced by
their corresponding actual arguments.

@smallexample
#define foo(x) x, "x"
foo(bar)        @expansion{} bar, "x"
@end smallexample

@node Stringification
@section Stringification
@cindex stringification
@cindex @samp{#} operator

Sometimes you may want to convert a macro argument into a string
constant.  Parameters are not replaced inside string constants, but you
can use the @samp{#} preprocessing operator instead.  When a macro
parameter is used with a leading @samp{#}, the preprocessor replaces it
with the literal text of the actual argument, converted to a string
constant.  Unlike normal parameter replacement, the argument is not
macro-expanded first.  This is called @dfn{stringification}.

There is no way to combine an argument with surrounding text and
stringify it all together.  Instead, you can write a series of adjacent
string constants and stringified arguments.  The preprocessor will
replace the stringified arguments with string constants.  The C
compiler will then combine all the adjacent string constants into one
long string.

Here is an example of a macro definition that uses stringification:

@smallexample
@group
#define WARN_IF(EXP) \
do @{ if (EXP) \
        fprintf (stderr, "Warning: " #EXP "\n"); @} \
while (0)
WARN_IF (x == 0);
     @expansion{} do @{ if (x == 0)
           fprintf (stderr, "Warning: " "x == 0" "\n"); @} while (0);
@end group
@end smallexample

@noindent
The argument for @code{EXP} is substituted once, as-is, into the
@code{if} statement, and once, stringified, into the argument to
@code{fprintf}.  If @code{x} were a macro, it would be expanded in the
@code{if} statement, but not in the string.

The @code{do} and @code{while (0)} are a kludge to make it possible to
write @code{WARN_IF (@var{arg});}, which the resemblance of
@code{WARN_IF} to a function would make C programmers want to do; see
@ref{Swallowing the Semicolon}.

Stringification in C involves more than putting double-quote characters
around the fragment.  The preprocessor backslash-escapes the quotes
surrounding embedded string constants, and all backslashes within string and
character constants, in order to get a valid C string constant with the
proper contents.  Thus, stringifying @code{@w{p = "foo\n";}} results in
@t{@w{"p = \"foo\\n\";"}}.  However, backslashes that are not inside string
or character constants are not duplicated: @samp{\n} by itself
stringifies to @t{"\n"}.

All leading and trailing whitespace in text being stringified is
ignored.  Any sequence of whitespace in the middle of the text is
converted to a single space in the stringified result.  Comments are
replaced by whitespace long before stringification happens, so they
never appear in stringified text.

There is no way to convert a macro argument into a character constant.

If you want to stringify the result of expansion of a macro argument,
you have to use two levels of macros.

@smallexample
#define xstr(s) str(s)
#define str(s) #s
#define foo 4
str (foo)
     @expansion{} "foo"
xstr (foo)
     @expansion{} xstr (4)
     @expansion{} str (4)
     @expansion{} "4"
@end smallexample

@code{s} is stringified when it is used in @code{str}, so it is not
macro-expanded first.  But @code{s} is an ordinary argument to
@code{xstr}, so it is completely macro-expanded before @code{xstr}
itself is expanded (@pxref{Argument Prescan}).  Therefore, by the time
@code{str} gets to its argument, it has already been macro-expanded.

@node Concatenation
@section Concatenation
@cindex concatenation
@cindex token pasting
@cindex token concatenation
@cindex @samp{##} operator

It is often useful to merge two tokens into one while expanding macros.
This is called @dfn{token pasting} or @dfn{token concatenation}.  The
@samp{##} preprocessing operator performs token pasting.  When a macro
is expanded, the two tokens on either side of each @samp{##} operator
are combined into a single token, which then replaces the @samp{##} and
the two original tokens in the macro expansion.  Usually both will be
identifiers, or one will be an identifier and the other a preprocessing
number.  When pasted, they make a longer identifier.  This isn't the
only valid case.  It is also possible to concatenate two numbers (or a
number and a name, such as @code{1.5} and @code{e3}) into a number.
Also, multi-character operators such as @code{+=} can be formed by
token pasting.

However, two tokens that don't together form a valid token cannot be
pasted together.  For example, you cannot concatenate @code{x} with
@code{+} in either order.  If you try, the preprocessor issues a warning
and emits the two tokens.  Whether it puts white space between the
tokens is undefined.  It is common to find unnecessary uses of @samp{##}
in complex macros.  If you get this warning, it is likely that you can
simply remove the @samp{##}.

Both the tokens combined by @samp{##} could come from the macro body,
but you could just as well write them as one token in the first place.
Token pasting is most useful when one or both of the tokens comes from a
macro argument.  If either of the tokens next to an @samp{##} is a
parameter name, it is replaced by its actual argument before @samp{##}
executes.  As with stringification, the actual argument is not
macro-expanded first.  If the argument is empty, that @samp{##} has no
effect.

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{*}.  You can put as much
whitespace between @samp{##} and its operands as you like, including
comments, and you can put comments in arguments that will be
concatenated.  However, it is an error if @samp{##} appears at either
end of a macro body.

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:

@smallexample
@group
struct command
@{
  char *name;
  void (*function) (void);
@};
@end group

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

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:

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

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

@node Variadic Macros
@section Variadic Macros
@cindex variable number of arguments
@cindex macros with variable arguments
@cindex variadic macros

A macro can be declared to accept a variable number of arguments much as
a function can.  The syntax for defining the macro is similar to that of
a function.  Here is an example:

@smallexample
#define eprintf(@dots{}) fprintf (stderr, __VA_ARGS__)
@end smallexample

This kind of macro is called @dfn{variadic}.  When the macro is invoked,
all the tokens in its argument list after the last named argument (this
macro has none), including any commas, become the @dfn{variable
argument}.  This sequence of tokens replaces the identifier
@code{@w{__VA_ARGS__}} in the macro body wherever it appears.  Thus, we
have this expansion:

@smallexample
eprintf ("%s:%d: ", input_file, lineno)
     @expansion{}  fprintf (stderr, "%s:%d: ", input_file, lineno)
@end smallexample

The variable argument is completely macro-expanded before it is inserted
into the macro expansion, just like an ordinary argument.  You may use
the @samp{#} and @samp{##} operators to stringify the variable argument
or to paste its leading or trailing token with another token.  (But see
below for an important special case for @samp{##}.)

If your macro is complicated, you may want a more descriptive name for
the variable argument than @code{@w{__VA_ARGS__}}.  CPP permits
this, as an extension.  You may write an argument name immediately
before the @samp{@dots{}}; that name is used for the variable argument.
The @code{eprintf} macro above could be written

@smallexample
#define eprintf(args@dots{}) fprintf (stderr, args)
@end smallexample

@noindent
using this extension.  You cannot use @code{@w{__VA_ARGS__}} and this
extension in the same macro.

You can have named arguments as well as variable arguments in a variadic
macro.  We could define @code{eprintf} like this, instead:

@smallexample
#define eprintf(format, @dots{}) fprintf (stderr, format, __VA_ARGS__)
@end smallexample

@noindent
This formulation looks more descriptive, but unfortunately it is less
flexible: you must now supply at least one argument after the format
string.  In standard C, you cannot omit the comma separating the named
argument from the variable arguments.  Furthermore, if you leave the
variable argument empty, you will get a syntax error, because
there will be an extra comma after the format string.

@smallexample
eprintf("success!\n", );
     @expansion{} fprintf(stderr, "success!\n", );
@end smallexample

GNU CPP has a pair of extensions which deal with this problem.  First,
you are allowed to leave the variable argument out entirely:

@smallexample
eprintf ("success!\n")
     @expansion{} fprintf(stderr, "success!\n", );
@end smallexample

@noindent
Second, the @samp{##} token paste operator has a special meaning when
placed between a comma and a variable argument.  If you write

@smallexample
#define eprintf(format, @dots{}) fprintf (stderr, format, ##__VA_ARGS__)
@end smallexample

@noindent
and the variable argument is left out when the @code{eprintf} macro is
used, then the comma before the @samp{##} will be deleted.  This does
@emph{not} happen if you pass an empty argument, nor does it happen if
the token preceding @samp{##} is anything other than a comma.

@smallexample
eprintf ("success!\n")
     @expansion{} fprintf(stderr, "success!\n");
@end smallexample

@noindent
The above explanation is ambiguous about the case where the only macro
parameter is a variable arguments parameter, as it is meaningless to
try to distinguish whether no argument at all is an empty argument or
a missing argument.  In this case the C99 standard is clear that the
comma must remain, however the existing GCC extension used to swallow
the comma.  So CPP retains the comma when conforming to a specific C
standard, and drops it otherwise.

C99 mandates that the only place the identifier @code{@w{__VA_ARGS__}}
can appear is in the replacement list of a variadic macro.  It may not
be used as a macro name, macro argument name, or within a different type
of macro.  It may also be forbidden in open text; the standard is
ambiguous.  We recommend you avoid using it except for its defined
purp