GNU Info

(cpp-300.info)Variadic Macros

---

Next: Predefined Macros Prev: Concatenation Up: Macros

---

Enter node , (file) or (file)node

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:

     #define eprintf(...) fprintf (stderr, __VA_ARGS__)

   This kind of macro is called "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 "variable argument".
This sequence of tokens replaces the identifier `__VA_ARGS__' in the
macro body wherever it appears.  Thus, we have this expansion:

     eprintf ("%s:%d: ", input_file, lineno)
          ==>  fprintf (stderr, "%s:%d: ", input_file, lineno)

   The variable argument is completely macro-expanded before it is
inserted into the macro expansion, just like an ordinary argument.  You
may use the `#' and `##' 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 `##'.)

   If your macro is complicated, you may want a more descriptive name
for the variable argument than `__VA_ARGS__'.  GNU CPP permits this, as
an extension.  You may write an argument name immediately before the
`...'; that name is used for the variable argument.  The `eprintf'
macro above could be written

     #define eprintf(args...) fprintf (stderr, args)

using this extension.  You cannot use `__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 `eprintf' like this, instead:

     #define eprintf(format, ...) fprintf (stderr, format, __VA_ARGS__)

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.

     eprintf("success!\n", );
          ==> fprintf(stderr, "success!\n", );

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

     eprintf ("success!\n")
          ==> fprintf(stderr, "success!\n", );

Second, the `##' token paste operator has a special meaning when placed
between a comma and a variable argument.  If you write

     #define eprintf(format, ...) fprintf (stderr, format, ##__VA_ARGS__)

and the variable argument is left out when the `eprintf' macro is used,
then the comma before the `##' will be deleted.  This does _not_ happen
if you pass an empty argument, nor does it happen if the token
preceding `##' is anything other than a comma.

     eprintf ("success!\n")
          ==> fprintf(stderr, "success!\n");

   C99 mandates that the only place the identifier `__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 (`args...',
not `...' and `__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 `__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 `##' must be
a comma, and there must be white space between that comma and whatever
comes immediately before it:

     #define eprintf(format, args...) fprintf (stderr, format , ##args)

Note: Differences from previous versions, for the gory details.