va_arg(9F)						   Kernel Functions for Drivers 						va_arg(9F)

NAME

       va_arg, va_start, va_copy, va_end - handle variable argument list

SYNOPSIS

       #include <sys/varargs.h>

       void va_start(va_list pvar, void parmN);

       (type *)

       va_arg(va_list pvar, type);

       void va_copy(va_list dest, va_list src);

       void va_end(va_list pvar);

INTERFACE LEVEL

       Solaris DDI specific (Solaris DDI).

PARAMETERS

   va_start()
       pvar	       Pointer to variable argument list.

       name	       Identifier of rightmost parameter in the function definition.

   va_arg()
       pvar	       Pointer to variable argument list.

       type	       Type name of the next argument to be returned.

   va_copy()
       dest	       Destination variable argument list.

       src	       Source variable argument list.

   va_end()
       pvar	       Pointer to variable argument list.

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 different argument-passing conventions. Routines
       that accept a variable argument list can use these macros to traverse the list.

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

       va_start()  is  called  to initialize  pvar to the beginning of the variable argument list. va_start() 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 defi-
       nition (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.

       va_arg()  expands to an expression that has the type and value of the next argument in the call.  The parameter pvar must be initialized by
       va_start(). Each invocation of va_arg() 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 promotions), the behavior is undefined.

       The  va_copy()  macro saves the state represented by the va_list src in the va_list dest. The va_list passed as dest should not be initial-
       ized by a previous call to va_start() It then must be passed to va_end() before being reused as a parameter to va_start() or  as  the  dest
       parameter of a subsequent call to va_copy(). The behavior is undefined if any of these restrictions are not met.

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

       Multiple traversals, each bracketed by a call to va_start() and va_end(), are possible.

EXAMPLES

       Example 1: Creating a Variable Length Command

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

       static void
       xx_write_cmd(uchar_t *cmdp, int ncmdbytes, ...)
       {
	       va_list	   ap;
	       int    i;

		   /*
		* Write variable-length command to destination
		    */
		va_start(ap, ncmdbytes);
		for (i = 0; i < ncmdbytes; i++) {
			 *cmdp++ = va_arg(ap, uchar_t);
		    }
		va_end(ap);
       }

SEE ALSO

       vcmn_err(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 possible	to  determine  the
       number of arguments from the stack frame.

       Specifying  a  second argument of char or  short to  va_arg 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.10							    21 Feb 1996 							va_arg(9F)