1<html lang="en"> 2<head> 3<title>Variadic Macros - The C Preprocessor</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="The C Preprocessor"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Macros.html#Macros" title="Macros"> 9<link rel="prev" href="Concatenation.html#Concatenation" title="Concatenation"> 10<link rel="next" href="Predefined-Macros.html#Predefined-Macros" title="Predefined Macros"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 141997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 152008, 2009, 2010, 2011 16Free Software Foundation, Inc. 17 18Permission is granted to copy, distribute and/or modify this document 19under the terms of the GNU Free Documentation License, Version 1.3 or 20any later version published by the Free Software Foundation. A copy of 21the license is included in the 22section entitled ``GNU Free Documentation License''. 23 24This manual contains no Invariant Sections. The Front-Cover Texts are 25(a) (see below), and the Back-Cover Texts are (b) (see below). 26 27(a) The FSF's Front-Cover Text is: 28 29 A GNU Manual 30 31(b) The FSF's Back-Cover Text is: 32 33 You have freedom to copy and modify this GNU Manual, like GNU 34 software. Copies published by the Free Software Foundation raise 35 funds for GNU development. 36--> 37<meta http-equiv="Content-Style-Type" content="text/css"> 38<style type="text/css"><!-- 39 pre.display { font-family:inherit } 40 pre.format { font-family:inherit } 41 pre.smalldisplay { font-family:inherit; font-size:smaller } 42 pre.smallformat { font-family:inherit; font-size:smaller } 43 pre.smallexample { font-size:smaller } 44 pre.smalllisp { font-size:smaller } 45 span.sc { font-variant:small-caps } 46 span.roman { font-family:serif; font-weight:normal; } 47 span.sansserif { font-family:sans-serif; font-weight:normal; } 48--></style> 49<link rel="stylesheet" type="text/css" href="../cs.css"> 50</head> 51<body> 52<div class="node"> 53<a name="Variadic-Macros"></a> 54<p> 55Next: <a rel="next" accesskey="n" href="Predefined-Macros.html#Predefined-Macros">Predefined Macros</a>, 56Previous: <a rel="previous" accesskey="p" href="Concatenation.html#Concatenation">Concatenation</a>, 57Up: <a rel="up" accesskey="u" href="Macros.html#Macros">Macros</a> 58<hr> 59</div> 60 61<h3 class="section">3.6 Variadic Macros</h3> 62 63<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> 64A macro can be declared to accept a variable number of arguments much as 65a function can. The syntax for defining the macro is similar to that of 66a function. Here is an example: 67 68<pre class="smallexample"> #define eprintf(...) fprintf (stderr, __VA_ARGS__) 69</pre> 70 <p>This kind of macro is called <dfn>variadic</dfn>. When the macro is invoked, 71all the tokens in its argument list after the last named argument (this 72macro has none), including any commas, become the <dfn>variable 73argument</dfn>. This sequence of tokens replaces the identifier 74<code>__VA_ARGS__<!-- /@w --></code> in the macro body wherever it appears. Thus, we 75have this expansion: 76 77<pre class="smallexample"> eprintf ("%s:%d: ", input_file, lineno) 78 ==> fprintf (stderr, "%s:%d: ", input_file, lineno) 79</pre> 80 <p>The variable argument is completely macro-expanded before it is inserted 81into the macro expansion, just like an ordinary argument. You may use 82the ‘<samp><span class="samp">#</span></samp>’ and ‘<samp><span class="samp">##</span></samp>’ operators to stringify the variable argument 83or to paste its leading or trailing token with another token. (But see 84below for an important special case for ‘<samp><span class="samp">##</span></samp>’.) 85 86 <p>If your macro is complicated, you may want a more descriptive name for 87the variable argument than <code>__VA_ARGS__<!-- /@w --></code>. CPP permits 88this, as an extension. You may write an argument name immediately 89before the ‘<samp><span class="samp">...</span></samp>’; that name is used for the variable argument. 90The <code>eprintf</code> macro above could be written 91 92<pre class="smallexample"> #define eprintf(args...) fprintf (stderr, args) 93</pre> 94 <p class="noindent">using this extension. You cannot use <code>__VA_ARGS__<!-- /@w --></code> and this 95extension in the same macro. 96 97 <p>You can have named arguments as well as variable arguments in a variadic 98macro. We could define <code>eprintf</code> like this, instead: 99 100<pre class="smallexample"> #define eprintf(format, ...) fprintf (stderr, format, __VA_ARGS__) 101</pre> 102 <p class="noindent">This formulation looks more descriptive, but unfortunately it is less 103flexible: you must now supply at least one argument after the format 104string. In standard C, you cannot omit the comma separating the named 105argument from the variable arguments. Furthermore, if you leave the 106variable argument empty, you will get a syntax error, because 107there will be an extra comma after the format string. 108 109<pre class="smallexample"> eprintf("success!\n", ); 110 ==> fprintf(stderr, "success!\n", ); 111</pre> 112 <p>GNU CPP has a pair of extensions which deal with this problem. First, 113you are allowed to leave the variable argument out entirely: 114 115<pre class="smallexample"> eprintf ("success!\n") 116 ==> fprintf(stderr, "success!\n", ); 117</pre> 118 <p class="noindent">Second, the ‘<samp><span class="samp">##</span></samp>’ token paste operator has a special meaning when 119placed between a comma and a variable argument. If you write 120 121<pre class="smallexample"> #define eprintf(format, ...) fprintf (stderr, format, ##__VA_ARGS__) 122</pre> 123 <p class="noindent">and the variable argument is left out when the <code>eprintf</code> macro is 124used, then the comma before the ‘<samp><span class="samp">##</span></samp>’ will be deleted. This does 125<em>not</em> happen if you pass an empty argument, nor does it happen if 126the token preceding ‘<samp><span class="samp">##</span></samp>’ is anything other than a comma. 127 128<pre class="smallexample"> eprintf ("success!\n") 129 ==> fprintf(stderr, "success!\n"); 130</pre> 131 <p class="noindent">The above explanation is ambiguous about the case where the only macro 132parameter is a variable arguments parameter, as it is meaningless to 133try to distinguish whether no argument at all is an empty argument or 134a missing argument. In this case the C99 standard is clear that the 135comma must remain, however the existing GCC extension used to swallow 136the comma. So CPP retains the comma when conforming to a specific C 137standard, and drops it otherwise. 138 139 <p>C99 mandates that the only place the identifier <code>__VA_ARGS__<!-- /@w --></code> 140can appear is in the replacement list of a variadic macro. It may not 141be used as a macro name, macro argument name, or within a different type 142of macro. It may also be forbidden in open text; the standard is 143ambiguous. We recommend you avoid using it except for its defined 144purpose. 145 146 <p>Variadic macros are a new feature in C99. GNU CPP has supported them 147for a long time, but only with a named variable argument 148(‘<samp><span class="samp">args...</span></samp>’, not ‘<samp><span class="samp">...</span></samp>’ and <code>__VA_ARGS__<!-- /@w --></code>). If you are 149concerned with portability to previous versions of GCC, you should use 150only named variable arguments. On the other hand, if you are concerned 151with portability to other conforming implementations of C99, you should 152use only <code>__VA_ARGS__<!-- /@w --></code>. 153 154 <p>Previous versions of CPP implemented the comma-deletion extension 155much more generally. We have restricted it in this release to minimize 156the differences from C99. To get the same effect with both this and 157previous versions of GCC, the token preceding the special ‘<samp><span class="samp">##</span></samp>’ must 158be a comma, and there must be white space between that comma and 159whatever comes immediately before it: 160 161<pre class="smallexample"> #define eprintf(format, args...) fprintf (stderr, format , ##args) 162</pre> 163 <p class="noindent">See <a href="Differences-from-previous-versions.html#Differences-from-previous-versions">Differences from previous versions</a>, for the gory details. 164 165 </body></html> 166 167