1.\" $NetBSD: stdarg.3,v 1.10 2001/09/11 16:53:14 wiz Exp $ 2.\" 3.\" Copyright (c) 1990, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" the American National Standards Committee X3, on Information 8.\" Processing Systems. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the University of 21.\" California, Berkeley and its contributors. 22.\" 4. Neither the name of the University nor the names of its contributors 23.\" may be used to endorse or promote products derived from this software 24.\" without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 27.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 28.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 29.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 30.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 31.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 32.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 33.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 34.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 35.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 36.\" SUCH DAMAGE. 37.\" 38.\" @(#)stdarg.3 8.1 (Berkeley) 6/5/93 39.\" 40.Dd April 14, 2001 41.Dt STDARG 3 42.Os 43.Sh NAME 44.Nm stdarg , 45.Nm varargs , 46.Nm va_arg , 47.Nm va_copy , 48.Nm va_end , 49.Nm va_start 50.Nd variable argument lists 51.Sh SYNOPSIS 52.Fd #include <stdarg.h> 53.Ft void 54.Fn va_start "va_list ap" last 55.Ft type 56.Fn va_arg "va_list ap" type 57.Ft void 58.Fn va_copy "va_list dest" "va_list src" 59.Ft void 60.Fn va_end "va_list ap" 61.Sh DESCRIPTION 62A function may be called with a varying number of arguments of varying 63types. 64The include file 65.Aq Pa stdarg.h 66declares a type 67.Pq Em va_list 68and defines three macros for stepping 69through a list of arguments whose number and types are not known to 70the called function. 71.Pp 72The called function must declare an object of type 73.Em va_list 74which is used by the macros 75.Fn va_start , 76.Fn va_arg , 77.Fn va_end , 78and, optionally, 79.Fn va_copy . 80.Pp 81The 82.Fn va_start 83macro initializes 84.Fa ap 85for subsequent use by 86.Fn va_arg , 87.Fn va_copy 88and 89.Fn va_end , 90and must be called first. 91.Pp 92The parameter 93.Fa last 94is the name of the last parameter before the variable argument list, 95i.e. the last parameter of which the calling function knows the type. 96.Pp 97Because the address of this parameter is used in the 98.Fn va_start 99macro, it should not be declared as a register variable, or as a 100function or an array type. 101.Pp 102The 103.Fn va_start 104macro returns no value. 105.Pp 106The 107.Fn va_arg 108macro expands to an expression that has the type and value of the next 109argument in the call. 110The parameter 111.Fa ap 112is the 113.Em va_list Fa ap 114initialized by 115.Fn va_start . 116Each call to 117.Fn va_arg 118modifies 119.Fa ap 120so that the next call returns the next argument. 121The parameter 122.Fa type 123is a type name specified so that the type of a pointer to an 124object that has the specified type can be obtained simply by 125adding a * 126to 127.Fa type . 128.Pp 129If there is no next argument, or if 130.Fa type 131is not compatible with the type of the actual next argument 132(as promoted according to the default argument promotions), 133random errors will occur. 134.Pp 135The first use of the 136.Fn va_arg 137macro after that of the 138.Fn va_start 139macro returns the argument after 140.Fa last . 141Successive invocations return the values of the remaining 142arguments. 143.Pp 144The 145.Fn va_copy 146macro makes 147.Fa dest 148a copy of 149.Fa src 150as if the 151.Fn va_start 152macro had been applied to it followed by the same sequence of uses of the 153.Fn va_arg 154macro as had previously been used to reach the present state of 155.Fa src . 156.Pp 157The 158.Fn va_copy 159macro returns no value. 160.Pp 161The 162.Fn va_end 163macro handles a normal return from the function whose variable argument 164list was initialized by 165.Fn va_start 166or 167.Fn va_copy . 168.Pp 169The 170.Fn va_end 171macro returns no value. 172.Sh EXAMPLES 173The function 174.Em foo 175takes a string of format characters and prints out the argument 176associated with each format character based on the type. 177.Bd -literal -offset indent 178void foo(char *fmt, ...) 179{ 180 va_list ap; 181 int d; 182 char c, *p, *s; 183 184 va_start(ap, fmt); 185 while (*fmt) 186 switch (*fmt++) { 187 case 's': /* string */ 188 s = va_arg(ap, char *); 189 printf("string %s\en", s); 190 break; 191 case 'd': /* int */ 192 d = va_arg(ap, int); 193 printf("int %d\en", d); 194 break; 195 case 'c': /* char */ 196 c = va_arg(ap, char); 197 printf("char %c\en", c); 198 break; 199 } 200 va_end(ap); 201} 202.Ed 203.Sh STANDARDS 204The 205.Fn va_start , 206.Fn va_arg , 207.Fn va_copy , 208and 209.Fn va_end 210macros conform to 211.St -isoC99 . 212.Sh HISTORY 213The 214.Fn va_start , 215.Fn va_arg 216and 217.Fn va_end 218macros were introduced in 219.St -isoC90 . 220The 221.Fn va_copy 222macro was introduced in 223.St -isoC99 . 224.Sh COMPATIBILITY 225These macros are 226.Em not 227compatible with the historic macros they replace. 228A backward compatible version can be found in the include 229file 230.Aq Pa varargs.h . 231.Sh BUGS 232Unlike the 233.Em varargs 234macros, the 235.Nm stdarg 236macros do not permit programmers to 237code a function with no fixed arguments. 238This problem generates work mainly when converting 239.Em varargs 240code to 241.Nm stdarg 242code, 243but it also creates difficulties for variadic functions that 244wish to pass all of their arguments on to a function 245that takes a 246.Em va_list 247argument, such as 248.Xr vfprintf 3 . 249