stdarg, va_start, va_arg, va_end, va_copy — variable argument lists
#include <stdarg.h>
void
va_start( |
va_list | ap, |
last) ; |
type
va_arg( |
va_list | ap, |
type) ; |
void
va_end( |
va_list | ap) ; |
void
va_copy( |
va_list | dest, |
va_list | src) ; |
A function may be called with a varying number of
arguments of varying types. The include file <stdarg.h>
declares a
type va_list
and
defines three macros for stepping through a list of arguments
whose number and types are not known to the called
function.
The called function must declare an object of type
va_list
which is
used by the macros va_start
(),
va_arg
(), and va_end
().
The va_start
() macro
initializes ap
for
subsequent use by va_arg
()
and va_end
(), and must be
called first.
The parameter last
is the name of the last
parameter before the variable argument list, i.e., the last
parameter of which the calling function knows the type.
Because the address of this parameter may be used in the
va_start
() macro, it should
not be declared as a register variable, or as a function or
an array type.
The va_arg
() macro expands
to an expression that has the type and value of the next
argument in the call. The parameter ap
is the va_list
ap
initialized by
va_start
(). Each call to
va_arg
() modifies ap
so that the next call
returns the next argument. The parameter type
is a type name specified
so that the type of a pointer to an object that has the
specified type can be obtained simply by adding a * to
type
.
The first use of the va_arg
() macro after that of the
va_start
() macro returns the
argument after last
. Successive invocations
return the values of the remaining arguments.
If there is no next argument, or if type
is not compatible with
the type of the actual next argument (as promoted according
to the default argument promotions), random errors will
occur.
If ap
is passed
to a function that uses va_arg
(ap
, type
) then the value of
ap
is undefined
after the return of that function.
Each invocation of va_start
() must be matched by a
corresponding invocation of va_end
() in the same function. After the
call va_end
(ap
) the variable ap
is undefined. Multiple
transversals of the list, each bracketed by va_start
() and va_end
() are possible. va_end
() may be a macro or a
function.
An obvious implementation would have a va_list
be a pointer to the
stack frame of the variadic function. In such a setup (by
far the most common) there seems nothing against an
assignment
va_list aq = ap;
Unfortunately, there are also systems that make it an array of pointers (of length 1), and there one needs
va_list aq; *aq = *ap;
Finally, on systems where parameters are passed in
registers, it may be necessary for va_start
() to allocate memory, store the
parameters there, and also an indication of which parameter
is next, so that va_arg
() can
step through the list. Now va_end
() can free the allocated memory
again. To accommodate this situation, C99 adds a macro
va_copy
(), so that the above
assignment can be replaced by
va_list aq; va_copy(aq, ap); ... va_end(aq);
Each invocation of va_copy
() must be matched by a
corresponding invocation of va_end
() in the same function. Some
systems that do not supply va_copy
() have __va_copy
instead, since
that was the name used in the draft proposal.
The function foo
takes a string of format characters and prints out the
argument associated with each format character based on the
type.
#include <stdio.h> #include <stdarg.h> void foo(char *fmt, ...) { va_list ap; int d; char c, *s; va_start(ap, fmt); while (*fmt) switch(*fmt++) { case 's': /* string */ s = va_arg(ap, char *); printf("string %s\n", s); break; case 'd': /* int */ d = va_arg(ap, int); printf("int %d\n", d); break; case 'c': /* char */ /* need a cast here since va_arg only takes fully promoted types */ c = (char) va_arg(ap, int); printf("char %c\n", c); break; } va_end(ap); }
The va_start
(), va_arg
(), and va_end
() macros conform to C89. C99 defines
the va_copy
() macro.
These macros are not
compatible with the
historic macros they replace. A backward compatible version
can be found in the include file varargs.h
.
The historic setup is:
#include <varargs.h> void foo(va_alist) va_dcl { va_list ap; va_start(ap); while(...) { ... x = va_arg(ap, type); ... } va_end(ap); }
On some systems, va_end
contains a closing '}' matching a '{' in va_start
, so that both macros must occur in
the same function, and in a way that allows this.
Unlike the varargs
macros, the
stdarg
macros do not permit
programmers to code a function with no fixed arguments. This
problem generates work mainly when converting varargs
code to stdarg
code, but it also creates
difficulties for variadic functions that wish to pass all of
their arguments on to a function that takes a va_list
argument, such as
vfprintf(3).
|