nrelease: Define BUILDING_NRELEASE_DPORTS when building packages.
[dragonfly.git] / share / man / man3 / stdarg.3
1 .\" Copyright (c) 1990, 1991, 1993
2 .\"     The Regents of the University of California.  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. Neither the name of the University nor the names of its contributors
17 .\"    may be used to endorse or promote products derived from this software
18 .\"    without specific prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .\"     @(#)stdarg.3    8.1 (Berkeley) 6/5/93
33 .\" $FreeBSD: src/share/man/man3/stdarg.3,v 1.15 2005/01/21 08:36:36 ru Exp $
34 .\"
35 .Dd May 9, 2019
36 .Dt STDARG 3
37 .Os
38 .Sh NAME
39 .Nm stdarg
40 .Nd variable argument lists
41 .Sh SYNOPSIS
42 .In stdarg.h
43 .Ft void
44 .Fn va_start "va_list ap" last
45 .Ft type
46 .Fn va_arg "va_list ap" type
47 .Ft void
48 .Fn va_copy "va_list dest" "va_list src"
49 .Ft void
50 .Fn va_end "va_list ap"
51 .Sh DESCRIPTION
52 A function may be called with a varying number of arguments of varying
53 types.
54 The include file
55 .In stdarg.h
56 declares a type
57 .Pq Em va_list
58 and defines three macros for stepping
59 through a list of arguments whose number and types are not known to
60 the called function.
61 .Pp
62 The called function must declare an object of type
63 .Em va_list
64 which is used by the macros
65 .Fn va_start ,
66 .Fn va_arg ,
67 .Fn va_copy ,
68 and
69 .Fn va_end .
70 .Pp
71 The
72 .Fn va_start
73 macro initializes
74 .Fa ap
75 for subsequent use by
76 .Fn va_arg
77 and
78 .Fn va_end ,
79 and must be called first.
80 .Pp
81 The parameter
82 .Fa last
83 is the name of the last parameter before the variable argument list,
84 i.e., the last parameter of which the calling function knows the type.
85 .Pp
86 Because the address of this parameter is used in the
87 .Fn va_start
88 macro, it should not be declared as a register variable, or as a
89 function or an array type.
90 .Pp
91 The
92 .Fn va_start
93 macro returns no value.
94 .Pp
95 The
96 .Fn va_arg
97 macro expands to an expression that has the type and value of the next
98 argument in the call.
99 The parameter
100 .Fa ap
101 is the
102 .Em va_list Fa ap
103 initialized by
104 .Fn va_start .
105 Each call to
106 .Fn va_arg
107 modifies
108 .Fa ap
109 so that the next call returns the next argument.
110 The parameter
111 .Fa type
112 is a type name specified so that the type of a pointer to an
113 object that has the specified type can be obtained simply by
114 adding a *
115 to
116 .Fa type .
117 .Pp
118 If there is no next argument, or if
119 .Fa type
120 is not compatible with the type of the actual next argument
121 (as promoted according to the default argument promotions),
122 random errors will occur.
123 .Pp
124 The first use of the
125 .Fn va_arg
126 macro after that of the
127 .Fn va_start
128 macro returns the argument after
129 .Fa last .
130 Successive invocations return the values of the remaining
131 arguments.
132 .Pp
133 The
134 .Fn va_copy
135 macro copies a variable argument list, previously initialized by
136 .Fn va_start ,
137 from
138 .Fa src
139 to
140 .Fa dest .
141 The state is preserved such that it is equivalent to calling
142 .Fn va_start
143 with the same second argument used with
144 .Fa src ,
145 and calling
146 .Fn va_arg
147 the same number of times as called with
148 .Fa src .
149 .Pp
150 The
151 .Fn va_copy
152 macro returns no value.
153 .Pp
154 The
155 .Fn va_end
156 macro handles a normal return from the function whose variable argument
157 list was initialized by
158 .Fn va_start .
159 .Pp
160 The
161 .Fn va_end
162 macro returns no value.
163 .Sh EXAMPLES
164 The function
165 .Em foo
166 takes a string of format characters and prints out the argument
167 associated with each format character based on the type.
168 .Bd -literal -offset indent
169 void foo(char *fmt, ...)
170 {
171         va_list ap;
172         int d;
173         char c, *s;
174
175         va_start(ap, fmt);
176         while (*fmt)
177                 switch(*fmt++) {
178                 case 's':                       /* string */
179                         s = va_arg(ap, char *);
180                         printf("string %s\en", s);
181                         break;
182                 case 'd':                       /* int */
183                         d = va_arg(ap, int);
184                         printf("int %d\en", d);
185                         break;
186                 case 'c':                       /* char */
187                         /* Note: char is promoted to int. */
188                         c = va_arg(ap, int);
189                         printf("char %c\en", c);
190                         break;
191                 }
192         va_end(ap);
193 }
194 .Ed
195 .Sh COMPATIBILITY
196 These macros are
197 .Em not
198 compatible with the historic macros they replace.
199 .Sh STANDARDS
200 The
201 .Fn va_start ,
202 .Fn va_arg ,
203 .Fn va_copy ,
204 and
205 .Fn va_end
206 macros conform to
207 .St -isoC-99 .
208 .Sh BUGS
209 Unlike the
210 .Em varargs
211 macros, the
212 .Nm
213 macros do not permit programmers to
214 code a function with no fixed arguments.
215 This problem generates work mainly when converting
216 .Em varargs
217 code to
218 .Nm
219 code,
220 but it also creates difficulties for variadic functions that
221 wish to pass all of their arguments on to a function
222 that takes a
223 .Em va_list
224 argument, such as
225 .Xr vfprintf 3 .