]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1990, 1991 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" This code is derived from software contributed to Berkeley by | |
5 | .\" the American National Standards Committee X3, on Information | |
6 | .\" Processing Systems. | |
7 | .\" | |
a9cd9cb7 | 8 | .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
fea681da MK |
9 | .\" Redistribution and use in source and binary forms, with or without |
10 | .\" modification, are permitted provided that the following conditions | |
11 | .\" are met: | |
12 | .\" 1. Redistributions of source code must retain the above copyright | |
13 | .\" notice, this list of conditions and the following disclaimer. | |
14 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
15 | .\" notice, this list of conditions and the following disclaimer in the | |
16 | .\" documentation and/or other materials provided with the distribution. | |
17 | .\" 3. All advertising materials mentioning features or use of this software | |
18 | .\" must display the following acknowledgement: | |
19 | .\" This product includes software developed by the University of | |
20 | .\" California, Berkeley and its contributors. | |
21 | .\" 4. Neither the name of the University nor the names of its contributors | |
22 | .\" may be used to endorse or promote products derived from this software | |
23 | .\" without specific prior written permission. | |
24 | .\" | |
25 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
26 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
27 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
28 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
29 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
30 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
31 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
32 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
33 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
34 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
35 | .\" SUCH DAMAGE. | |
8c9302dc | 36 | .\" %%%LICENSE_END |
fea681da MK |
37 | .\" |
38 | .\" @(#)stdarg.3 6.8 (Berkeley) 6/29/91 | |
39 | .\" | |
40 | .\" Converted for Linux, Mon Nov 29 15:11:11 1993, faith@cs.unc.edu | |
41 | .\" Additions, 2001-10-14, aeb | |
42 | .\" | |
2e3023c4 | 43 | .TH STDARG 3 2019-05-09 "" "Linux Programmer's Manual" |
fea681da | 44 | .SH NAME |
393a89e6 | 45 | stdarg, va_start, va_arg, va_end, va_copy \- variable argument lists |
fea681da MK |
46 | .SH SYNOPSIS |
47 | .B #include <stdarg.h> | |
68e4db0a | 48 | .PP |
fea681da MK |
49 | .BI "void va_start(va_list " ap ", " last ); |
50 | .br | |
b9d200ce | 51 | .IB type " va_arg(va_list " ap ", " type ); |
fea681da MK |
52 | .br |
53 | .BI "void va_end(va_list " ap ); | |
54 | .br | |
55 | .BI "void va_copy(va_list " dest ", va_list " src ); | |
56 | .SH DESCRIPTION | |
57 | A function may be called with a varying number of arguments of varying | |
c13182ef MK |
58 | types. |
59 | The include file | |
bd12ab88 | 60 | .I <stdarg.h> |
fea681da | 61 | declares a type |
f19a0f03 | 62 | .I va_list |
fea681da MK |
63 | and defines three macros for stepping through a list of arguments whose |
64 | number and types are not known to the called function. | |
65 | .PP | |
66 | The called function must declare an object of type | |
f19a0f03 | 67 | .I va_list |
fea681da | 68 | which is used by the macros |
e511ffb6 MK |
69 | .BR va_start (), |
70 | .BR va_arg (), | |
fea681da | 71 | and |
e511ffb6 | 72 | .BR va_end (). |
dded5e0c | 73 | .SS va_start() |
fea681da | 74 | The |
e511ffb6 | 75 | .BR va_start () |
fea681da MK |
76 | macro initializes |
77 | .I ap | |
78 | for subsequent use by | |
e511ffb6 | 79 | .BR va_arg () |
fea681da | 80 | and |
e511ffb6 | 81 | .BR va_end (), |
fea681da MK |
82 | and must be called first. |
83 | .PP | |
c4bb193f | 84 | The argument |
fea681da | 85 | .I last |
c4bb193f MK |
86 | is the name of the last argument before the variable argument list, that is, |
87 | the last argument of which the calling function knows the type. | |
fea681da | 88 | .PP |
c4bb193f | 89 | Because the address of this argument may be used in the |
e511ffb6 | 90 | .BR va_start () |
fea681da MK |
91 | macro, it should not be declared as a register variable, |
92 | or as a function or an array type. | |
dded5e0c | 93 | .SS va_arg() |
fea681da | 94 | The |
e511ffb6 | 95 | .BR va_arg () |
fea681da | 96 | macro expands to an expression that has the type and value of the next |
c13182ef | 97 | argument in the call. |
c4bb193f | 98 | The argument |
fea681da | 99 | .I ap |
c13182ef | 100 | is the |
f19a0f03 | 101 | .I va_list |
fea681da MK |
102 | .I ap |
103 | initialized by | |
e511ffb6 | 104 | .BR va_start (). |
fea681da | 105 | Each call to |
e511ffb6 | 106 | .BR va_arg () |
fea681da MK |
107 | modifies |
108 | .I ap | |
c13182ef | 109 | so that the next call returns the next argument. |
c4bb193f | 110 | The argument |
fea681da MK |
111 | .I type |
112 | is a type name specified so that the type of a pointer to an object that | |
113 | has the specified type can be obtained simply by adding a * to | |
114 | .IR type . | |
115 | .PP | |
116 | The first use of the | |
e511ffb6 | 117 | .BR va_arg () |
c13182ef | 118 | macro after that of the |
e511ffb6 | 119 | .BR va_start () |
c13182ef | 120 | macro returns the argument after |
fea681da MK |
121 | .IR last . |
122 | Successive invocations return the values of the remaining arguments. | |
123 | .PP | |
124 | If there is no next argument, or if | |
125 | .I type | |
126 | is not compatible with the type of the actual next argument (as promoted | |
127 | according to the default argument promotions), random errors will occur. | |
128 | .PP | |
129 | If | |
130 | .I ap | |
131 | is passed to a function that uses | |
9a9ca538 | 132 | .BI va_arg( ap , type ), |
fea681da MK |
133 | then the value of |
134 | .I ap | |
135 | is undefined after the return of that function. | |
dded5e0c | 136 | .SS va_end() |
fea681da | 137 | Each invocation of |
e511ffb6 | 138 | .BR va_start () |
fea681da | 139 | must be matched by a corresponding invocation of |
e511ffb6 | 140 | .BR va_end () |
c13182ef MK |
141 | in the same function. |
142 | After the call | |
fea681da MK |
143 | .BI va_end( ap ) |
144 | the variable | |
145 | .I ap | |
c13182ef | 146 | is undefined. |
eb1af896 | 147 | Multiple traversals of the list, each |
fea681da | 148 | bracketed by |
e511ffb6 | 149 | .BR va_start () |
fea681da | 150 | and |
e511ffb6 | 151 | .BR va_end () |
fea681da | 152 | are possible. |
e511ffb6 | 153 | .BR va_end () |
fea681da | 154 | may be a macro or a function. |
dded5e0c | 155 | .SS va_copy() |
03045452 MK |
156 | The |
157 | .BR va_copy () | |
158 | macro copies the (previously initialized) variable argument list | |
159 | .I src | |
160 | to | |
161 | .IR dest . | |
162 | The behavior is as if | |
163 | .BR va_start () | |
164 | were applied to | |
165 | .IR dest | |
166 | with the same | |
167 | .I last | |
168 | argument, followed by the same number of | |
169 | .BR va_arg () | |
170 | invocations that was used to reach the current state of | |
171 | .IR src . | |
847e0d88 | 172 | .PP |
fea681da MK |
173 | .\" Proposal from clive@demon.net, 1997-02-28 |
174 | An obvious implementation would have a | |
f19a0f03 | 175 | .I va_list |
27e59a1f | 176 | be a pointer to the stack frame of the variadic function. |
fea681da MK |
177 | In such a setup (by far the most common) there seems |
178 | nothing against an assignment | |
e646a1ba | 179 | .PP |
a6e2f128 | 180 | .in +4n |
e646a1ba | 181 | .EX |
a6e2f128 | 182 | va_list aq = ap; |
e646a1ba | 183 | .EE |
a6e2f128 | 184 | .in |
e646a1ba | 185 | .PP |
fea681da MK |
186 | Unfortunately, there are also systems that make it an |
187 | array of pointers (of length 1), and there one needs | |
e646a1ba | 188 | .PP |
a6e2f128 | 189 | .in +4n |
e646a1ba | 190 | .EX |
a6e2f128 MK |
191 | va_list aq; |
192 | *aq = *ap; | |
e646a1ba | 193 | .EE |
a6e2f128 | 194 | .in |
e646a1ba | 195 | .PP |
c4bb193f | 196 | Finally, on systems where arguments are passed in registers, |
fea681da | 197 | it may be necessary for |
e511ffb6 | 198 | .BR va_start () |
c4bb193f MK |
199 | to allocate memory, store the arguments there, and also |
200 | an indication of which argument is next, so that | |
e511ffb6 | 201 | .BR va_arg () |
c13182ef MK |
202 | can step through the list. |
203 | Now | |
e511ffb6 | 204 | .BR va_end () |
fea681da MK |
205 | can free the allocated memory again. |
206 | To accommodate this situation, C99 adds a macro | |
e511ffb6 | 207 | .BR va_copy (), |
fea681da | 208 | so that the above assignment can be replaced by |
e646a1ba | 209 | .PP |
a6e2f128 | 210 | .in +4n |
e646a1ba | 211 | .EX |
a6e2f128 MK |
212 | va_list aq; |
213 | va_copy(aq, ap); | |
f560fdd5 | 214 | \&... |
a6e2f128 | 215 | va_end(aq); |
e646a1ba | 216 | .EE |
a6e2f128 | 217 | .in |
e646a1ba | 218 | .PP |
fea681da | 219 | Each invocation of |
e511ffb6 | 220 | .BR va_copy () |
fea681da | 221 | must be matched by a corresponding invocation of |
e511ffb6 | 222 | .BR va_end () |
fea681da MK |
223 | in the same function. |
224 | Some systems that do not supply | |
e511ffb6 | 225 | .BR va_copy () |
fea681da MK |
226 | have |
227 | .B __va_copy | |
228 | instead, since that was the name used in the draft proposal. | |
0d7bdb2a | 229 | .SH ATTRIBUTES |
67a62d2a PH |
230 | For an explanation of the terms used in this section, see |
231 | .BR attributes (7). | |
232 | .TS | |
233 | allbox; | |
234 | lbw21 lb lb | |
235 | l l l. | |
236 | Interface Attribute Value | |
237 | T{ | |
0d7bdb2a | 238 | .BR va_start (), |
0d7bdb2a | 239 | .BR va_end (), |
0d7bdb2a | 240 | .BR va_copy () |
67a62d2a | 241 | T} Thread safety MT-Safe |
70f434d3 MS |
242 | T{ |
243 | .BR va_arg () | |
244 | T} Thread safety MT-Safe race:ap | |
67a62d2a | 245 | .TE |
47297adb | 246 | .SH CONFORMING TO |
fea681da | 247 | The |
e511ffb6 MK |
248 | .BR va_start (), |
249 | .BR va_arg (), | |
fea681da | 250 | and |
e511ffb6 | 251 | .BR va_end () |
68e1685c | 252 | macros conform to C89. |
fea681da | 253 | C99 defines the |
e511ffb6 | 254 | .BR va_copy () |
fea681da | 255 | macro. |
fea681da | 256 | .SH BUGS |
263a6208 | 257 | Unlike the historical |
fea681da MK |
258 | .B varargs |
259 | macros, the | |
260 | .B stdarg | |
261 | macros do not permit programmers to code a function with no fixed | |
c13182ef MK |
262 | arguments. |
263 | This problem generates work mainly when converting | |
fea681da MK |
264 | .B varargs |
265 | code to | |
266 | .B stdarg | |
267 | code, but it also creates difficulties for variadic functions that wish to | |
268 | pass all of their arguments on to a function that takes a | |
f19a0f03 | 269 | .I va_list |
fea681da MK |
270 | argument, such as |
271 | .BR vfprintf (3). | |
2b2581ee MK |
272 | .SH EXAMPLE |
273 | The function | |
274 | .I foo | |
275 | takes a string of format characters and prints out the argument associated | |
276 | with each format character based on the type. | |
a2b7a144 MK |
277 | .PP |
278 | .EX | |
2b2581ee MK |
279 | #include <stdio.h> |
280 | #include <stdarg.h> | |
281 | ||
282 | void | |
ad484960 MK |
283 | foo(char *fmt, ...) /* '...' is C syntax for a variadic function */ |
284 | ||
2b2581ee MK |
285 | { |
286 | va_list ap; | |
287 | int d; | |
288 | char c, *s; | |
289 | ||
290 | va_start(ap, fmt); | |
291 | while (*fmt) | |
d4949190 | 292 | switch (*fmt++) { |
f81fb444 | 293 | case \(aqs\(aq: /* string */ |
2b2581ee | 294 | s = va_arg(ap, char *); |
31a6818e | 295 | printf("string %s\en", s); |
2b2581ee | 296 | break; |
f81fb444 | 297 | case \(aqd\(aq: /* int */ |
2b2581ee | 298 | d = va_arg(ap, int); |
31a6818e | 299 | printf("int %d\en", d); |
2b2581ee | 300 | break; |
f81fb444 | 301 | case \(aqc\(aq: /* char */ |
2b2581ee MK |
302 | /* need a cast here since va_arg only |
303 | takes fully promoted types */ | |
304 | c = (char) va_arg(ap, int); | |
31a6818e | 305 | printf("char %c\en", c); |
2b2581ee MK |
306 | break; |
307 | } | |
308 | va_end(ap); | |
309 | } | |
a2b7a144 | 310 | .EE |