Provided by: manpages-posix-dev_2013a-2_all 
PROLOG
This manual page is part of the POSIX Programmer's Manual. The Linux implementation of
this interface may differ (consult the corresponding Linux manual page for details of
Linux behavior), or the interface may not be implemented on Linux.
NAME
stdarg.h — handle variable argument list
SYNOPSIS
#include <stdarg.h>
void va_start(va_list ap, argN);
void va_copy(va_list dest, va_list src);
type va_arg(va_list ap, type);
void va_end(va_list ap);
DESCRIPTION
The functionality described on this reference page is aligned with the ISO C standard. Any
conflict between the requirements described here and the ISO C standard is unintentional.
This volume of POSIX.1‐2008 defers to the ISO C standard.
The <stdarg.h> header shall contain a set of macros which allows portable functions that
accept variable argument lists to be written. Functions that have variable argument lists
(such as printf()) but do not use these macros are inherently non-portable, as different
systems use different argument-passing conventions.
The <stdarg.h> header shall define the va_list type for variables used to traverse the
list.
The va_start() macro is invoked to initialize ap to the beginning of the list before any
calls to va_arg().
The va_copy() macro initializes dest as a copy of src, as if the va_start() macro had been
applied to dest followed by the same sequence of uses of the va_arg() macro as had
previously been used to reach the present state of src. Neither the va_copy() nor
va_start() macro shall be invoked to reinitialize dest without an intervening invocation
of the va_end() macro for the same dest.
The object ap may be passed as an argument to another function; if that function invokes
the va_arg() macro with parameter ap, the value of ap in the calling function is
unspecified and shall be passed to the va_end() macro prior to any further reference to
ap. The parameter argN is the identifier of the rightmost parameter in the variable
parameter list in the function definition (the one just before the ...). If the parameter
argN is declared with the register storage class, with a function type or array type, or
with a type that is not compatible with the type that results after application of the
default argument promotions, the behavior is undefined.
The va_arg() macro shall return the next argument in the list pointed to by ap. Each
invocation of va_arg() modifies ap so that the values of successive arguments are returned
in turn. The type parameter shall be a type name specified such that the type of a pointer
to an object that has the specified type can be obtained simply by postfixing a '*' to
type. If there is no actual next argument, or if type is not compatible with the type of
the actual next argument (as promoted according to the default argument promotions), the
behavior is undefined, except for the following cases:
* One type is a signed integer type, the other type is the corresponding unsigned
integer type, and the value is representable in both types.
* One type is a pointer to void and the other is a pointer to a character type.
* Both types are pointers.
Different types can be mixed, but it is up to the routine to know what type of argument is
expected.
The va_end() macro is used to clean up; it invalidates ap for use (unless va_start() or
va_copy() is invoked again).
Each invocation of the va_start() and va_copy() macros shall be matched by a corresponding
invocation of the va_end() macro in the same function.
Multiple traversals, each bracketed by va_start() ... va_end(), are possible.
The following sections are informative.
EXAMPLES
This example is a possible implementation of execl():
#include <stdarg.h>
#define MAXARGS 31
/*
* execl is called by
* execl(file, arg1, arg2, ..., (char *)(0));
*/
int execl(const char *file, const char *args, ...)
{
va_list ap;
char *array[MAXARGS +1];
int argno = 0;
va_start(ap, args);
while (args != 0 && argno < MAXARGS)
{
array[argno++] = args;
args = va_arg(ap, const char *);
}
array[argno] = (char *) 0;
va_end(ap);
return execv(file, array);
}
APPLICATION USAGE
It is up to the calling routine to communicate to the called routine how many arguments
there are, since it is not always possible for the called routine to determine this in any
other way. For example, execl() is passed a null pointer to signal the end of the list.
The printf() function can tell how many arguments are there by the format argument.
RATIONALE
None.
FUTURE DIRECTIONS
None.
SEE ALSO
The System Interfaces volume of POSIX.1‐2008, exec, fprintf()
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form from IEEE Std
1003.1, 2013 Edition, Standard for Information Technology -- Portable Operating System
Interface (POSIX), The Open Group Base Specifications Issue 7, Copyright (C) 2013 by the
Institute of Electrical and Electronics Engineers, Inc and The Open Group. (This is
POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the event of any
discrepancy between this version and the original IEEE and The Open Group Standard, the
original IEEE and The Open Group Standard is the referee document. The original Standard
can be obtained online at http://www.unix.org/online.html .
Any typographical or formatting errors that appear in this page are most likely to have
been introduced during the conversion of the source files to man page format. To report
such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .