stdarg.h
<stdarg.h>(P) <stdarg.h>(P)
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 <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 type va_list shall be defined 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 com-
patible with the type of the actual next argument (as promoted accord-
ing 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 corre-
sponding 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 char-
acter 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.
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);
}
The following sections are informative.
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 IEEE Std 1003.1-2001, exec, printf()
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technol-
ogy -- Portable Operating System Interface (POSIX), The Open Group
Base Specifications Issue 6, Copyright (C) 2001-2003 by the Institute
of Electrical and Electronics Engineers, Inc and The Open Group. 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.opengroup.org/unix/online.html .
POSIX 2003 <stdarg.h>(P)
