C Reference ยท Functions and Scope
Variadic functions in C
Reference for variadic functions in C: the ... parameter, va_start, va_arg, va_end, va_copy, default argument promotions and safe designs like printf wrappers.
A variadic function accepts a variable number of arguments. It is declared with an ellipsis ... after at least one named parameter (in C23 the ellipsis may stand alone). The macros in <stdarg.h> let the function walk through the extra arguments: va_start begins, va_arg fetches the next value of a type you name, and va_end finishes.
The compiler cannot check the extra arguments. The function itself must know how many there are and what types they have, through a count, a sentinel value, or a format string like the one printf reads. If the function guesses wrong, the behavior is undefined.
#include <stdarg.h> int sum(int count, ...); /* sum(3, 10, 20, 30) */
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> return-type name(type named, ...); va_list ap; va_start(ap, named); /* named: the last parameter before ... */ T value = va_arg(ap, T); /* fetch the next argument as type T */ va_copy(dest, ap); /* duplicate the current position */ va_end(ap); /* clean up; required before returning */
| Name | Description |
|---|---|
va_list |
Type that holds the state of the argument walk. |
va_start(ap, last) |
Initializes ap. In C23 the second argument is optional (va_start(ap)), and ... may be the only parameter. |
va_arg(ap, T) |
Expands to the next argument, which must really have type T (after promotions). |
va_copy(d, s) |
Makes d a copy of s, to be ended separately with va_end. |
va_end(ap) |
Ends use of ap. Every va_start and va_copy needs a matching call. |
Errors / undefined behavior: calling va_arg more times than arguments were passed, requesting an incompatible type, using va_list after va_end, or forgetting va_end are all undefined. Passing a va_list to another function (like vprintf) and then using it again in the caller is also undefined; use va_copy first.
Usage notes
- Default argument promotions apply to the extra arguments:
charandshortare passed asint,floatasdouble. Ask forint,unsignedordoubleinva_arg, neverchar,shortorfloat. - Pass the right types.
average(3, 1, 2, 3)with integer literals is undefined, becauseva_arg(args, double)reads adouble. Write1.0. - Null sentinels should be a pointer of the expected type: write
(char *)NULLornullptr(C23) in caseNULLexpands to plain0. - Provide a
vvariant (vlog(const char *fmt, va_list ap)) next to a...function so other wrappers can forward arguments. - Format attributes. GCC's
__attribute__((format(printf, 2, 3)))makes the compiler check calls to yourprintf-like functions. - Type safety is gone. Prefer fixed parameters, arrays with a length, or structs when the number of arguments is not truly open-ended.
- You cannot read the argument count from the
va_list; there is nova_count. - Calling convention: a variadic function pointer has a different type than a non-variadic one with the same fixed parameters. Calling through the wrong type is undefined.