diff options
Diffstat (limited to 'manual/=stdarg.texi')
| -rw-r--r-- | manual/=stdarg.texi | 290 |
1 files changed, 290 insertions, 0 deletions
diff --git a/manual/=stdarg.texi b/manual/=stdarg.texi new file mode 100644 index 0000000000..384c992f13 --- /dev/null +++ b/manual/=stdarg.texi @@ -0,0 +1,290 @@ +@node Variable Argument Facilities, Memory Allocation, Common Definitions, Top +@chapter Variable Argument Facilities +@cindex variadic argument functions +@cindex variadic functions +@cindex variable number of arguments +@cindex optional arguments + +ANSI C defines a syntax as part of the kernel language for specifying +functions that take a variable number or type of arguments. (Such +functions are also referred to as @dfn{variadic functions}.) However, +the kernel language provides no mechanism for actually accessing +non-required arguments; instead, you use the variable arguments macros +defined in @file{stdarg.h}. +@pindex stdarg.h + +@menu +* Why Variable Arguments are Used:: Using variable arguments can + save you time and effort. +* How Variable Arguments are Used:: An overview of the facilities for + receiving variable arguments. +* Variable Arguments Interface:: Detailed specification of the + library facilities. +* Example of Variable Arguments:: A complete example. +@end menu + +@node Why Variable Arguments are Used, How Variable Arguments are Used, , Variable Argument Facilities +@section Why Variable Arguments are Used + +Most C functions take a fixed number of arguments. When you define a +function, you also supply a specific data type for each argument. +Every call to the function should supply the same number and type of +arguments as specified in the function definition. + +On the other hand, sometimes a function performs an operation that can +meaningfully accept an unlimited number of arguments. + +For example, consider a function that joins its arguments into a linked +list. It makes sense to connect any number of arguments together into a +list of arbitrary length. Without facilities for variable arguments, +you would have to define a separate function for each possible number of +arguments you might want to link together. This is an example of a +situation where some kind of mapping or iteration is performed over an +arbitrary number of arguments of the same type. + +Another kind of application where variable arguments can be useful is +for functions where values for some arguments can simply be omitted in +some calls, either because they are not used at all or because the +function can determine appropriate defaults for them if they're missing. + +The library function @code{printf} (@pxref{Formatted Output}) is an +example of still another class of function where variable arguments are +useful. This function prints its arguments (which can vary in type as +well as number) under the control of a format template string. + +@node How Variable Arguments are Used, Variable Arguments Interface, Why Variable Arguments are Used, Variable Argument Facilities +@section How Variable Arguments are Used + +This section describes how you can define and call functions that take +variable arguments, and how to access the values of the non-required +arguments. + +@menu +* Syntax for Variable Arguments:: How to make a prototype for a + function with variable arguments. +* Receiving the Argument Values:: Steps you must follow to access the + optional argument values. +* How Many Arguments:: How to decide whether there are more + arguments. +* Calling Variadic Functions:: Things you need to know about calling + variable arguments functions. +@end menu + +@node Syntax for Variable Arguments, Receiving the Argument Values, , How Variable Arguments are Used +@subsection Syntax for Variable Arguments + +A function that accepts a variable number of arguments must have at +least one required argument with a specified type. In the function +definition or prototype declaration, you indicate the fact that a +function can accept additional arguments of unspecified type by putting +@samp{@dots{}} at the end of the arguments. For example, + +@example +int +func (const char *a, int b, @dots{}) +@{ + @dots{} +@} +@end example + +@noindent +outlines a definition of a function @code{func} which returns an +@code{int} and takes at least two arguments, the first two being a +@code{const char *} and an @code{int}.@refill + +An obscure restriction placed by the ANSI C standard is that the last +required argument must not be declared @code{register} in the function +definition. Furthermore, this argument must not be of a function or +array type, and may not be, for example, a @code{char} or @code{short +int} (whether signed or not) or a @code{float}. + +@strong{Compatibility Note:} Many older C dialects provide a similar, +but incompatible, mechanism for defining functions with variable numbers +of arguments. In particular, the @samp{@dots{}} syntax is a new feature +of ANSI C. + + +@node Receiving the Argument Values, How Many Arguments, Syntax for Variable Arguments, How Variable Arguments are Used +@subsection Receiving the Argument Values + +Inside the definition of a variadic function, to access the optional +arguments with the following three step process: + +@enumerate +@item +You initialize an argument pointer variable of type @code{va_list} using +@code{va_start}. + +@item +You access the optional arguments by successive calls to @code{va_arg}. + +@item +You call @code{va_end} to indicate that you are finished accessing the +arguments. +@end enumerate + +Steps 1 and 3 must be performed in the function that is defined to +accept variable arguments. However, you can pass the @code{va_list} +variable as an argument to another function and perform all or part of +step 2 there. After doing this, the value of the @code{va_list} +variable in the calling function becomes undefined for further calls to +@code{va_arg}; you should just pass it to @code{va_end}. + +You can perform the entire sequence of the three steps multiple times +within a single function invocation. And, if the function doesn't want +to look at its optional arguments at all, it doesn't have to do any of +these steps. It is also perfectly all right for a function to access +fewer arguments than were supplied in the call, but you will get garbage +values if you try to access too many arguments. + + +@node How Many Arguments, Calling Variadic Functions, Receiving the Argument Values, How Variable Arguments are Used +@subsection How Many Arguments Were Supplied + +There is no general way for a function to determine the number and type +of the actual values that were passed as optional arguments. Typically, +the value of one of the required arguments is used to tell the function +this information. It is up to you to define an appropriate calling +convention for each function, and write all calls accordingly. + +One calling convention is to make one of the required arguments be an +explicit argument count. This convention is usable if all of the +optional arguments are of the same type. + +A required argument can be used as a pattern to specify both the number +and types of the optional arguments. The format template string +argument to @code{printf} is one example of this. + +A similar technique that is sometimes used is to have one of the +required arguments be a bit mask, with a bit for each possible optional +argument that might be supplied. The bits are tested in a predefined +sequence; if the bit is set, the value of the next argument is +retrieved, and otherwise a default value is used. + +Another technique that is sometimes used is to pass an ``end marker'' +value as the last optional argument. For example, for a function that +manipulates an arbitrary number of pointer arguments, a null pointer +might indicate the end of the argument list, provided that a null +pointer isn't otherwise meaningful to the function. + + +@node Calling Variadic Functions, , How Many Arguments, How Variable Arguments are Used +@subsection Calling Variadic Functions + +Functions that are @emph{defined} to be variadic must also be +@emph{declared} to be variadic using a function prototype in the scope +of all calls to it. This is because C compilers might use a different +internal function call protocol for variadic functions than for +functions that take a fixed number and type of arguments. If the +compiler can't determine in advance that the function being called is +variadic, it may end up trying to call it incorrectly and your program +won't work. +@cindex function prototypes +@cindex prototypes for variadic functions +@cindex variadic functions need prototypes + +Since the prototype doesn't specify types for optional arguments, in a +call to a variadic function the @dfn{default argument promotions} are +performed on the optional argument values. This means the objects of +type @code{char} or @code{short int} (whether signed or not) are +promoted to either @code{int} or @code{unsigned int}, as appropriate; +and that objects of type @code{float} are promoted to type +@code{double}. So, if the caller passes a @code{char} as an optional +argument, it is promoted to a @code{int}, and the function should get it +with @code{va_arg (@var{ap}, int)}. + +Promotions of the required arguments are determined by the function +prototype in the usual way (as if by assignment to the types of the +corresponding formal parameters). +@cindex default argument promotions +@cindex argument promotion + +@node Variable Arguments Interface, Example of Variable Arguments, How Variable Arguments are Used, Variable Argument Facilities +@section Variable Arguments Interface + +Here are descriptions of the macros used to retrieve variable arguments. +These macros are defined in the header file @file{stdarg.h}. +@pindex stdarg.h + +@comment stdarg.h +@comment ANSI +@deftp {Data Type} va_list +The type @code{va_list} is used for argument pointer variables. +@end deftp + +@comment stdarg.h +@comment ANSI +@deftypefn {Macro} void va_start (va_list @var{ap}, @var{last_required}) +This macro initialized the argument pointer variable @var{ap} to point +to the first of the optional arguments of the current function; +@var{last_required} must be the last required argument to the function. +@end deftypefn + +@comment stdarg.h +@comment ANSI +@deftypefn {Macro} @var{type} va_arg (va_list @var{ap}, @var{type}) +The @code{va_arg} macro returns the value of the next optional argument, +and changes the internal state of @var{ap} to move past this argument. +Thus, successive uses of @code{va_arg} return successive optional +arguments. +The type of the value returned by @code{va_arg} is the @var{type} +specified in the call. + +The @var{type} must match the type of the actual argument, and must not +be @code{char} or @code{short int} or @code{float}. (Remember that the +default argument promotions apply to optional arguments.) +@end deftypefn + +@comment stdarg.h +@comment ANSI +@deftypefn {Macro} void va_end (va_list @var{ap}) +This ends the use of @var{ap}. After a @code{va_end} call, further +@code{va_arg} calls with the same @var{ap} may not work. You should invoke +@code{va_end} before returning from the function in which @code{va_start} +was invoked with the same @var{ap} argument. + +In the GNU C library, @code{va_end} does nothing, and you need not ever +use it except for reasons of portability. +@refill +@end deftypefn + + +@node Example of Variable Arguments, , Variable Arguments Interface, Variable Argument Facilities +@section Example of Variable Arguments + +Here is a complete sample function that accepts variable numbers of +arguments. The first argument to the function is the count of remaining +arguments, which are added up and the result returned. (This is +obviously a rather pointless function, but it serves to illustrate the +way the variable arguments facility is commonly used.) + +@comment Yes, this example has been tested. + +@example +#include <stdarg.h> + +int +add_em_up (int count, @dots{}) +@{ + va_list ap; + int i, sum; + + va_start (ap, count); /* @r{Initialize the argument list.} */ + + sum = 0; + for (i = 0; i < count; i++) + sum = sum + va_arg (ap, int); /* @r{Get the next argument value.} */ + + va_end (ap); /* @r{Clean up.} */ + return sum; +@} + +void main (void) +@{ + /* @r{This call prints 16.} */ + printf ("%d\n", add_em_up (3, 5, 5, 6)); + + /* @r{This call prints 55.} */ + printf ("%d\n", add_em_up (10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10)); +@} +@end example |