Extended Library Functions                           stdarg(3EXT)



NAME
     stdarg - handle variable argument list

SYNOPSIS
     #include 
     valist pvar;

     void vastart(valist pvar, void name);


     (type *) vaarg(valist pvar, type);


     void vacopy(valist dest, valist src);


     void vaend(valist pvar);


DESCRIPTION
     This set of macros allows portable  procedures  that  accept
     variable  numbers of arguments of variable types to be writ-
     ten. 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 conven-
     tions.


     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 name 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 parameter name is required under strict ANSI C  compila-
     tion.  In other compilation modes, name need not be supplied
     and the second parameter to the vastart() macro can be left
     empty (for example, vastart(pvar, );). This allows for rou-
     tines that contain no parameters before the ... in the vari-
     able parameter list.






SunOS 5.11          Last change: 22 Mar 2006                    1






Extended Library Functions                           stdarg(3EXT)



     The vaarg() macro expands to an  expression  that  has  the
     type and value of the next argument in the call. The parame-
     ter  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 argu-
     ment 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 vacopy() macro  saves  the  state  represented  by  the
     valistsrc  in  the valist dest. The valist passed as dest
     should not be initialized by a previous call to  vastart(),
     and  must  be  passed  to  vaend() before being reused as a
     parameter to vastart() or as the dest parameter of a subse-
     quent  call  to  vacopy(). The behavior is undefined should
     any of these restrictions not be met.


     The vaend() macro is used to clean up.


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

EXAMPLES
     Example 1 A sample program.


     This example gathers into an array a list of arguments  that
     are  pointers  to  strings  (but not more than MAXARGS argu-
     ments) 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 
       #define MAXARGS     31
       void f1(int nptrs, ...)
       {
            valist ap;
            char *array[MAXARGS];
            int ptrno = 0;

            if (nptrs > MAXARGS)
                 nptrs = MAXARGS;
            vastart(ap, nptrs);



SunOS 5.11          Last change: 22 Mar 2006                    2






Extended Library Functions                           stdarg(3EXT)



            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, ...)



ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability          Standard                    
    


SEE ALSO
     vprintf(3C), attributes(5), standards(5)

NOTES
     It is the responsibility of 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.  The  printf  function  can
     determine  the number of arguments 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 dou-
     ble before passing them to a function.











SunOS 5.11          Last change: 22 Mar 2006                    3