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