Movatterモバイル変換

NAME

stdarg.h - handle variable argument list

SYNOPSIS

#include <stdarg.h>

void va_start(va_listap,argN);
void va_copy(va_listdest, va_listsrc);
type va_arg(va_listap,type);
void va_end(va_listap);

DESCRIPTION

^[CX] The functionality described on this reference page is aligned with the ISO C standard. Any conflict between therequirements described here and the ISO C standard is unintentional. This volume of IEEE Std 1003.1-2001 defers tothe ISO C standard.

The<stdarg.h> header shall contain a set of macros which allows portable functions that accept variable argumentlists to be written. Functions that have variable argument lists (such asprintf())but do not use these macros are inherently non-portable, as different systems use different argument-passing conventions.

The typeva_list shall be defined for variables used to traverse the list.

Theva_start() macro is invoked to initializeap to the beginning of the list before any calls tova_arg().

Theva_copy() macro initializesdest as a copy ofsrc, as if theva_start() macro had been appliedtodest followed by the same sequence of uses of theva_arg() macro as had previously been used to reach the presentstate ofsrc. Neither theva_copy() norva_start() macro shall be invoked to reinitializedest withoutan intervening invocation of theva_end() macro for the samedest.

The objectap may be passed as an argument to another function; if that function invokes theva_arg() macro withparameterap, the value ofap in the calling function is unspecified and shall be passed to theva_end() macroprior to any further reference toap. The parameterargN is the identifier of the rightmost parameter in the variableparameter list in the function definition (the one just before the ...). If the parameterargN is declared with theregister storage class, with a function type or array type, or with a type that is not compatible with the type that resultsafter application of the default argument promotions, the behavior is undefined.

Theva_arg() macro shall return the next argument in the list pointed to byap. Each invocation ofva_arg()modifiesap so that the values of successive arguments are returned in turn. Thetype parameter shall be a type namespecified 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 iftype is not compatible with the type of the actual nextargument (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 inboth types.

• One type is a pointer tovoid and the other is a pointer to a character type.

• ^[XSI]Both types are pointers.

Different types can be mixed, but it is up to the routine to know what type of argument is expected.

Theva_end() macro is used to clean up; it invalidatesap for use (unlessva_start() orva_copy() isinvoked again).

Each invocation of theva_start() andva_copy() macros shall be matched by a corresponding invocation of theva_end() macro in the same function.

Multiple traversals, each bracketed byva_start() ...va_end(), are possible.

EXAMPLES

This example is a possible implementation ofexecl():

#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 alwayspossible 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. Theprintf() function can tell how many arguments are there by theformat argument.

RATIONALE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

The System Interfaces volume of IEEE Std 1003.1-2001,exec,printf()

CHANGE HISTORY

First released in Issue 4. Derived from the ANSI C standard.

Issue 6

This reference page is updated to align with the ISO/IEC 9899:1999 standard.