cpp.texi

一个能在WIN32环境下使用GCC的功能进行程序设计的SHE

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 example

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 are not replaced by their corresponding actual
arguments if they appear inside string literals.

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

@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 more 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:

@example
@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 example

@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 surrounding
quotes of string literals, 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.

@example
#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 example

@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 as if they had been written next to each other.
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:

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

@group
struct command commands[] =
@{
  @{ "quit", quit_command @},
  @{ "help", help_command @},
  @dots{}
@};
@end group
@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

@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:

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

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:

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

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__}}.  GNU 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

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

@noindent
using this extension.  You cannot use @code{__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:

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

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

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

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

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

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

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

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

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

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
purpose.

Variadic macros are a new feature in C99.  GNU CPP has supported them
for a long time, but only with a named variable argument
(@samp{args@dots{}}, not @samp{@dots{}} and @code{@w{__VA_ARGS__}}).  If you are
concerned with portability to previous versions of GCC, you should use
only named variable arguments.  On the other hand, if you are concerned
with portability to other conforming implementations of C99, you should
use only @code{@w{__VA_ARGS__}}.

Previous versions of GNU CPP implemented the comma-deletion extension
much more generally.  We have restricted it in this release to minimize
the differences from C99.  To get the same effect with both this and
previous versions of GCC, the token preceding the special @samp{##} must
be a comma, and there must be white space between that comma and
whatever comes immediately before it:

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

@noindent
@xref{Differences from previous versions}, for the gory details.

@node Predefined Macros
@section Predefined Macros

@cindex predefined macros
Several object-like macros are predefined; you use them without
supplying their definitions.  They fall into three classes: standard,
common, and system-specific.

In C++, there is a fourth category, the named operators.  They act like
predefined macros, but you cannot undefine them.

@menu
* Standard Predefined Macros::
* Common Predefined Macros::
* System-specific Predefined Macros::
* C++ Named Operators::
@end menu

@node Standard Predefined Macros
@subsection Standard Predefined Macros
@cindex standard predefined macros.

The standard predefined macros are specified by the C and/or C++
language standards, so they are available with all compilers that
implement those standards.  Older compilers may not provide all of
them.  Their names all start with double underscores.

@table @code
@item __FILE__
This macro expands to the name of the current input file, in the form of
a C string constant.  This is