Kernel Functions for Drivers                           vaarg(9F)



NAME
     vaarg, vastart, vacopy, vaend - handle variable argument
     list

SYNOPSIS
     #include 



     void vastart(valist pvar, name);


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


     void vacopy(valist dest, valist src);


     void vaend(valist pvar);


INTERFACE LEVEL
     Solaris DI specific (Solaris DI).

PARAMETERS
  vastart()
     pvar    Pointer to variable argument list.


     name    Identifier of rightmost parameter  in  the  function
             definition.


  vaarg()
     pvar    Pointer to variable argument list.


     type    Type name of the next argument to be returned.


  vacopy()
     dest    Destination variable argument list.


     src     Source variable argument list.


  vaend()
     pvar    Pointer to variable argument list.






SunOS 5.11          Last change: 22 Mar 2006                    1






Kernel Functions for Drivers                           vaarg(9F)



DESCRIPTION
     This set of macros allows portable  procedures  that  accept
     variable  argument  lists  to be written. Routines that have
     variable argument lists but do not use  the  varargs  macros
     are  inherently non-portable, as different machines use dif-
     ferent argument-passing conventions. Routines that accept  a
     variable  argument list can use these macros to traverse the
     list.


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


     vastart() is called to initialize pvar to the beginning  of
     the  variable  argument  list.  vastart()  must  be invoked
     before any access to the unnamed  arguments.  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  promo-
     tions, the behavior is undefined.


     vaarg() expands to an expression  that  has  the  type  and
     value  of  the next argument in the call. The parameter pvar
     must  be  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 that the type of pointer  to
     an  object  that  has  the specified type can be obtained by
     postfixing a * to type. If there is no actual next argument,
     or iftype is not compatible with the type of the actual next
     argument (as promoted according to the default argument pro-
     motions), 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()
     It  then 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 if any of
     these restrictions are not met.


     The vaend() macro is used to clean up. It invalidates  pvar
     for use (unless vastart() is invoked again).




SunOS 5.11          Last change: 22 Mar 2006                    2






Kernel Functions for Drivers                           vaarg(9F)



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

EXAMPLES
     Example 1 Creating a Variable Length Command


     The following example uses these routines to create a  vari-
     able  length command. This might be useful for a device that
     provides for a variable-length command set. ncmdbytes is the
     number  of  bytes in the command. The new command is written
     to cmdp.


       static void
       xxwritecmd(uchart *cmdp, int ncmdbytes, ...)
       {
               valist     ap;
               int    i;

                   /*
                * Write variable-length command to destination
                    */
                vastart(ap, ncmdbytes);
                for (i = 0; i < ncmdbytes; i]) {
                         *cmdp] = vaarg(ap, uchart);
                    }
                vaend(ap);
       }


SEE ALSO
     vcmnerr(9F), vsprintf(9F)

NOTES
     It is up to the calling routine to specify  in  some  manner
     how  many arguments there are, since it is not always possi-
     ble to determine the number  of  arguments  from  the  stack
     frame.


     Specifying a second argument of  char  or  short  to  vaarg
     makes  your code non-portable, because arguments seen by the
     called function are not char or short. C converts  char  and
     short arguments to int before passing them to a function.










SunOS 5.11          Last change: 22 Mar 2006                    3