You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
163 lines
8.2 KiB
HTML
163 lines
8.2 KiB
HTML
4 years ago
|
<html lang="en">
|
||
|
|
<head>
|
||
|
|
<title>Variadic Macros - The C Preprocessor</title>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html">
|
||
|
|
<meta name="description" content="The C Preprocessor">
|
||
|
|
<meta name="generator" content="makeinfo 4.13">
|
||
|
|
<link title="Top" rel="start" href="index.html#Top">
|
||
|
|
<link rel="up" href="Macros.html#Macros" title="Macros">
|
||
|
|
<link rel="prev" href="Concatenation.html#Concatenation" title="Concatenation">
|
||
|
|
<link rel="next" href="Predefined-Macros.html#Predefined-Macros" title="Predefined Macros">
|
||
|
|
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
|
||
|
|
<!--
|
||
|
|
Copyright (C) 1987-2015 Free Software Foundation, Inc.
|
||
|
|
|
||
|
|
Permission is granted to copy, distribute and/or modify this document
|
||
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
||
|
|
any later version published by the Free Software Foundation. A copy of
|
||
|
|
the license is included in the
|
||
|
|
section entitled ``GNU Free Documentation License''.
|
||
|
|
|
||
|
|
This manual contains no Invariant Sections. The Front-Cover Texts are
|
||
|
|
(a) (see below), and the Back-Cover Texts are (b) (see below).
|
||
|
|
|
||
|
|
(a) The FSF's Front-Cover Text is:
|
||
|
|
|
||
|
|
A GNU Manual
|
||
|
|
|
||
|
|
(b) The FSF's Back-Cover Text is:
|
||
|
|
|
||
|
|
You have freedom to copy and modify this GNU Manual, like GNU
|
||
|
|
software. Copies published by the Free Software Foundation raise
|
||
|
|
funds for GNU development.
|
||
|
|
-->
|
||
|
|
<meta http-equiv="Content-Style-Type" content="text/css">
|
||
|
|
<style type="text/css"><!--
|
||
|
|
pre.display { font-family:inherit }
|
||
|
|
pre.format { font-family:inherit }
|
||
|
|
pre.smalldisplay { font-family:inherit; font-size:smaller }
|
||
|
|
pre.smallformat { font-family:inherit; font-size:smaller }
|
||
|
|
pre.smallexample { font-size:smaller }
|
||
|
|
pre.smalllisp { font-size:smaller }
|
||
|
|
span.sc { font-variant:small-caps }
|
||
|
|
span.roman { font-family:serif; font-weight:normal; }
|
||
|
|
span.sansserif { font-family:sans-serif; font-weight:normal; }
|
||
|
|
--></style>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<div class="node">
|
||
|
|
<a name="Variadic-Macros"></a>
|
||
|
|
<p>
|
||
|
|
Next: <a rel="next" accesskey="n" href="Predefined-Macros.html#Predefined-Macros">Predefined Macros</a>,
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="Concatenation.html#Concatenation">Concatenation</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="Macros.html#Macros">Macros</a>
|
||
|
|
<hr>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">3.6 Variadic Macros</h3>
|
||
|
|
|
||
|
|
<p><a name="index-variable-number-of-arguments-56"></a><a name="index-macros-with-variable-arguments-57"></a><a name="index-variadic-macros-58"></a>
|
||
|
|
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:
|
||
|
|
|
||
|
|
<pre class="smallexample"> #define eprintf(...) fprintf (stderr, __VA_ARGS__)
|
||
|
|
</pre>
|
||
|
|
<p>This kind of macro is called <dfn>variadic</dfn>. 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</dfn>. This sequence of tokens replaces the identifier
|
||
|
|
<code>__VA_ARGS__<!-- /@w --></code> in the macro body wherever it appears. Thus, we
|
||
|
|
have this expansion:
|
||
|
|
|
||
|
|
<pre class="smallexample"> eprintf ("%s:%d: ", input_file, lineno)
|
||
|
|
==> fprintf (stderr, "%s:%d: ", input_file, lineno)
|
||
|
|
</pre>
|
||
|
|
<p>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><span class="samp">#</span></samp>’ and ‘<samp><span class="samp">##</span></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><span class="samp">##</span></samp>’.)
|
||
|
|
|
||
|
|
<p>If your macro is complicated, you may want a more descriptive name for
|
||
|
|
the variable argument than <code>__VA_ARGS__<!-- /@w --></code>. CPP permits
|
||
|
|
this, as an extension. You may write an argument name immediately
|
||
|
|
before the ‘<samp><span class="samp">...</span></samp>’; that name is used for the variable argument.
|
||
|
|
The <code>eprintf</code> macro above could be written
|
||
|
|
|
||
|
|
<pre class="smallexample"> #define eprintf(args...) fprintf (stderr, args)
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">using this extension. You cannot use <code>__VA_ARGS__<!-- /@w --></code> and this
|
||
|
|
extension in the same macro.
|
||
|
|
|
||
|
|
<p>You can have named arguments as well as variable arguments in a variadic
|
||
|
|
macro. We could define <code>eprintf</code> like this, instead:
|
||
|
|
|
||
|
|
<pre class="smallexample"> #define eprintf(format, ...) fprintf (stderr, format, __VA_ARGS__)
|
||
|
|
</pre>
|
||
|
|
<p class="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.
|
||
|
|
|
||
|
|
<pre class="smallexample"> eprintf("success!\n", );
|
||
|
|
==> fprintf(stderr, "success!\n", );
|
||
|
|
</pre>
|
||
|
|
<p>GNU CPP has a pair of extensions which deal with this problem. First,
|
||
|
|
you are allowed to leave the variable argument out entirely:
|
||
|
|
|
||
|
|
<pre class="smallexample"> eprintf ("success!\n")
|
||
|
|
==> fprintf(stderr, "success!\n", );
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">Second, the ‘<samp><span class="samp">##</span></samp>’ token paste operator has a special meaning when
|
||
|
|
placed between a comma and a variable argument. If you write
|
||
|
|
|
||
|
|
<pre class="smallexample"> #define eprintf(format, ...) fprintf (stderr, format, ##__VA_ARGS__)
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">and the variable argument is left out when the <code>eprintf</code> macro is
|
||
|
|
used, then the comma before the ‘<samp><span class="samp">##</span></samp>’ will be deleted. This does
|
||
|
|
<em>not</em> happen if you pass an empty argument, nor does it happen if
|
||
|
|
the token preceding ‘<samp><span class="samp">##</span></samp>’ is anything other than a comma.
|
||
|
|
|
||
|
|
<pre class="smallexample"> eprintf ("success!\n")
|
||
|
|
==> fprintf(stderr, "success!\n");
|
||
|
|
</pre>
|
||
|
|
<p class="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.
|
||
|
|
|
||
|
|
<p>C99 mandates that the only place the identifier <code>__VA_ARGS__<!-- /@w --></code>
|
||
|
|
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.
|
||
|
|
|
||
|
|
<p>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><span class="samp">args...</span></samp>’, not ‘<samp><span class="samp">...</span></samp>’ and <code>__VA_ARGS__<!-- /@w --></code>). 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>__VA_ARGS__<!-- /@w --></code>.
|
||
|
|
|
||
|
|
<p>Previous versions of 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><span class="samp">##</span></samp>’ must
|
||
|
|
be a comma, and there must be white space between that comma and
|
||
|
|
whatever comes immediately before it:
|
||
|
|
|
||
|
|
<pre class="smallexample"> #define eprintf(format, args...) fprintf (stderr, format , ##args)
|
||
|
|
</pre>
|
||
|
|
<p class="noindent">See <a href="Differences-from-previous-versions.html#Differences-from-previous-versions">Differences from previous versions</a>, for the gory details.
|
||
|
|
|
||
|
|
</body></html>
|
||
|
|
|