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