va_end(9f) - osol9

1va_arg(9F)               Kernel Functions for Drivers               va_arg(9F)
2
3
4

NAME

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

SYNOPSIS

9       #include <sys/varargs.h>
10
11
12
13       void va_start(va_list pvar, name);
14
15
16       (type *) va_arg(va_list pvar, type);
17
18
19       void va_copy(va_list dest, va_list src);
20
21
22       void va_end(va_list pvar);
23
24

INTERFACE LEVEL

26       Solaris DDI specific (Solaris DDI).
27

PARAMETERS

29   va_start()
30       pvar    Pointer to variable argument list.
31
32
33       name    Identifier of rightmost parameter in the function definition.
34
35
36   va_arg()
37       pvar    Pointer to variable argument list.
38
39
40       type    Type name of the next argument to be returned.
41
42
43   va_copy()
44       dest    Destination variable argument list.
45
46
47       src     Source variable argument list.
48
49
50   va_end()
51       pvar    Pointer to variable argument list.
52
53

DESCRIPTION

55       This  set  of  macros  allows  portable procedures that accept variable
56       argument lists to be written.  Routines  that  have  variable  argument
57       lists but do not use the varargs macros are inherently non-portable, as
58       different machines use different argument-passing conventions. Routines
59       that  accept  a variable argument list can use these macros to traverse
60       the list.
61
62
63       va_list is the type defined for the variable used to traverse the  list
64       of arguments.
65
66
67       va_start()  is  called to initialize pvar to the beginning of the vari‐
68       able argument list. va_start() must be invoked before any access to the
69       unnamed  arguments.  The parameter name is the identifier of the right‐
70       most parameter in the variable parameter list in the  function  defini‐
71       tion  (the  one just before the ", ..."). If this parameter is declared
72       with the register storage class or with a function or  array  type,  or
73       with  a  type  that  is not compatible with the type that results after
74       application of the default argument promotions, the behavior  is  unde‐
75       fined.
76
77
78       va_arg()  expands  to  an expression that has the type and value of the
79       next argument in the call. The parameter pvar must  be  initialized  by
80       va_start().  Each invocation of va_arg() modifies pvar so that the val‐
81       ues of successive arguments are returned in turn. The parameter type is
82       the  type  name of the next argument to be returned. The type name must
83       be specified in such a way that the type of pointer to an  object  that
84       has  the  specified  type can be obtained by postfixing a * to type. If
85       there is no actual next argument, or iftype is not compatible with  the
86       type  of the actual next argument (as promoted according to the default
87       argument promotions), the behavior is undefined.
88
89
90       The va_copy() macro saves the state represented by  the  va_listsrc  in
91       the  va_list dest. The va_list passed as dest should not be initialized
92       by a previous call to va_start() It then must  be  passed  to  va_end()
93       before being reused as a parameter to va_start() or as the dest parame‐
94       ter of a subsequent call to va_copy(). The behavior is undefined if any
95       of these restrictions are not met.
96
97
98       The  va_end()  macro  is  used to clean up. It invalidates pvar for use
99       (unless va_start() is invoked again).
100
101
102       Multiple traversals,  each  bracketed  by  a  call  to  va_start()  and
103       va_end(), are possible.
104

EXAMPLES

106       Example 1 Creating a Variable Length Command
107
108
109       The  following  example uses these routines to create a variable length
110       command. This might be useful for a device that provides  for  a  vari‐
111       able-length  command  set. ncmdbytes is the number of bytes in the com‐
112       mand. The new command is written to cmdp.
113
114
115         static void
116         xx_write_cmd(uchar_t *cmdp, int ncmdbytes, ...)
117         {
118                 va_list     ap;
119                 int    i;
120
121                     /*
122                  * Write variable-length command to destination
123                      */
124                  va_start(ap, ncmdbytes);
125                  for (i = 0; i < ncmdbytes; i++) {
126                           *cmdp++ = va_arg(ap, uchar_t);
127                      }
128                  va_end(ap);
129         }
130
131

NOTES

136       It is up to the calling routine to specify  in  some  manner  how  many
137       arguments  there  are, since it is not always possible to determine the
138       number of arguments from the stack frame.
139
140
141       Specifying a second argument of char or short to va_arg makes your code
142       non-portable,  because  arguments  seen  by the called function are not
143       char or short. C converts char and short arguments to int before  pass‐
144       ing them to a function.
145
146
147
148SunOS 5.11                        22 Mar 2006                       va_arg(9F)