Debian Codegraph @

upstream/debian-trixie/man3/stdarg.3

raw
1 '\" t
2 .\" Copyright (c) 1990, 1991 The Regents of the University of California.
3 .\" All rights reserved.
4 .\"
5 .\" This code is derived from software contributed to Berkeley by
6 .\" the American National Standards Committee X3, on Information
7 .\" Processing Systems.
8 .\"
9 .\" SPDX-License-Identifier: BSD-4-Clause-UC
10 .\"
11 .\" @(#)stdarg.3 6.8 (Berkeley) 6/29/91
12 .\"
13 .\" Converted for Linux, Mon Nov 29 15:11:11 1993, [email protected]
14 .\" Additions, 2001-10-14, aeb
15 .\"
16 .TH stdarg 3 2024-06-15 "Linux man-pages 6.9.1"
17 .SH NAME
18 stdarg, va_start, va_arg, va_end, va_copy \- variable argument lists
19 .SH LIBRARY
20 Standard C library
21 .RI ( libc ", " \-lc )
22 .SH SYNOPSIS
23 .nf
24 .B #include <stdarg.h>
25 .P
26 .BI "void va_start(va_list " ap ", " last );
27 .IB type " va_arg(va_list " ap ", " type );
28 .BI "void va_end(va_list " ap );
29 .BI "void va_copy(va_list " dest ", va_list " src );
30 .fi
31 .SH DESCRIPTION
32 A function may be called with a varying number of arguments of varying
33 types.
34 The include file
35 .I <stdarg.h>
36 declares a type
37 .I va_list
38 and defines three macros for stepping through a list of arguments whose
39 number and types are not known to the called function.
40 .P
41 The called function must declare an object of type
42 .I va_list
43 which is used by the macros
44 .BR va_start (),
45 .BR va_arg (),
46 and
47 .BR va_end ().
48 .SS va_start()
49 The
50 .BR va_start ()
51 macro initializes
52 .I ap
53 for subsequent use by
54 .BR va_arg ()
55 and
56 .BR va_end (),
57 and must be called first.
58 .P
59 The argument
60 .I last
61 is the name of the last argument before the variable argument list, that is,
62 the last argument of which the calling function knows the type.
63 .P
64 Because the address of this argument may be used in the
65 .BR va_start ()
66 macro, it should not be declared as a register variable,
67 or as a function or an array type.
68 .SS va_arg()
69 The
70 .BR va_arg ()
71 macro expands to an expression that has the type and value of the next
72 argument in the call.
73 The argument
74 .I ap
75 is the
76 .I va_list
77 .I ap
78 initialized by
79 .BR va_start ().
80 Each call to
81 .BR va_arg ()
82 modifies
83 .I ap
84 so that the next call returns the next argument.
85 The argument
86 .I type
87 is a type name specified so that the type of a pointer to an object that
88 has the specified type can be obtained simply by adding a * to
89 .IR type .
90 .P
91 The first use of the
92 .BR va_arg ()
93 macro after that of the
94 .BR va_start ()
95 macro returns the argument after
96 .IR last .
97 Successive invocations return the values of the remaining arguments.
98 .P
99 If there is no next argument, or if
100 .I type
101 is not compatible with the type of the actual next argument (as promoted
102 according to the default argument promotions), random errors will occur.
103 .P
104 If
105 .I ap
106 is passed to a function that uses
107 .BI va_arg( ap , type ),
108 then the value of
109 .I ap
110 is undefined after the return of that function.
111 .SS va_end()
112 Each invocation of
113 .BR va_start ()
114 must be matched by a corresponding invocation of
115 .BR va_end ()
116 in the same function.
117 After the call
118 .BI va_end( ap )
119 the variable
120 .I ap
121 is undefined.
122 Multiple traversals of the list, each
123 bracketed by
124 .BR va_start ()
125 and
126 .BR va_end ()
127 are possible.
128 .BR va_end ()
129 may be a macro or a function.
130 .SS va_copy()
131 The
132 .BR va_copy ()
133 macro copies the (previously initialized) variable argument list
134 .I src
135 to
136 .IR dest .
137 The behavior is as if
138 .BR va_start ()
139 were applied to
140 .I dest
141 with the same
142 .I last
143 argument, followed by the same number of
144 .BR va_arg ()
145 invocations that was used to reach the current state of
146 .IR src .
147 .P
148 .\" Proposal from [email protected], 1997-02-28
149 An obvious implementation would have a
150 .I va_list
151 be a pointer to the stack frame of the variadic function.
152 In such a setup (by far the most common) there seems
153 nothing against an assignment
154 .P
155 .in +4n
156 .EX
157 va_list aq = ap;
158 .EE
159 .in
160 .P
161 Unfortunately, there are also systems that make it an
162 array of pointers (of length 1), and there one needs
163 .P
164 .in +4n
165 .EX
166 va_list aq;
167 *aq = *ap;
168 .EE
169 .in
170 .P
171 Finally, on systems where arguments are passed in registers,
172 it may be necessary for
173 .BR va_start ()
174 to allocate memory, store the arguments there, and also
175 an indication of which argument is next, so that
176 .BR va_arg ()
177 can step through the list.
178 Now
179 .BR va_end ()
180 can free the allocated memory again.
181 To accommodate this situation, C99 adds a macro
182 .BR va_copy (),
183 so that the above assignment can be replaced by
184 .P
185 .in +4n
186 .EX
187 va_list aq;
188 va_copy(aq, ap);
189 \&...
190 va_end(aq);
191 .EE
192 .in
193 .P
194 Each invocation of
195 .BR va_copy ()
196 must be matched by a corresponding invocation of
197 .BR va_end ()
198 in the same function.
199 Some systems that do not supply
200 .BR va_copy ()
201 have
202 .B __va_copy
203 instead, since that was the name used in the draft proposal.
204 .SH ATTRIBUTES
205 For an explanation of the terms used in this section, see
206 .BR attributes (7).
207 .TS
208 allbox;
209 lbx lb lb
210 l l l.
211 Interface Attribute Value
212 T{
213 .na
214 .nh
215 .BR va_start (),
216 .BR va_end (),
217 .BR va_copy ()
218 T} Thread safety MT-Safe
219 T{
220 .na
221 .nh
222 .BR va_arg ()
223 T} Thread safety MT-Safe race:ap
224 .TE
225 .SH STANDARDS
226 C11, POSIX.1-2008.
227 .SH HISTORY
228 .TP
229 .BR va_start ()
230 .TQ
231 .BR va_arg ()
232 .TQ
233 .BR va_end ()
234 C89, POSIX.1-2001.
235 .TP
236 .BR va_copy ()
237 C99, POSIX.1-2001.
238 .SH CAVEATS
239 Unlike the historical
240 .B varargs
241 macros, the
242 .B stdarg
243 macros do not permit programmers to code a function with no fixed
244 arguments.
245 This problem generates work mainly when converting
246 .B varargs
247 code to
248 .B stdarg
249 code, but it also creates difficulties for variadic functions that wish to
250 pass all of their arguments on to a function that takes a
251 .I va_list
252 argument, such as
253 .BR vfprintf (3).
254 .SH EXAMPLES
255 The function
256 .I foo
257 takes a string of format characters and prints out the argument associated
258 with each format character based on the type.
259 .P
260 .EX
261 #include <stdio.h>
262 #include <stdarg.h>
263 \&
264 void
265 foo(char *fmt, ...) /* \[aq]...\[aq] is C syntax for a variadic function */
266 \&
267 {
268 va_list ap;
269 int d;
270 char c;
271 char *s;
272 \&
273 va_start(ap, fmt);
274 while (*fmt)
275 switch (*fmt++) {
276 case \[aq]s\[aq]: /* string */
277 s = va_arg(ap, char *);
278 printf("string %s\[rs]n", s);
279 break;
280 case \[aq]d\[aq]: /* int */
281 d = va_arg(ap, int);
282 printf("int %d\[rs]n", d);
283 break;
284 case \[aq]c\[aq]: /* char */
285 /* need a cast here since va_arg only
286 takes fully promoted types */
287 c = (char) va_arg(ap, int);
288 printf("char %c\[rs]n", c);
289 break;
290 }
291 va_end(ap);
292 }
293 .EE
294 .SH SEE ALSO
295 .BR vprintf (3),
296 .BR vscanf (3),
297 .BR vsyslog (3)