Debian Codegraph @

upstream/debian-unstable/man3/stdarg.3

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