NAME

stdargs − handle variable argument list

SYNOPSIS

#include <stdarg.h>

va_list

void va_start(va_list ap, paramN)

type va_arg(va_list ap, type)

void va_end(va_list ap)

DESCRIPTION

This is the ANSI C standard interface for writing portable C functions that accept variable argument lists to be written.  Routines that have variable argument lists (such as printf(3S)) but do not use stdargs are inherently nonportable, as different machines use different argument-passing conventions. 

ANSI C requires that all functions that expect variable argument list be declared and defined using function prototype declarators terminated with the ellipsis notation (...), and that there be at least one parameter.  The use of the ellipsis notation in the function prototype is necessary to tell the compiler that the function will receive a variable argument list, and the parameter is required to provide va_start with its paramN argument. 

va_list is a type suitable for holding information needed by the macros va_start, va_arg, va_end.  Programs should make no assumptions about what type va_list actually is, and variables of type va_list may only be used with one of the stdarg macros, assigned to other variables of va_list type, or passed to functions.  All other uses of va_list type variables are nonportable and unreliable. 

va_start is called to initialize ap to the beginning of the variable argument list.  It must be called before any access to the unnamed arguments.  paramN is the identifier of the right most argument (just before the ...).  It must not be declared with the register storage class, and must have a type compatible with the default argument type promotion rules (i.e. no char, short, or float types). 

va_arg will return the next argument in the list pointed to by ap.  Type is the type the argument is expected to be.  Different types can be mixed, but it is up to the routine to know what type of argument is expected, as it cannot be determined at runtime.  Type must be compatible with the types that result from the default argument promotion rules. 

va_end is used to clean up the argument stack pointed to by ap.  It must be called before a function whose variable argument list was referred to by the va_start macro is returned from. 

Multiple traversals, each bracketed by va_start and va_end, are possible. 

EXAMPLE

This example is a possible implementation of execl(2). 

#include <stdarg.h>
#define MAXARGS100
 /∗execl is called by
execl(file, arg1, arg2, ..., (char ∗)0);
∗/
execl(char ∗ file, ...)
{
va_list ap;
char ∗args[MAXARGS];
int argno = 0;
 va_start(ap, file);
file = va_arg(ap, char ∗);
while ((args[argno++] = va_arg(ap, char ∗)) != (char ∗)0)
;
va_end(ap);
return execv(file, args);
}

SEE ALSO

exec(2), varargs(5), printf(3S). 

CAUTIONS

It is up to the calling routine to specify how many arguments there are, since it is not always possible to determine this from the stack frame.  For example, execl is passed a zero pointer to signal the end of the list.  Printf can tell how many arguments are there by the format. 
 

CX/UX Programmer’s Reference Manual