213 lines
10 KiB
HTML
213 lines
10 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
|
|
<html>
|
||
|
|
<!-- Copyright (C) 1987-2016 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. -->
|
||
|
|
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
|
||
|
|
<head>
|
||
|
|
<title>The C Preprocessor: Variadic Macros</title>
|
||
|
|
|
||
|
|
<meta name="description" content="The C Preprocessor: Variadic Macros">
|
||
|
|
<meta name="keywords" content="The C Preprocessor: Variadic Macros">
|
||
|
|
<meta name="resource-type" content="document">
|
||
|
|
<meta name="distribution" content="global">
|
||
|
|
<meta name="Generator" content="makeinfo">
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<link href="index.html#Top" rel="start" title="Top">
|
||
|
|
<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives">
|
||
|
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
||
|
|
<link href="Macros.html#Macros" rel="up" title="Macros">
|
||
|
|
<link href="Predefined-Macros.html#Predefined-Macros" rel="next" title="Predefined Macros">
|
||
|
|
<link href="Concatenation.html#Concatenation" rel="prev" title="Concatenation">
|
||
|
|
<style type="text/css">
|
||
|
|
<!--
|
||
|
|
a.summary-letter {text-decoration: none}
|
||
|
|
blockquote.smallquotation {font-size: smaller}
|
||
|
|
div.display {margin-left: 3.2em}
|
||
|
|
div.example {margin-left: 3.2em}
|
||
|
|
div.indentedblock {margin-left: 3.2em}
|
||
|
|
div.lisp {margin-left: 3.2em}
|
||
|
|
div.smalldisplay {margin-left: 3.2em}
|
||
|
|
div.smallexample {margin-left: 3.2em}
|
||
|
|
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
|
||
|
|
div.smalllisp {margin-left: 3.2em}
|
||
|
|
kbd {font-style:oblique}
|
||
|
|
pre.display {font-family: inherit}
|
||
|
|
pre.format {font-family: inherit}
|
||
|
|
pre.menu-comment {font-family: serif}
|
||
|
|
pre.menu-preformatted {font-family: serif}
|
||
|
|
pre.smalldisplay {font-family: inherit; font-size: smaller}
|
||
|
|
pre.smallexample {font-size: smaller}
|
||
|
|
pre.smallformat {font-family: inherit; font-size: smaller}
|
||
|
|
pre.smalllisp {font-size: smaller}
|
||
|
|
span.nocodebreak {white-space:nowrap}
|
||
|
|
span.nolinebreak {white-space:nowrap}
|
||
|
|
span.roman {font-family:serif; font-weight:normal}
|
||
|
|
span.sansserif {font-family:sans-serif; font-weight:normal}
|
||
|
|
ul.no-bullet {list-style: none}
|
||
|
|
-->
|
||
|
|
</style>
|
||
|
|
|
||
|
|
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
|
||
|
|
<a name="Variadic-Macros"></a>
|
||
|
|
<div class="header">
|
||
|
|
<p>
|
||
|
|
Next: <a href="Predefined-Macros.html#Predefined-Macros" accesskey="n" rel="next">Predefined Macros</a>, Previous: <a href="Concatenation.html#Concatenation" accesskey="p" rel="prev">Concatenation</a>, Up: <a href="Macros.html#Macros" accesskey="u" rel="up">Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<a name="Variadic-Macros-1"></a>
|
||
|
|
<h3 class="section">3.6 Variadic Macros</h3>
|
||
|
|
<a name="index-variable-number-of-arguments"></a>
|
||
|
|
<a name="index-macros-with-variable-arguments"></a>
|
||
|
|
<a name="index-variadic-macros"></a>
|
||
|
|
|
||
|
|
<p>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:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">#define eprintf(…) fprintf (stderr, __VA_ARGS__)
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>This kind of macro is called <em>variadic</em>. 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 <em>variable
|
||
|
|
argument</em>. This sequence of tokens replaces the identifier
|
||
|
|
<code><span class="nolinebreak">__VA_ARGS__</span><!-- /@w --></code> in the macro body wherever it appears. Thus, we
|
||
|
|
have this expansion:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">eprintf ("%s:%d: ", input_file, lineno)
|
||
|
|
→ fprintf (stderr, "%s:%d: ", input_file, lineno)
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<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>#</samp>’ and ‘<samp>##</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>##</samp>’.)
|
||
|
|
</p>
|
||
|
|
<p>If your macro is complicated, you may want a more descriptive name for
|
||
|
|
the variable argument than <code><span class="nolinebreak">__VA_ARGS__</span><!-- /@w --></code>. CPP permits
|
||
|
|
this, as an extension. You may write an argument name immediately
|
||
|
|
before the ‘<samp>…</samp>’; that name is used for the variable argument.
|
||
|
|
The <code>eprintf</code> macro above could be written
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">#define eprintf(args…) fprintf (stderr, args)
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>using this extension. You cannot use <code><span class="nolinebreak">__VA_ARGS__</span><!-- /@w --></code> and this
|
||
|
|
extension in the same macro.
|
||
|
|
</p>
|
||
|
|
<p>You can have named arguments as well as variable arguments in a variadic
|
||
|
|
macro. We could define <code>eprintf</code> like this, instead:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">#define eprintf(format, …) fprintf (stderr, format, __VA_ARGS__)
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">eprintf("success!\n", );
|
||
|
|
→ fprintf(stderr, "success!\n", );
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>GNU CPP has a pair of extensions which deal with this problem. First,
|
||
|
|
you are allowed to leave the variable argument out entirely:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">eprintf ("success!\n")
|
||
|
|
→ fprintf(stderr, "success!\n", );
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>Second, the ‘<samp>##</samp>’ token paste operator has a special meaning when
|
||
|
|
placed between a comma and a variable argument. If you write
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">#define eprintf(format, …) fprintf (stderr, format, ##__VA_ARGS__)
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>and the variable argument is left out when the <code>eprintf</code> macro is
|
||
|
|
used, then the comma before the ‘<samp>##</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>##</samp>’ is anything other than a comma.
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">eprintf ("success!\n")
|
||
|
|
→ fprintf(stderr, "success!\n");
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>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>
|
||
|
|
<p>C99 mandates that the only place the identifier <code><span class="nolinebreak">__VA_ARGS__</span><!-- /@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>
|
||
|
|
<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>args…</samp>’, not ‘<samp>…</samp>’ and <code><span class="nolinebreak">__VA_ARGS__</span><!-- /@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><span class="nolinebreak">__VA_ARGS__</span><!-- /@w --></code>.
|
||
|
|
</p>
|
||
|
|
<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>##</samp>’ must
|
||
|
|
be a comma, and there must be white space between that comma and
|
||
|
|
whatever comes immediately before it:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">#define eprintf(format, args…) fprintf (stderr, format , ##args)
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>See <a href="Differences-from-previous-versions.html#Differences-from-previous-versions">Differences from previous versions</a>, for the gory details.
|
||
|
|
</p>
|
||
|
|
<hr>
|
||
|
|
<div class="header">
|
||
|
|
<p>
|
||
|
|
Next: <a href="Predefined-Macros.html#Predefined-Macros" accesskey="n" rel="next">Predefined Macros</a>, Previous: <a href="Concatenation.html#Concatenation" accesskey="p" rel="prev">Concatenation</a>, Up: <a href="Macros.html#Macros" accesskey="u" rel="up">Macros</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|