Merge from vendor branch BIND:
[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. 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    8.1 (Berkeley) 6/5/93
37 .\" $FreeBSD: src/share/man/man3/stdarg.3,v 1.4.2.5 2001/12/17 11:30:11 ru Exp $
38 .\" $DragonFly: src/share/man/man3/stdarg.3,v 1.2 2003/06/17 04:36:58 dillon Exp $
39 .\"
40 .Dd June 5, 1993
41 .Dt STDARG 3
42 .Os
43 .Sh NAME
44 .Nm stdarg
45 .Nd variable argument lists
46 .Sh SYNOPSIS
47 .In stdarg.h
48 .Ft void
49 .Fn va_start "va_list ap" last
50 .Ft type
51 .Fn va_arg "va_list ap" type
52 .Ft void
53 .Fn va_end "va_list ap"
54 .Sh DESCRIPTION
55 A function may be called with a varying number of arguments of varying
56 types.
57 The include file
58 .Aq Pa stdarg.h
59 declares a type
60 .Pq Em va_list
61 and defines three macros for stepping
62 through a list of arguments whose number and types are not known to
63 the called function.
64 .Pp
65 The called function must declare an object of type
66 .Em va_list
67 which is used by the macros
68 .Fn va_start ,
69 .Fn va_arg ,
70 and
71 .Fn va_end .
72 .Pp
73 The
74 .Fn va_start
75 macro initializes
76 .Fa ap
77 for subsequent use by
78 .Fn va_arg
79 and
80 .Fn va_end ,
81 and must be called first.
82 .Pp
83 The parameter
84 .Fa last
85 is the name of the last parameter before the variable argument list,
86 i.e. the last parameter of which the calling function knows the type.
87 .Pp
88 Because the address of this parameter is used in the
89 .Fn va_start
90 macro, it should not be declared as a register variable, or as a
91 function or an array type.
92 .Pp
93 The
94 .Fn va_start
95 macro returns no value.
96 .Pp
97 The
98 .Fn va_arg
99 macro expands to an expression that has the type and value of the next
100 argument in the call.
101 The parameter
102 .Fa ap
103 is the
104 .Em va_list Fa ap
105 initialized by
106 .Fn va_start .
107 Each call to
108 .Fn va_arg
109 modifies
110 .Fa ap
111 so that the next call returns the next argument.
112 The parameter
113 .Fa type
114 is a type name specified so that the type of a pointer to an
115 object that has the specified type can be obtained simply by
116 adding a *
117 to
118 .Fa type .
119 .Pp
120 If there is no next argument, or if
121 .Fa type
122 is not compatible with the type of the actual next argument
123 (as promoted according to the default argument promotions),
124 random errors will occur.
125 .Pp
126 The first use of the
127 .Fn va_arg
128 macro after that of the
129 .Fn va_start
130 macro returns the argument after
131 .Fa last .
132 Successive invocations return the values of the remaining
133 arguments.
134 .Pp
135 The
136 .Fn va_end
137 macro handles a normal return from the function whose variable argument
138 list was initialized by
139 .Fn va_start .
140 .Pp
141 The
142 .Fn va_end
143 macro returns no value.
144 .Sh EXAMPLES
145 The function
146 .Em foo
147 takes a string of format characters and prints out the argument
148 associated with each format character based on the type.
149 .Bd -literal -offset indent
150 void foo(char *fmt, ...)
151 {
152         va_list ap;
153         int d;
154         char c, *s;
155
156         va_start(ap, fmt);
157         while (*fmt)
158                 switch(*fmt++) {
159                 case 's':                       /* string */
160                         s = va_arg(ap, char *);
161                         printf("string %s\en", s);
162                         break;
163                 case 'd':                       /* int */
164                         d = va_arg(ap, int);
165                         printf("int %d\en", d);
166                         break;
167                 case 'c':                       /* char */
168                         /* Note: char is promoted to int. */
169                         c = va_arg(ap, int);
170                         printf("char %c\en", c);
171                         break;
172                 }
173         va_end(ap);
174 }
175 .Ed
176 .Sh STANDARDS
177 The
178 .Fn va_start ,
179 .Fn va_arg ,
180 and
181 .Fn va_end
182 macros conform to
183 .St -isoC .
184 .Sh COMPATIBILITY
185 These macros are
186 .Em not
187 compatible with the historic macros they replace.
188 A backward compatible version can be found in the include
189 file
190 .Aq Pa varargs.h .
191 .Sh BUGS
192 Unlike the
193 .Em varargs
194 macros, the
195 .Nm
196 macros do not permit programmers to
197 code a function with no fixed arguments.
198 This problem generates work mainly when converting
199 .Em varargs
200 code to
201 .Nm
202 code,
203 but it also creates difficulties for variadic functions that
204 wish to pass all of their arguments on to a function
205 that takes a
206 .Em va_list
207 argument, such as
208 .Xr vfprintf 3 .