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