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