1<html lang="en"> 2<head> 3<title>Macro Arguments - 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="Function_002dlike-Macros.html#Function_002dlike-Macros" title="Function-like Macros"> 10<link rel="next" href="Stringification.html#Stringification" title="Stringification"> 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="Macro-Arguments"></a> 54<p> 55Next: <a rel="next" accesskey="n" href="Stringification.html#Stringification">Stringification</a>, 56Previous: <a rel="previous" accesskey="p" href="Function_002dlike-Macros.html#Function_002dlike-Macros">Function-like Macros</a>, 57Up: <a rel="up" accesskey="u" href="Macros.html#Macros">Macros</a> 58<hr> 59</div> 60 61<h3 class="section">3.3 Macro Arguments</h3> 62 63<p><a name="index-arguments-46"></a><a name="index-macros-with-arguments-47"></a><a name="index-arguments-in-macro-definitions-48"></a> 64Function-like macros can take <dfn>arguments</dfn>, just like true functions. 65To define a macro that uses arguments, you insert <dfn>parameters</dfn> 66between the pair of parentheses in the macro definition that make the 67macro function-like. The parameters must be valid C identifiers, 68separated by commas and optionally whitespace. 69 70 <p>To invoke a macro that takes arguments, you write the name of the macro 71followed by a list of <dfn>actual arguments</dfn> in parentheses, separated 72by commas. The invocation of the macro need not be restricted to a 73single logical line—it can cross as many lines in the source file as 74you wish. The number of arguments you give must match the number of 75parameters in the macro definition. When the macro is expanded, each 76use of a parameter in its body is replaced by the tokens of the 77corresponding argument. (You need not use all of the parameters in the 78macro body.) 79 80 <p>As an example, here is a macro that computes the minimum of two numeric 81values, as it is defined in many C programs, and some uses. 82 83<pre class="smallexample"> #define min(X, Y) ((X) < (Y) ? (X) : (Y)) 84 x = min(a, b); ==> x = ((a) < (b) ? (a) : (b)); 85 y = min(1, 2); ==> y = ((1) < (2) ? (1) : (2)); 86 z = min(a + 28, *p); ==> z = ((a + 28) < (*p) ? (a + 28) : (*p)); 87</pre> 88 <p class="noindent">(In this small example you can already see several of the dangers of 89macro arguments. See <a href="Macro-Pitfalls.html#Macro-Pitfalls">Macro Pitfalls</a>, for detailed explanations.) 90 91 <p>Leading and trailing whitespace in each argument is dropped, and all 92whitespace between the tokens of an argument is reduced to a single 93space. Parentheses within each argument must balance; a comma within 94such parentheses does not end the argument. However, there is no 95requirement for square brackets or braces to balance, and they do not 96prevent a comma from separating arguments. Thus, 97 98<pre class="smallexample"> macro (array[x = y, x + 1]) 99</pre> 100 <p class="noindent">passes two arguments to <code>macro</code>: <code>array[x = y</code> and <code>x + 1011]</code>. If you want to supply <code>array[x = y, x + 1]</code> as an argument, 102you can write it as <code>array[(x = y, x + 1)]</code>, which is equivalent C 103code. 104 105 <p>All arguments to a macro are completely macro-expanded before they are 106substituted into the macro body. After substitution, the complete text 107is scanned again for macros to expand, including the arguments. This rule 108may seem strange, but it is carefully designed so you need not worry 109about whether any function call is actually a macro invocation. You can 110run into trouble if you try to be too clever, though. See <a href="Argument-Prescan.html#Argument-Prescan">Argument Prescan</a>, for detailed discussion. 111 112 <p>For example, <code>min (min (a, b), c)</code> is first expanded to 113 114<pre class="smallexample"> min (((a) < (b) ? (a) : (b)), (c)) 115</pre> 116 <p class="noindent">and then to 117 118<pre class="smallexample"> ((((a) < (b) ? (a) : (b))) < (c) 119 ? (((a) < (b) ? (a) : (b))) 120 : (c)) 121</pre> 122 <p class="noindent">(Line breaks shown here for clarity would not actually be generated.) 123 124 <p><a name="index-empty-macro-arguments-49"></a>You can leave macro arguments empty; this is not an error to the 125preprocessor (but many macros will then expand to invalid code). 126You cannot leave out arguments entirely; if a macro takes two arguments, 127there must be exactly one comma at the top level of its argument list. 128Here are some silly examples using <code>min</code>: 129 130<pre class="smallexample"> min(, b) ==> (( ) < (b) ? ( ) : (b)) 131 min(a, ) ==> ((a ) < ( ) ? (a ) : ( )) 132 min(,) ==> (( ) < ( ) ? ( ) : ( )) 133 min((,),) ==> (((,)) < ( ) ? ((,)) : ( )) 134 135 min() error--> macro "min" requires 2 arguments, but only 1 given 136 min(,,) error--> macro "min" passed 3 arguments, but takes just 2 137</pre> 138 <p>Whitespace is not a preprocessing token, so if a macro <code>foo</code> takes 139one argument, <code>foo ()<!-- /@w --></code> and <code>foo ( )<!-- /@w --></code> both supply it an 140empty argument. Previous GNU preprocessor implementations and 141documentation were incorrect on this point, insisting that a 142function-like macro that takes a single argument be passed a space if an 143empty argument was required. 144 145 <p>Macro parameters appearing inside string literals are not replaced by 146their corresponding actual arguments. 147 148<pre class="smallexample"> #define foo(x) x, "x" 149 foo(bar) ==> bar, "x" 150</pre> 151 </body></html> 152 153