va_arg, va_end, va_start
Go Up to stdarg.h Index
Header File
stdarg.h
Category
Variable Argument List Routines
Prototype
void va_start(va_list ap, lastfix);
type va_arg(va_list ap, type);
void va_end(va_list ap);
Description
Implement a variable argument list.
Some C functions, such as vfprintf and vprintf, take variable argument lists in addition to taking a number of fixed (known) parameters. The va_arg, va_end, and va_start macros provide a portable way to access these argument lists. They are used for stepping through a list of arguments when the called function does not know the number and types of the arguments being passed.
The header file stdarg.h declares one type (va_list) and three macros (va_start, va_arg, and va_end).
- va_list: This array holds information needed by va_arg and va_end. When a called function takes a variable argument list, it declares a variable ap of type va_list.
- va_start: This routine (implemented as a macro) sets ap to point to the first of the variable arguments being passed to the function. va_start must be used before the first call to va_arg or va_end.
- va_start takes two parameters: ap and lastfix. (ap is explained under va_list in the preceding paragraph; lastfix is the name of the last fixed parameter being passed to the called function.)
- va_arg: This routine (also implemented as a macro) expands to an expression that has the same type and value as the next argument being passed (one of the variable arguments). The variable ap to va_arg should be the same ap that va_start initialized.
Note: Because of default promotions, you cannot use char, unsigned char, or float types with va_arg.
Note: The first time va_arg is used, it returns the first argument in the list. Each successive time va_arg is used, it returns the next argument in the list. It does this by first dereferencing ap, and then incrementing ap to point to the following item. va_arg uses the type to both perform the dereference and to locate the following item. Each successive time va_arg is invoked, it modifies ap to point to the next argument in the list.
- va_end: This macro helps the called function perform a normal return. va_end might modify ap in such a way that it cannot be used unless va_start is recalled. va_end should be called after va_arg has read all the arguments; failure to do so might cause strange, undefined behavior in your program.
Return Value
va_start and va_end return no values; va_arg returns the current argument in the list (the one that ap is pointing to).
Example
#include <stdio.h> #include <stdarg.h> /* calculate sum of a 0 terminated list */ void sum(char *msg, ...) { int total = 0; va_list ap; int arg; va_start(ap, msg); while ((arg = va_arg(ap,int)) != 0) { total += arg; } printf(msg, total); va_end(ap); } int main(void) { sum("The total of 1+2+3+4 is %d\n", 1,2,3,4,0); return 0; }
Portability
POSIX | Win32 | ANSI C | ANSI C++ |
---|---|---|---|
+ |
+ |
+ |
+ |