VARARGS(3)

NAME
varargs - handle variable argument list

SYNOPSIS
#include <varargs.h>

function(va_alist) va_dcl

va_list pvar;

va_start(pvar);

f = va_arg(pvar, type);

va_end(pvar);

DESCRIPTION

This set of macros provides a means of writing portable procedures that accept variable argument lists. Routines having variable argument lists (such as printf(3V)) but do not use varargs() are inherently nonportable, since different machines use different argument passing conventions. Routines with variable arguments lists must use varargs() functions in order to run correctly on Sun-4 systems.

va_alist() is used in a function header to declare a variable argument list.

va_dcl() is a declaration for va_alist(). No semicolon should follow va_dcl().

va_list() is a type defined for the variable used to traverse the list. One such variable must always be declared.

va_start (pvar) is called to initialize pvar to the beginning of the list.

va_arg (pvar, type) will return the next argument in the list pointed to by pvar. The parameter type is a type name such that the type of a pointer to an object that has the specified type can be obtained simply by appending a * to type. If type disagrees with the type of the actual next argument (as promoted according to the default argument promotions), the behavior is undefined.

In standard C, arguments that are char or short are converted to int and should be accessed as int, arguments that are unsigned char or unsigned short are converted to unsigned int and should be accessed as unsigned int, and arguments that are float are converted to double and should be accessed as double. Different types can be mixed, but it is up to the routine to know what type of argument is expected, since it cannot be determined at runtime.

va_end (pvar) is used to finish up.

Multiple traversals, each bracketed by va_start() ... va_end(), are possible.

va_alist() must encompass the entire arguments list. This insures that a #define statement can be used to redefine or expand its value.

The argument list (or its remainder) can be passed to another function using a pointer to a variable of type va_list() — in which case a call to va_arg() in the subroutine advances the argument-list pointer with respect to the caller as well.

EXAMPLE
This example is a possible implementation of execl(3V).
    #include <varargs.h>
    #define MAXARGS	100

    /*	execl is called by
    *	execl(file, arg1, arg2, ..., (char *)0);
    */
    execl (va_alist)
    va_dcl
    {
    	va_list ap;
    	char *file;
    	char *args[MAXARGS];
    	int argno = 0;

    	va_start (ap);
    	file = va_arg(ap, char *);
    	while ((args[argno++] = va_arg(ap, char *)) != (char *)0)
    		;
     	va_end (ap);
    	return execv(file, args);
    }

SEE ALSO
execl(3V), printf(3V)

BUGS

It is up to the calling routine to specify how many arguments there are, since it is not 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 supposed to be there by the format.

The macros va_start() and va_end() may be arbitrarily complex; for example, va_start() might contain an opening brace, which is closed by a matching brace in va_end(). Thus, they should only be used where they could be placed within a single complex statement.