Fixed some formatting and indexing problems.
[kopensolaris-gnu/glibc.git] / manual / =stdarg.texi
1 @node Variable Argument Facilities
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 argument functions}, or
11 simply @dfn{variadic functions}.)  However, the kernel language provides
12 no mechanism for actually accessing non-required arguments; instead,
13 you use the variable arguments macros defined in
14 @file{stdarg.h}.
15 @pindex stdarg.h
16
17 @menu
18 * Why Variable Arguments are Used::     
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
27 @section Why Variable Arguments are Used
28
29 Most C functions take a fixed number of arguments.  When you declare or
30 define a function, you also supply a specific data type for each 
31 argument.  Calls to the function with the wrong number or type of 
32 arguments cause compile-time error messages.
33
34 On the other hand, sometimes a function performs an operation that makes
35 sense no matter how many arguments it is called with.  
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
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 function
64                                          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
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 func (const char *a, int b, @dots{})
84 @end example
85
86 @noindent
87 begins a definition of a function @code{func} which returns an
88 @code{int} and takes at least two arguments, the first two being a
89 @code{const char *} and an @code{int}.@refill
90
91 An obscure restriction placed by the ANSI C standard is that the last
92 required argument must not be declared @code{register} in the function
93 definition.  Furthermore, this argument must not be of a function or
94 array type, or of a type that is not compatible with the type that
95 results after application of the default argument promotions --- for
96 example, a @code{char} or @code{short int} (whether signed or not) or
97 a @code{float}.
98
99 @strong{Compatibility Note:} Many older C dialects provide a similar,
100 but incompatible, mechanism for defining variadic arguments functions.
101 In particular, the @samp{@dots{}} syntax is a new feature of ANSI C.
102
103
104 @node Receiving the Argument Values
105 @subsection Receiving the Argument Values
106
107 Inside the definition of a variadic arguments function, you can access
108 the optional arguments using a set of macros.  The process consists of
109 three steps:
110
111 @enumerate
112 @item
113 You initialize a variable of type @code{va_list} using @code{va_start}.
114
115 @item
116 You access the optional arguments by successive calls to @code{va_arg}.
117
118 @item
119 You call @code{va_end} to indicate that you are finished accessing the
120 arguments.
121 @end enumerate
122
123 Steps 1 and 3 must be performed in the function that is defined to
124 accept variable arguments.  However, you can pass the @code{va_list}
125 variable as an argument to another function and perform all or part of
126 step 2 there.  After doing this, the value of the @code{va_list}
127 variable in the calling function becomes undefined for further calls to
128 @code{va_arg}; you should just pass it to @code{va_end}.
129
130 You can perform the entire sequence of the three steps multiple times
131 within a single function invocation.  And, if the function doesn't want
132 to look at its optional arguments at all, it doesn't have to do any of
133 these steps.  It is also perfectly all right for a function to access
134 fewer arguments than were supplied in the call, but you will get garbage
135 values if you try to access too many arguments.
136
137
138 @node How Many Arguments
139 @subsection How Many Arguments Were Supplied
140
141 There is no general way for a function to determine the number and type
142 of the actual values that were passed as optional arguments.  Typically,
143 the value of one of the required arguments is used to decide when to
144 stop fetching more optional arguments.  It is up to you to define an
145 appropriate calling convention for each function, and write all calls
146 accordingly.
147
148 One calling convention is to make one of the required arguments be an
149 explicit argument count.  This works if all of the optional arguments
150 are of the same type.
151
152 A required argument can be used as a pattern to specify both the number
153 and types of the optional arguments.  The format template string
154 argument to @code{printf} is one example of this.
155
156 A similar technique that is sometimes used is to have one of the
157 required arguments be a bit mask, with a bit for each possible optional
158 argument that might be supplied.  The bits are tested in a predefined
159 sequence; if the bit is set, the value of the next argument is
160 retrieved, and otherwise a default value is used.
161
162 Another technique that is sometimes used is to pass an ``end marker''
163 value as the last optional argument.  For example, for a function that
164 manipulates an arbitrary number of pointer arguments, a null pointer
165 might indicate the end of the argument list, provided that a null
166 pointer isn't otherwise meaningful to the function.
167
168
169 @node Calling Variadic Functions
170 @subsection Calling Variadic Functions
171
172 Functions that are @emph{defined} to be variadic also be @emph{declared}
173 to be variadic using a function prototype in the scope of all calls to
174 it.  This is because C compilers might use a different internal function
175 call protocol for variadic functions than for functions that take a
176 fixed number and type of arguments.  If the compiler can't determine in
177 advance that the function being called is variadic, it may end up trying
178 to call it incorrectly and your program won't work.
179 @cindex function prototypes
180 @cindex prototypes for variadic functions
181 @cindex variadic functions need prototypes
182
183 Since the prototype doesn't specify types for optional arguments, in a
184 call to a variadic function the @dfn{default argument promotions} are
185 performed on the optional argument values.  This means the objects of
186 type @code{char} or @code{short int} are promoted to either @code{int}
187 or @code{unsigned int}, as appropriate; and that objects of type
188 @code{float} are promoted to type @code{double}.  So, if the caller
189 passes a @code{char} as an optional argument, it is promoted to a
190 @code{int}, and the function should get it with @code{va_arg (@var{ap},
191 int)}.
192
193 Promotions of the required arguments are determined by the function
194 prototype in the usual way (as if by assignment to the types of the
195 corresponding formal parameters).
196 @cindex default argument promotions
197 @cindex argument promotion
198
199 @node Variable Arguments Interface
200 @section Variable Arguments Interface
201
202 Here are descriptions of the macros used to retrieve variable arguments.
203 These macros are defined in the header file @file{stdarg.h}.
204 @pindex stdarg.h
205
206 @comment stdarg.h
207 @comment ANSI
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 @comment stdarg.h
214 @comment ANSI
215 @deftypefn {Macro} void va_start (va_list @var{ap}, @var{last_required})
216 This macro initializes the variable @var{ap} to hold the list of
217 optional arguments supplied to the function; @var{last_required} must be
218 the last required argument parameter to the function.  Initially, @var{ap}
219 ``points to'' the first optional argument.
220 @end deftypefn
221
222 @comment stdarg.h
223 @comment ANSI
224 @deftypefn {Macro} @var{type} va_arg (va_list @var{ap}, @var{type})
225 The @code{va_arg} macro returns the value of the next optional argument,
226 and changes the internal state of @var{ap} to move past this argument.
227 The type of the value returned by @code{va_arg} is the @var{type}
228 specified in the call.  
229
230 The @var{type} must match the type of the actual argument, and must not
231 be @code{char} or @code{short int} or @code{float}.  (Remember that the
232 default argument promotions apply to optional arguments.)
233 @end deftypefn
234
235 @comment stdarg.h
236 @comment ANSI
237 @deftypefn {Macro} void va_end (va_list @var{ap})
238 This ends the use of @var{ap}.  After a @code{va_end} call, further
239 @code{va_arg} calls with the same @var{ap} will not work.  You should invoke
240 @code{va_end} before returning from the function in which @code{va_start}
241 was invoked with the same @var{ap} argument.
242
243 In the GNU C library, @code{va_end} does nothing, and you need not ever
244 use it except for reasons of portability.
245 @refill
246 @end deftypefn
247
248
249 @node Example of Variable Arguments
250 @section Example of Variable Arguments
251
252 Here is a full example of a function using these macros.  The first 
253 argument to the function is the count of remaining arguments, which
254 are added up and the result returned.  (This is obviously a rather
255 pointless function, but it serves to illustrate the way the variable
256 arguments facility is commonly used.)
257
258 @comment Yes, this example has been tested.
259
260 @example
261 #include <stdarg.h>
262
263 int 
264 add_em_up (int count, @dots{})
265 @{
266   va_list ap;
267   int i, sum;
268
269   va_start (ap, count);           /* @r{Initialize the argument list.} */
270
271   sum = 0;
272   for (i = 0; i < count; i++)
273     sum = sum + va_arg (ap, int); /* @r{Get the next argument value.} */
274
275   va_end (ap);                    /* @r{Clean up.} */
276   return sum;
277 @}
278
279 void main (void)
280 @{
281   /* @r{This call prints 16.} */
282   printf ("%d\n", add_em_up (3, 5, 5, 6));
283
284   /* @r{This call prints 55.} */
285   printf ("%d\n", add_em_up (10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10));
286 @}
287 @end example