va_arg(), va_copy(), va_end(), va_start() — Access Function Arguments
Format
#include <stdarg.h>
var_type va_arg(va_list arg_ptr, var_type);
void va_end(va_list arg_ptr);
void va_start(va_list arg_ptr, variable_name);#define _ISOC99_SOURCE
#include <stdarg.h>
var_type va_arg(va_list arg_ptr, var_type);
void va_end(va_list arg_ptr);
void va_start(va_list arg_ptr, variable_name);
void va_copy(va_list dest, va_list src);General Description
The va_arg(), va_end(), and va_start() macros access the arguments to a function when it takes a fixed number of required arguments and a variable number of optional arguments. You declare required arguments as ordinary parameters to the function and access the arguments through the parameter names.
The va_start() macro initializes the arg_ptr pointer for subsequent calls to va_arg() and va_end().
The argument variable_name is the identifier of the rightmost
named parameter in the parameter list (preceding , …).
Use the va_start() macro before the va_arg() macro. Corresponding
va_start() and va_end() macro calls must be in the same function.
If variable_name is declared as a register, with a function
or an array type, or with a type that is not compatible with the type
that results after application of the default argument promotions,
then the behavior is undefined.
The va_arg() macro retrieves a value of the given var_type from the location given by arg_ptr and increases arg_ptr to point to the next argument in the list. The va_arg() macro can retrieve arguments from the list any number of times within the function.
The macros also provide fixed-point decimal support under z/OS® XL C.
The sizeof(xx) operator is used to determine the size and
type casting that is used to generate the values. Therefore, a call,
such as, x = va_arg(ap, _Decimal(5,2)); is valid. The size
of a fixed-point decimal number, however, cannot be made a variable.
Therefore, a call, such as, z = va_arg(ap, _Decimal(x,y)) where x
= 5 and y = 2 is not valid.
The va_end() macro is needed by some systems to indicate the end of parameter scanning.
va_start() and va_arg() do not work with parameter lists of functions
whose linkages were changed with the #pragma linkage directive.
stdarg.h and varargs.h are mutually exclusive. Whichever #include comes first, determines the form of macro that is visible.
The type definition for the va_list type in this implementation is "char *va_list".
The va_copy() function creates a copy (dest) of a variable of type va_list (src). The copy appear as if it has gone through a va_start() and the exact set of sequences of va_arg() as that of src.
After va_copy() initializes dest, the va_copy() macro shall not be invoked to reinitialize dest without an intervening invocation of the va_end() macro for the same dest.
Returned Value
The va_arg() macro returns the current argument.
The va_end(), va_copy(), and va_start() macros return no values.