stdarg(5)                                                         stdarg(5)

NAME
     stdarg - 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
     stdarg.h contains macros that permit the development of portable pro-
     cedures that accept variable numbers of arguments of variable types.
     Routines that have variable argument lists (such as printf()) but do
     not use these macros 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 argu-
     ments 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.
     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 promo-
     tions, the behavior is undefined.

     The parameter parmN is required under strict ANSI C compilation. In
     other compilation modes, parmN need not be supplied and the second
     parameter to the vastart() macro can be left empty (e.g.
     vastart(pvar, );). This allows for routines that contain no parame-
     ters before the ... in the variable parameter list.

     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 promo-
     tions), the behavior is undefined.

     The vaend() macro is used to clean up.

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




Page 1                       Reliant UNIX 5.44                Printed 11/98

stdarg(5)                                                         stdarg(5)

EXAMPLE
     This example gathers into an array a list of arguments that are
     pointers to strings (but not more than MAXARGS arguments) with func-
     tion 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, ...)

NOTES
     It is up to the calling routine to specify how many arguments there
     are, since it is not always possible to determine the number of argu-
     ments from the stack frame. For example, execl() is passed a null
     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 argu-
     ments 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.

SEE ALSO
     vprintf(3S).












Page 2                       Reliant UNIX 5.44                Printed 11/98