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.
223 lines
10 KiB
HTML
223 lines
10 KiB
HTML
4 years ago
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
|
|
<html>
|
||
|
|
<!-- Copyright (C) 1987-2018 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 6.4, http://www.gnu.org/software/texinfo/ -->
|
||
|
|
<head>
|
||
|
|
<title>Variadic Macros (The C Preprocessor)</title>
|
||
|
|
|
||
|
|
<meta name="description" content="Variadic Macros (The C Preprocessor)">
|
||
|
|
<meta name="keywords" content="Variadic Macros (The C Preprocessor)">
|
||
|
|
<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.indentedblock {margin-right: 0em}
|
||
|
|
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
|
||
|
|
blockquote.smallquotation {font-size: smaller}
|
||
|
|
div.display {margin-left: 3.2em}
|
||
|
|
div.example {margin-left: 3.2em}
|
||
|
|
div.lisp {margin-left: 3.2em}
|
||
|
|
div.smalldisplay {margin-left: 3.2em}
|
||
|
|
div.smallexample {margin-left: 3.2em}
|
||
|
|
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.nolinebreak {white-space: nowrap}
|
||
|
|
span.roman {font-family: initial; font-weight: normal}
|
||
|
|
span.sansserif {font-family: sans-serif; font-weight: normal}
|
||
|
|
ul.no-bullet {list-style: none}
|
||
|
|
-->
|
||
|
|
</style>
|
||
|
|
|
||
|
|
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body lang="en">
|
||
|
|
<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 stringize 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 historically it was less
|
||
|
|
flexible: you had to supply at least one argument after the format
|
||
|
|
string. In standard C, you could not omit the comma separating the
|
||
|
|
named argument from the variable arguments. (Note that this
|
||
|
|
restriction has been lifted in C++2a, and never existed in GNU C; see
|
||
|
|
below.)
|
||
|
|
</p>
|
||
|
|
<p>Furthermore, if you left the variable argument empty, you would have
|
||
|
|
gotten a syntax error, because there would have been an extra comma
|
||
|
|
after the format string.
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">eprintf("success!\n", );
|
||
|
|
→ fprintf(stderr, "success!\n", );
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>This has been fixed in C++2a, and GNU CPP also has a pair of
|
||
|
|
extensions which deal with this problem.
|
||
|
|
</p>
|
||
|
|
<p>First, in GNU CPP, and in C++ beginning in C++2a, 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, C++2a introduces the <code><span class="nolinebreak">__VA_OPT__</span><!-- /@w --></code> function macro.
|
||
|
|
This macro may only appear in the definition of a variadic macro. If
|
||
|
|
the variable argument has any tokens, then a <code><span class="nolinebreak">__VA_OPT__</span><!-- /@w --></code>
|
||
|
|
invocation expands to its argument; but if the variable argument does
|
||
|
|
not have any tokens, the <code><span class="nolinebreak">__VA_OPT__</span><!-- /@w --></code> expands to nothing:
|
||
|
|
</p>
|
||
|
|
<div class="smallexample">
|
||
|
|
<pre class="smallexample">#define eprintf(format, …) \
|
||
|
|
fprintf (stderr, format __VA_OPT__(,) __VA_ARGS__)
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p><code><span class="nolinebreak">__VA_OPT__</span><!-- /@w --></code> is also available in GNU C and GNU C++.
|
||
|
|
</p>
|
||
|
|
<p>Historically, GNU CPP has also had another extension to handle the
|
||
|
|
trailing comma: the ‘<samp>##</samp>’ token paste operator has a special
|
||
|
|
meaning when placed between a comma and a variable argument. Despite
|
||
|
|
the introduction of <code><span class="nolinebreak">__VA_OPT__</span><!-- /@w --></code>, this extension remains
|
||
|
|
supported in GNU CPP, for backward compatibility. 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.
|
||
|
|
CPP retains the comma when conforming to a specific C
|
||
|
|
standard. Otherwise the comma is dropped as an extension to the standard.
|
||
|
|
</p>
|
||
|
|
<p>The C standard
|
||
|
|
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>Likewise, C++ forbids <code><span class="nolinebreak">__VA_OPT__</span><!-- /@w --></code> anywhere outside the
|
||
|
|
replacement list of a variadic macro.
|
||
|
|
</p>
|
||
|
|
<p>Variadic macros became a standard part of the C language with C99.
|
||
|
|
GNU CPP previously supported them
|
||
|
|
with a named variable argument
|
||
|
|
(‘<samp>args…</samp>’, not ‘<samp>…</samp>’ and <code><span class="nolinebreak">__VA_ARGS__</span><!-- /@w --></code>), which
|
||
|
|
is still supported for backward compatibility.
|
||
|
|
</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>
|