xref: /dragonfly/share/man/man3/stdarg.3 (revision 2cd2d2b5) 
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
55A function may be called with a varying number of arguments of varying
56types.
57The include file
58.Aq Pa stdarg.h
59declares a type
60.Pq Em va_list
61and defines three macros for stepping
62through a list of arguments whose number and types are not known to
63the called function.
64.Pp
65The called function must declare an object of type
66.Em va_list
67which is used by the macros
68.Fn va_start ,
69.Fn va_arg ,
70and
71.Fn va_end .
72.Pp
73The
74.Fn va_start
75macro initializes
76.Fa ap
77for subsequent use by
78.Fn va_arg
79and
80.Fn va_end ,
81and must be called first.
82.Pp
83The parameter
84.Fa last
85is the name of the last parameter before the variable argument list,
86i.e. the last parameter of which the calling function knows the type.
87.Pp
88Because the address of this parameter is used in the
89.Fn va_start
90macro, it should not be declared as a register variable, or as a
91function or an array type.
92.Pp
93The
94.Fn va_start
95macro returns no value.
96.Pp
97The
98.Fn va_arg
99macro expands to an expression that has the type and value of the next
100argument in the call.
101The parameter
102.Fa ap
103is the
104.Em va_list Fa ap
105initialized by
106.Fn va_start .
107Each call to
108.Fn va_arg
109modifies
110.Fa ap
111so that the next call returns the next argument.
112The parameter
113.Fa type
114is a type name specified so that the type of a pointer to an
115object that has the specified type can be obtained simply by
116adding a *
117to
118.Fa type .
119.Pp
120If there is no next argument, or if
121.Fa type
122is not compatible with the type of the actual next argument
123(as promoted according to the default argument promotions),
124random errors will occur.
125.Pp
126The first use of the
127.Fn va_arg
128macro after that of the
129.Fn va_start
130macro returns the argument after
131.Fa last .
132Successive invocations return the values of the remaining
133arguments.
134.Pp
135The
136.Fn va_end
137macro handles a normal return from the function whose variable argument
138list was initialized by
139.Fn va_start .
140.Pp
141The
142.Fn va_end
143macro returns no value.
144.Sh EXAMPLES
145The function
146.Em foo
147takes a string of format characters and prints out the argument
148associated with each format character based on the type.
149.Bd -literal -offset indent
150void 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
177The
178.Fn va_start ,
179.Fn va_arg ,
180and
181.Fn va_end
182macros conform to
183.St -isoC .
184.Sh COMPATIBILITY
185These macros are
186.Em not
187compatible with the historic macros they replace.
188A backward compatible version can be found in the include
189file
190.Aq Pa varargs.h .
191.Sh BUGS
192Unlike the
193.Em varargs
194macros, the
195.Nm
196macros do not permit programmers to
197code a function with no fixed arguments.
198This problem generates work mainly when converting
199.Em varargs
200code to
201.Nm
202code,
203but it also creates difficulties for variadic functions that
204wish to pass all of their arguments on to a function
205that takes a
206.Em va_list
207argument, such as
208.Xr vfprintf 3 .
209