C Reference ยท ctype.h, math.h and others
C stdarg.h: va_list, va_start, va_arg
Reference for stdarg.h: write variadic functions with va_list, va_start, va_arg, va_copy and va_end, forward arguments to vprintf, and avoid the type traps.
<stdarg.h> is the header behind functions such as printf that accept a variable number of arguments. A function declared with ... as its last parameter can be called with any number of extra arguments, and the macros in this header let that function read them one at a time.
There is no type checking and no argument count: the function must learn both from somewhere else, usually a count parameter, a sentinel value, or a format string. Getting it wrong is undefined behavior.
#include <stdarg.h> int sum(int count, ...); /* declaration */ va_list ap; /* state of the walk */ va_start(ap, count); /* begin after the last named parameter */ int next = va_arg(ap, int); /* fetch an argument of a claimed type */ va_end(ap); /* finish */
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Syntax
#include <stdarg.h> typedef /* implementation-defined */ va_list; void va_start(va_list ap, parmN); /* C23: parmN is optional, and ignored */ type va_arg(va_list ap, type); void va_copy(va_list dest, va_list src); /* C99 */ void va_end(va_list ap);
| Name | Description |
|---|---|
ap |
An object of type va_list that tracks the current position in the argument list. |
parmN |
The last named parameter before the .... Must not be declared register, a function or an array. |
type |
The type you expect the next argument to have, after the default argument promotions. |
dest, src |
va_copy makes dest an independent copy of the position in src. |
Returns: va_arg yields the next argument converted to type. The other macros return nothing.
Errors / undefined behavior: the behavior is undefined if va_arg runs out of arguments, if type is not compatible with the real argument type, if you call va_arg on a va_list after passing it to another function that used it (such as vprintf), or if you leave a function without va_end after va_start or va_copy.
Usage notes
- Default argument promotions apply. Extra arguments have no declared type, so
charandshortare passed asint, andfloatis passed asdouble. Ask forva_arg(ap, int)andva_arg(ap, double), neverchar,shortorfloat; asking for them is undefined. - Match types exactly. Passing
10and readinglongis wrong. A null pointer sentinel should be cast:(const char *)NULL, because plain0orNULLmay be passed as anint. - How does the function know when to stop? Three common ways: an explicit count, a sentinel value, or a format string that describes the arguments like
printf. The compiler cannot check any of them; with GCC,__attribute__((format(printf, 1, 2)))enables format warnings. - One pass per
va_list. Afterva_argconsumed the arguments, you cannot rewind. Useva_copybefore the first pass if you need a second one, and callva_endon every copy. - Pass
va_listtovfunctions.vprintf,vfprintf,vsprintfandvsnprintftake ava_listso wrapper functions can forward their arguments. After such a call, theva_listvalue is indeterminate: do not use it again except withva_end. va_startin C23. C23 allowsint f(...)with no named parameter and makes the second argument ofva_startoptional:va_start(ap)begins at the very first argument. A second argument, if present, is ignored. Before C23 such a function could not read its arguments portably. GCC 15 accepts this in C23 mode.- Cost. Reading each argument is O(1). On many ABIs a
va_listis an array type of one element, so it decays to a pointer when passed to a function, but you should treat it as opaque. - Standard version: C89 for
va_start,va_arg,va_endandva_list;va_copyin C99; optionalparmNin C23.