Skip to content
Tutorials Center
My learning

Topics

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.

C
#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

C Summing a counted list and a sentinel list

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.

C Forwarding to vsnprintf and using va_copy

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

C
#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 char and short are passed as int, and float is passed as double. Ask for va_arg(ap, int) and va_arg(ap, double), never char, short or float; asking for them is undefined.
  • Match types exactly. Passing 10 and reading long is wrong. A null pointer sentinel should be cast: (const char *)NULL, because plain 0 or NULL may be passed as an int.
  • 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. After va_arg consumed the arguments, you cannot rewind. Use va_copy before the first pass if you need a second one, and call va_end on every copy.
  • Pass va_list to v functions. vprintf, vfprintf, vsprintf and vsnprintf take a va_list so wrapper functions can forward their arguments. After such a call, the va_list value is indeterminate: do not use it again except with va_end.
  • va_start in C23. C23 allows int f(...) with no named parameter and makes the second argument of va_start optional: 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_list is 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_end and va_list; va_copy in C99; optional parmN in C23.