stdarg(5)                        DG/UX R4.11                       stdarg(5)


NAME
       stdarg: vastart, vaarg, vaend - handle variable argument list

SYNOPSIS
       #include <stdarg.h>
       valist pvar;
       void vastart(valist pvar, parmN);
       type vaarg(valist pvar, type);
       void vaend(valist pvar);

DESCRIPTION
       This set of macros allows portable procedures that accept variable
       numbers of arguments of variable types to be written.  Routines that
       have variable argument lists [such as printf] but do not use stdarg
       are inherently non-portable, as different machines use different
       argument-passing conventions.

       valist is a type defined for the variable used to traverse the list.

       The vastart() macro is invoked before any access to the unnamed
       arguments and initializes pvar for subsequent use by vaarg() and
       vaend(). The parameter parmN is the identifier of the rightmost
       parameter in the variable parameter list in the function definition
       (the one just before the , ...).  If this parameter is declared with
       the register storage class or with a function 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 vaarg() macro expands to an expression that has the type and
       value of the next argument in the call.  The parameter pvar should
       have been previously initialized by vastart().  Each invocation of
       vaarg() modifies pvar so that the values of successive arguments are
       returned in turn.  The parameter type is the type name of the next
       argument to be returned. The type name must be specified in such a
       way so 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.

       The vaend() macro is used to clean up.

       Multiple traversals, each bracketed by vastart and vaend, are
       possible.

EXAMPLE
       This example gathers into an array a list of arguments that are
       pointers to strings (but not more than MAXARGS arguments) with
       function f1, then passes the array as a single argument to function
       f2.  The number of pointers is specified by the first argument to f1.

            #include <stdarg.h>
            #define MAXARGS     31

            void f1(int nptrs, ...)
            {
                 valist ap;
                 char *array[MAXARGS];
                 int ptrno = 0;

                 if (nptrs > MAXARGS)
                      nptrs = MAXARGS;
                 vastart(ap, nptrs);
                 while (ptrno < nptrs)
                      array[ptrno++] = vaarg(ap, char*);
                 vaend(ap);
                 f2(nptrs, array);
            }

       Each call to f1 shall have visible the definition of the function or
       a declaration such as

              void f1(int, ...)

SEE ALSO
       vprintf(3S).

NOTES
       It is up to the calling routine to specify in some manner how many
       arguments there are, since it is not always possible to determine the
       number of arguments 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 there are by the format.  It is non-portable to
       specify a second argument of char, short, or float to vaarg, because
       arguments seen by the called function are not char, short, or float.
       C converts char and short arguments to int and converts float
       arguments to double before passing them to a function.


Licensed material--property of copyright holder(s)