1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
<table class="head">
<tr>
<td class="head-ltitle">STDARG(3)</td>
<td class="head-vol">Library Functions Manual</td>
<td class="head-rtitle">STDARG(3)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">stdarg</code> — <span class="Nd">variable
argument lists</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
<<a class="In">stdarg.h</a>></code></p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">va_start</code>(<var class="Fa" style="white-space: nowrap;">va_list
ap</var>, <var class="Fa" style="white-space: nowrap;">last</var>);</p>
<p class="Pp"><var class="Ft">type</var>
<br/>
<code class="Fn">va_arg</code>(<var class="Fa" style="white-space: nowrap;">va_list
ap</var>, <var class="Fa" style="white-space: nowrap;">type</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">va_copy</code>(<var class="Fa" style="white-space: nowrap;">va_list
dest</var>, <var class="Fa" style="white-space: nowrap;">va_list
src</var>);</p>
<p class="Pp"><var class="Ft">void</var>
<br/>
<code class="Fn">va_end</code>(<var class="Fa" style="white-space: nowrap;">va_list
ap</var>);</p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">A function may be called with a varying number of arguments of
varying types. The include file
<code class="In"><<a class="In">stdarg.h</a>></code> declares a type
(<i class="Em">va_list</i>) and defines four macros for stepping through a
list of arguments whose number and types are not known to the called
function.</p>
<p class="Pp" id="va_start">The called function must declare an object of type
<i class="Em">va_list</i> which is used by the macros
<a class="permalink" href="#va_start"><code class="Fn">va_start</code></a>(),
<code class="Fn">va_arg</code>(), <code class="Fn">va_copy</code>(), and
<code class="Fn">va_end</code>().</p>
<p class="Pp" id="va_start~2">The
<a class="permalink" href="#va_start~2"><code class="Fn">va_start</code></a>()
macro initializes <var class="Fa">ap</var> for subsequent use by
<code class="Fn">va_arg</code>(), <code class="Fn">va_copy</code>(), and
<code class="Fn">va_end</code>(), and must be called first.</p>
<p class="Pp">The parameter <var class="Fa">last</var> is the name of the last
parameter before the variable argument list, i.e., the last parameter of
which the calling function knows the type.</p>
<p class="Pp" id="va_start~3">Because the address of this parameter is used in
the
<a class="permalink" href="#va_start~3"><code class="Fn">va_start</code></a>()
macro, it should not be declared as a register variable, or as a function or
an array type.</p>
<p class="Pp" id="va_arg">The
<a class="permalink" href="#va_arg"><code class="Fn">va_arg</code></a>()
macro expands to an expression that has the type and value of the next
argument in the call. The parameter <var class="Fa">ap</var> is the
<i class="Em">va_list</i> <var class="Fa">ap</var> initialized by
<code class="Fn">va_start</code>() or <code class="Fn">va_copy</code>().
Each call to <code class="Fn">va_arg</code>() modifies
<var class="Fa">ap</var> so that the next call returns the next argument.
The parameter <var class="Fa">type</var> is a type name specified so that
the type of a pointer to an object that has the specified type can be
obtained simply by adding a * to <var class="Fa">type</var>.</p>
<p class="Pp">If there is no next argument, or if <var class="Fa">type</var> is
not compatible with the type of the actual next argument (as promoted
according to the default argument promotions), random errors will occur.</p>
<p class="Pp" id="va_arg~2">The first use of the
<a class="permalink" href="#va_arg~2"><code class="Fn">va_arg</code></a>()
macro after that of the <code class="Fn">va_start</code>() macro returns the
argument after <var class="Fa">last</var>. Successive invocations return the
values of the remaining arguments.</p>
<p class="Pp" id="va_copy">The
<a class="permalink" href="#va_copy"><code class="Fn">va_copy</code></a>()
macro copies a variable argument list, previously initialized by
<code class="Fn">va_start</code>(), from <var class="Fa">src</var> to
<var class="Fa">dest</var>. The state is preserved such that it is
equivalent to calling <code class="Fn">va_start</code>() with the same
second argument used with <var class="Fa">src</var>, and calling
<code class="Fn">va_arg</code>() the same number of times as called with
<var class="Fa">src</var>.</p>
<p class="Pp" id="va_end">The
<a class="permalink" href="#va_end"><code class="Fn">va_end</code></a>()
macro cleans up any state associated with the variable argument list
<var class="Fa">ap</var>.</p>
<p class="Pp" id="va_start~4">Each invocation of
<a class="permalink" href="#va_start~4"><code class="Fn">va_start</code></a>()
or <code class="Fn">va_copy</code>() must be paired with a corresponding
invocation of <code class="Fn">va_end</code>() in the same function.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN
VALUES</a></h1>
<p class="Pp">The <code class="Fn">va_arg</code>() macro returns the value of
the next argument.</p>
<p class="Pp">The <code class="Fn">va_start</code>(),
<code class="Fn">va_copy</code>(), and <code class="Fn">va_end</code>()
macros return no value.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
<p class="Pp">The function
<a class="permalink" href="#foo"><i class="Em" id="foo">foo</i></a> takes a
string of format characters and prints out the argument associated with each
format character based on the type.</p>
<div class="Bd Pp Bd-indent Li">
<pre>void foo(char *fmt, ...)
{
va_list ap;
int d;
char c, *s;
va_start(ap, fmt);
while (*fmt)
switch(*fmt++) {
case 's': /* string */
s = va_arg(ap, char *);
printf("string %s\n", s);
break;
case 'd': /* int */
d = va_arg(ap, int);
printf("int %d\n", d);
break;
case 'c': /* char */
/* Note: char is promoted to int. */
c = va_arg(ap, int);
printf("char %c\n", c);
break;
}
va_end(ap);
}</pre>
</div>
</section>
<section class="Sh">
<h1 class="Sh" id="COMPATIBILITY"><a class="permalink" href="#COMPATIBILITY">COMPATIBILITY</a></h1>
<p class="Pp">These macros are
<a class="permalink" href="#not"><i class="Em" id="not">not</i></a>
compatible with the historic macros they replace.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="STANDARDS"><a class="permalink" href="#STANDARDS">STANDARDS</a></h1>
<p class="Pp">The <code class="Fn">va_start</code>(),
<code class="Fn">va_arg</code>(), <code class="Fn">va_copy</code>(), and
<code class="Fn">va_end</code>() macros conform to <span class="St">ISO/IEC
9899:1999 (“ISO C99”)</span>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Fn">va_start</code>(),
<code class="Fn">va_arg</code>() and <code class="Fn">va_end</code>() macros
were introduced in <span class="St">ANSI X3.159-1989
(“ANSI C89”)</span>. The
<code class="Fn">va_copy</code>() macro was introduced in
<span class="St">ISO/IEC 9899:1999
(“ISO C99”)</span>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
<p class="Pp">Unlike the <i class="Em">varargs</i> macros, the
<code class="Nm">stdarg</code> macros do not permit programmers to code a
function with no fixed arguments. This problem generates work mainly when
converting <i class="Em">varargs</i> code to <code class="Nm">stdarg</code>
code, but it also creates difficulties for variadic functions that wish to
pass all of their arguments on to a function that takes a
<i class="Em">va_list</i> argument, such as
<a class="Xr">vfprintf(3)</a>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">October 18, 2024</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
