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