is a header in the
C standard libraryof the C programming languagethat allows functions to accept an indefinite number of arguments. C++provides this functionality in the header
; the C header, though permitted, is deprecated in C++.
The contents of
are typically used in
variadic functions, though they may be used in other functions (for example,
) called by variadic functions.
Declaring variadic functions
Variadic functions are functions which may take a variable number of arguments and are declared with an
ellipsisin place of the last parameter. An example of such a function is
. A typical declaration is
Variadic functions must have at least one named parameter, so, for instance,
is not allowed in C. (In C++, such a declaration is permitted, but not very useful.) In C, a comma must precede the ellipsis; in C++, it is optional.
Defining variadic functions
The same syntax is used in a definition:
An ellipsis may also appear in old-style function definitions:
Accessing the arguments
To access the unnamed arguments, one must declare a variable of type
va_listin the variadic function. The macro
va_startis then called with two arguments: the first is the
va_list, the second is the name of the last named parameter of the function. After this, each invocation of the
va_argmacro yields the next argument. The first argument to
va_listand the second is the type of the next argument passed to the function. Finally, the
va_endmacro must be called on the
before the function returns. (It is not required to read in all the arguments.)
C99provides an additional macro,
va_copy, which can duplicate the state of a
va_list. The macro invocation
There is no mechanism defined for determining the number or types of the unnamed arguments passed to the function. The function is simply required to know or determine this somehow, the means of which vary. Common conventions include:
* Use of a
printfor scanf-like format string with embedded specifiers that indicate argument types.
* A sentinel value at the end of the variadic arguments.
* A count argument indicating the number of variadic arguments.
Some C implementations, such as GCC, provide C extensions that allow the compiler to check for the proper use of format strings and sentinels. Barring these extensions, the compiler usually cannot check whether the unnamed arguments passed are of the type the function expects. Therefore, care should be taken to ensure correctness in this regard, since
undefined behaviorresults if the types do not match. For example, if passing a null pointer, one should not write simply
NULLbut cast to the appropriate pointer type. Another consideration is the default argument promotions applied to the unnamed arguments. A
floatwill automatically be promoted to a
double. Likewise, arguments of types narrower than an
intwill be promoted to
unsigned int. The function receiving the unnamed arguments must expect the promoted type.
This program yields the output:5 2 14 84 97 15 24 48 84 51
POSIXdefines the legacy header
, which dates from before the standardization of C and provides functionality similar to
. This header is not part of ISO C. The file, as defined in the second version of the
Single Unix Specification, simply contains all of the functionality of C89
stdarg.h, with the exceptions that:
* it cannot be used in Standard C new-style definitions
* you may choose not to have a given argument (Standard C requires at least one argument)
* the way it works is different:
In Standard C, one would write
or with old-style function definitions:
and call with
summate(0); summate(1, 2); summate(4, 9, 2, 3, 2);
, the function would be:
and is called the same way.
requires old-style function definitions because of the way the implementation works. [cite web|url=http://www.opengroup.org/onlinepubs/007908799/xsh/varargs.h.html|title=<varargs.h>|accessdate=1-8-2007]
[http://www.opengroup.org/onlinepubs/009695399/basedefs/stdarg.h.html IEEE Std 1003.1 stdarg.h]
Wikimedia Foundation. 2010.