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