visus
/
toolchain-gcc-arm-embedded

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1987-2020 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.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<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">
<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> &nbsp; [<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 (&quot;%s:%d: &quot;, input_file, lineno)
     &rarr;  fprintf (stderr, &quot;%s:%d: &quot;, 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 &lsquo;<samp>#</samp>&rsquo; and &lsquo;<samp>##</samp>&rsquo; 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 &lsquo;<samp>##</samp>&rsquo;.)
</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 &lsquo;<samp>...</samp>&rsquo;; 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(&quot;success!\n&quot;, );
     &rarr; fprintf(stderr, &quot;success!\n&quot;, );
</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 (&quot;success!\n&quot;)
     &rarr; fprintf(stderr, &quot;success!\n&quot;, );
</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 &lsquo;<samp>##</samp>&rsquo; 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 &lsquo;<samp>##</samp>&rsquo; will be deleted.  This does
<em>not</em> happen if you pass an empty argument, nor does it happen if
the token preceding &lsquo;<samp>##</samp>&rsquo; is anything other than a comma.
</p>
<div class="smallexample">
<pre class="smallexample">eprintf (&quot;success!\n&quot;)
     &rarr; fprintf(stderr, &quot;success!\n&quot;);
</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
(&lsquo;<samp>args...</samp>&rsquo;, not &lsquo;<samp>...</samp>&rsquo; 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> &nbsp; [<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>