1stdarg(3EXT) Extended Library Functions stdarg(3EXT)
2
3
4
6 stdarg - handle variable argument list
7
9 #include <stdarg.h>
10 va_list pvar;
11
12 void va_start(va_list pvar, void name);
13
14
15 (type *) va_arg(va_list pvar, type);
16
17
18 void va_copy(va_list dest, va_list src);
19
20
21 void va_end(va_list pvar);
22
23
25 This set of macros allows portable procedures that accept variable num‐
26 bers of arguments of variable types to be written. Routines that have
27 variable argument lists (such as printf) but do not use stdarg are
28 inherently non-portable, as different machines use different argument-
29 passing conventions.
30
31
32 va_list is a type defined for the variable used to traverse the list.
33
34
35 The va_start macro is invoked before any access to the unnamed argu‐
36 ments and initializes pvar for subsequent use by va_arg() and va_end().
37 The parameter name is the identifier of the rightmost parameter in the
38 variable parameter list in the function definition (the one just before
39 the , ...). If this parameter is declared with the register storage
40 class or with a function or array type, or with a type that is not com‐
41 patible with the type that results after application of the default
42 argument promotions, the behavior is undefined.
43
44
45 The parameter name is required under strict ANSI C compilation. In
46 other compilation modes, name need not be supplied and the second
47 parameter to the va_start() macro can be left empty (for example,
48 va_start(pvar, );). This allows for routines that contain no parameters
49 before the ... in the variable parameter list.
50
51
52 The va_arg() macro expands to an expression that has the type and value
53 of the next argument in the call. The parameter pvar should have been
54 previously initialized by va_start(). Each invocation of va_arg() modi‐
55 fies pvar so that the values of successive arguments are returned in
56 turn. The parameter type is the type name of the next argument to be
57 returned. The type name must be specified in such a way so that the
58 type of a pointer to an object that has the specified type can be
59 obtained simply by postfixing a * to type. If there is no actual next
60 argument, or if type is not compatible with the type of the actual next
61 argument (as promoted according to the default argument promotions),
62 the behavior is undefined.
63
64
65 The va_copy() macro saves the state represented by the va_listsrc in
66 the va_list dest. The va_list passed as dest should not be initialized
67 by a previous call to va_start(), and must be passed to va_end() before
68 being reused as a parameter to va_start() or as the dest parameter of a
69 subsequent call to va_copy(). The behavior is undefined should any of
70 these restrictions not be met.
71
72
73 The va_end() macro is used to clean up.
74
75
76 Multiple traversals, each bracketed by va_start() and va_end(), are
77 possible.
78
80 Example 1 A sample program.
81
82
83 This example gathers into an array a list of arguments that are point‐
84 ers to strings (but not more than MAXARGS arguments) with function f1,
85 then passes the array as a single argument to function f2. The number
86 of pointers is specified by the first argument to f1.
87
88
89 #include <stdarg.h>
90 #define MAXARGS 31
91 void f1(int n_ptrs, ...)
92 {
93 va_list ap;
94 char *array[MAXARGS];
95 int ptr_no = 0;
96
97 if (n_ptrs > MAXARGS)
98 n_ptrs = MAXARGS;
99 va_start(ap, n_ptrs);
100 while (ptr_no < n_ptrs)
101 array[ptr_no++] = va_arg(ap, char*);
102 va_end(ap);
103 f2(n_ptrs, array);
104 }
105
106
107
108 Each call to f1 shall have visible the definition of the function or a
109 declaration such as
110
111
112 void f1(int, ...)
113
114
115
117 See attributes(5) for descriptions of the following attributes:
118
119
120
121
122 ┌─────────────────────────────┬─────────────────────────────┐
123 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
124 ├─────────────────────────────┼─────────────────────────────┤
125 │Interface Stability │Standard │
126 └─────────────────────────────┴─────────────────────────────┘
127
129 vprintf(3C), attributes(5), standards(5)
130
132 It is the responsibility of the calling routine to specify in some man‐
133 ner how many arguments there are, since it is not always possible to
134 determine the number of arguments from the stack frame. For example,
135 execl is passed a zero pointer to signal the end of the list. The
136 printf function can determine the number of arguments by the format. It
137 is non-portable to specify a second argument of char, short, or float
138 to va_arg(), because arguments seen by the called function are not
139 char, short, or float. C converts char and short arguments to int and
140 converts float arguments to double before passing them to a function.
141
142
143
144SunOS 5.11 22 Mar 2006 stdarg(3EXT)