(_hurd_sig_post): __sig_post renamed to __msg_sig_post.
[kopensolaris-gnu/glibc.git] / manual / =stdarg.texi
1 @node Variable Argument Facilities, Memory Allocation, Common Definitions, Top
2 @chapter Variable Argument Facilities
3 @cindex variadic argument functions
4 @cindex variadic functions
5 @cindex variable number of arguments
6 @cindex optional arguments
7
8 ANSI C defines a syntax as part of the kernel language for specifying
9 functions that take a variable number or type of arguments.  (Such
10 functions are also referred to as @dfn{variadic functions}.)  However,
11 the kernel language provides no mechanism for actually accessing
12 non-required arguments; instead, you use the variable arguments macros
13 defined in @file{stdarg.h}.
14 @pindex stdarg.h
15
16 @menu
17 * Why Variable Arguments are Used::     Using variable arguments can
18                                          save you time and effort.
19 * How Variable Arguments are Used::     An overview of the facilities for
20                                          receiving variable arguments.
21 * Variable Arguments Interface::        Detailed specification of the
22                                          library facilities.
23 * Example of Variable Arguments::       A complete example.
24 @end menu
25
26 @node Why Variable Arguments are Used, How Variable Arguments are Used,  , Variable Argument Facilities
27 @section Why Variable Arguments are Used
28
29 Most C functions take a fixed number of arguments.  When you define a
30 function, you also supply a specific data type for each argument.
31 Every call to the function should supply the same number and type of
32 arguments as specified in the function definition.
33
34 On the other hand, sometimes a function performs an operation that can
35 meaningfully accept an unlimited number of arguments.  
36
37 For example, consider a function that joins its arguments into a linked
38 list.  It makes sense to connect any number of arguments together into a
39 list of arbitrary length.  Without facilities for variable arguments,
40 you would have to define a separate function for each possible number of
41 arguments you might want to link together.  This is an example of a
42 situation where some kind of mapping or iteration is performed over an
43 arbitrary number of arguments of the same type.
44
45 Another kind of application where variable arguments can be useful is
46 for functions where values for some arguments can simply be omitted in
47 some calls, either because they are not used at all or because the
48 function can determine appropriate defaults for them if they're missing.
49
50 The library function @code{printf} (@pxref{Formatted Output}) is an
51 example of still another class of function where variable arguments are
52 useful.  This function prints its arguments (which can vary in type as
53 well as number) under the control of a format template string.
54
55 @node How Variable Arguments are Used, Variable Arguments Interface, Why Variable Arguments are Used, Variable Argument Facilities
56 @section How Variable Arguments are Used
57
58 This section describes how you can define and call functions that take
59 variable arguments, and how to access the values of the non-required
60 arguments.
61
62 @menu
63 * Syntax for Variable Arguments::       How to make a prototype for a
64                                          function with variable arguments.
65 * Receiving the Argument Values::       Steps you must follow to access the
66                                          optional argument values.
67 * How Many Arguments::                  How to decide whether there are more
68                                          arguments.
69 * Calling Variadic Functions::          Things you need to know about calling
70                                          variable arguments functions.
71 @end menu
72
73 @node Syntax for Variable Arguments, Receiving the Argument Values,  , How Variable Arguments are Used
74 @subsection Syntax for Variable Arguments
75
76 A function that accepts a variable number of arguments must have at
77 least one required argument with a specified type.  In the function
78 definition or prototype declaration, you indicate the fact that a
79 function can accept additional arguments of unspecified type by putting
80 @samp{@dots{}} at the end of the arguments.  For example,
81
82 @example
83 int 
84 func (const char *a, int b, @dots{})
85 @{
86   @dots{}
87 @}      
88 @end example
89
90 @noindent
91 outlines a definition of a function @code{func} which returns an
92 @code{int} and takes at least two arguments, the first two being a
93 @code{const char *} and an @code{int}.@refill
94
95 An obscure restriction placed by the ANSI C standard is that the last
96 required argument must not be declared @code{register} in the function
97 definition.  Furthermore, this argument must not be of a function or
98 array type, and may not be, for example, a @code{char} or @code{short
99 int} (whether signed or not) or a @code{float}.
100
101 @strong{Compatibility Note:} Many older C dialects provide a similar,
102 but incompatible, mechanism for defining functions with variable numbers
103 of arguments.  In particular, the @samp{@dots{}} syntax is a new feature
104 of ANSI C.
105
106
107 @node Receiving the Argument Values, How Many Arguments, Syntax for Variable Arguments, How Variable Arguments are Used
108 @subsection Receiving the Argument Values
109
110 Inside the definition of a variadic function, to access the optional
111 arguments with the following three step process:
112
113 @enumerate
114 @item
115 You initialize an argument pointer variable of type @code{va_list} using
116 @code{va_start}.
117
118 @item
119 You access the optional arguments by successive calls to @code{va_arg}.
120
121 @item
122 You call @code{va_end} to indicate that you are finished accessing the
123 arguments.
124 @end enumerate
125
126 Steps 1 and 3 must be performed in the function that is defined to
127 accept variable arguments.  However, you can pass the @code{va_list}
128 variable as an argument to another function and perform all or part of
129 step 2 there.  After doing this, the value of the @code{va_list}
130 variable in the calling function becomes undefined for further calls to
131 @code{va_arg}; you should just pass it to @code{va_end}.
132
133 You can perform the entire sequence of the three steps multiple times
134 within a single function invocation.  And, if the function doesn't want
135 to look at its optional arguments at all, it doesn't have to do any of
136 these steps.  It is also perfectly all right for a function to access
137 fewer arguments than were supplied in the call, but you will get garbage
138 values if you try to access too many arguments.
139
140
141 @node How Many Arguments, Calling Variadic Functions, Receiving the Argument Values, How Variable Arguments are Used
142 @subsection How Many Arguments Were Supplied
143
144 There is no general way for a function to determine the number and type
145 of the actual values that were passed as optional arguments.  Typically,
146 the value of one of the required arguments is used to tell the function
147 this information.  It is up to you to define an appropriate calling
148 convention for each function, and write all calls accordingly.
149
150 One calling convention is to make one of the required arguments be an
151 explicit argument count.  This convention is usable if all of the
152 optional arguments are of the same type.
153
154 A required argument can be used as a pattern to specify both the number
155 and types of the optional arguments.  The format template string
156 argument to @code{printf} is one example of this.
157
158 A similar technique that is sometimes used is to have one of the
159 required arguments be a bit mask, with a bit for each possible optional
160 argument that might be supplied.  The bits are tested in a predefined
161 sequence; if the bit is set, the value of the next argument is
162 retrieved, and otherwise a default value is used.
163
164 Another technique that is sometimes used is to pass an ``end marker''
165 value as the last optional argument.  For example, for a function that
166 manipulates an arbitrary number of pointer arguments, a null pointer
167 might indicate the end of the argument list, provided that a null
168 pointer isn't otherwise meaningful to the function.
169
170
171 @node Calling Variadic Functions,  , How Many Arguments, How Variable Arguments are Used
172 @subsection Calling Variadic Functions
173
174 Functions that are @emph{defined} to be variadic must also be
175 @emph{declared} to be variadic using a function prototype in the scope
176 of all calls to it.  This is because C compilers might use a different
177 internal function call protocol for variadic functions than for
178 functions that take a fixed number and type of arguments.  If the
179 compiler can't determine in advance that the function being called is
180 variadic, it may end up trying to call it incorrectly and your program
181 won't work.
182 @cindex function prototypes
183 @cindex prototypes for variadic functions
184 @cindex variadic functions need prototypes
185
186 Since the prototype doesn't specify types for optional arguments, in a
187 call to a variadic function the @dfn{default argument promotions} are
188 performed on the optional argument values.  This means the objects of
189 type @code{char} or @code{short int} (whether signed or not) are
190 promoted to either @code{int} or @code{unsigned int}, as appropriate;
191 and that objects of type @code{float} are promoted to type
192 @code{double}.  So, if the caller passes a @code{char} as an optional
193 argument, it is promoted to a @code{int}, and the function should get it
194 with @code{va_arg (@var{ap}, int)}.
195
196 Promotions of the required arguments are determined by the function
197 prototype in the usual way (as if by assignment to the types of the
198 corresponding formal parameters).
199 @cindex default argument promotions
200 @cindex argument promotion
201
202 @node Variable Arguments Interface, Example of Variable Arguments, How Variable Arguments are Used, Variable Argument Facilities
203 @section Variable Arguments Interface
204
205 Here are descriptions of the macros used to retrieve variable arguments.
206 These macros are defined in the header file @file{stdarg.h}.
207 @pindex stdarg.h
208
209 @comment stdarg.h
210 @comment ANSI
211 @deftp {Data Type} va_list
212 The type @code{va_list} is used for argument pointer variables.
213 @end deftp
214
215 @comment stdarg.h
216 @comment ANSI
217 @deftypefn {Macro} void va_start (va_list @var{ap}, @var{last_required})
218 This macro initialized the argument pointer variable @var{ap} to point
219 to the first of the optional arguments of the current function;
220 @var{last_required} must be the last required argument to the function.
221 @end deftypefn
222
223 @comment stdarg.h
224 @comment ANSI
225 @deftypefn {Macro} @var{type} va_arg (va_list @var{ap}, @var{type})
226 The @code{va_arg} macro returns the value of the next optional argument,
227 and changes the internal state of @var{ap} to move past this argument.
228 Thus, successive uses of @code{va_arg} return successive optional 
229 arguments.
230 The type of the value returned by @code{va_arg} is the @var{type}
231 specified in the call.  
232
233 The @var{type} must match the type of the actual argument, and must not
234 be @code{char} or @code{short int} or @code{float}.  (Remember that the
235 default argument promotions apply to optional arguments.)
236 @end deftypefn
237
238 @comment stdarg.h
239 @comment ANSI
240 @deftypefn {Macro} void va_end (va_list @var{ap})
241 This ends the use of @var{ap}.  After a @code{va_end} call, further
242 @code{va_arg} calls with the same @var{ap} may not work.  You should invoke
243 @code{va_end} before returning from the function in which @code{va_start}
244 was invoked with the same @var{ap} argument.
245
246 In the GNU C library, @code{va_end} does nothing, and you need not ever
247 use it except for reasons of portability.
248 @refill
249 @end deftypefn
250
251
252 @node Example of Variable Arguments,  , Variable Arguments Interface, Variable Argument Facilities
253 @section Example of Variable Arguments
254
255 Here is a complete sample function that accepts variable numbers of
256 arguments.  The first argument to the function is the count of remaining
257 arguments, which are added up and the result returned.  (This is
258 obviously a rather pointless function, but it serves to illustrate the
259 way the variable arguments facility is commonly used.)
260
261 @comment Yes, this example has been tested.
262
263 @example
264 #include <stdarg.h>
265
266 int 
267 add_em_up (int count, @dots{})
268 @{
269   va_list ap;
270   int i, sum;
271
272   va_start (ap, count);           /* @r{Initialize the argument list.} */
273
274   sum = 0;
275   for (i = 0; i < count; i++)
276     sum = sum + va_arg (ap, int); /* @r{Get the next argument value.} */
277
278   va_end (ap);                    /* @r{Clean up.} */
279   return sum;
280 @}
281
282 void main (void)
283 @{
284   /* @r{This call prints 16.} */
285   printf ("%d\n", add_em_up (3, 5, 5, 6));
286
287   /* @r{This call prints 55.} */
288   printf ("%d\n", add_em_up (10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10));
289 @}
290 @end example