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. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)stdarg.3 8.1 (Berkeley) 6/5/93 33.\" $FreeBSD: src/share/man/man3/stdarg.3,v 1.15 2005/01/21 08:36:36 ru Exp $ 34.\" $DragonFly: src/share/man/man3/stdarg.3,v 1.3 2005/11/20 11:05:44 swildner Exp $ 35.\" 36.Dd October 25, 2002 37.Dt STDARG 3 38.Os 39.Sh NAME 40.Nm stdarg 41.Nd variable argument lists 42.Sh SYNOPSIS 43.In stdarg.h 44.Ft void 45.Fn va_start "va_list ap" last 46.Ft type 47.Fn va_arg "va_list ap" type 48.Ft void 49.Fn va_copy "va_list dest" "va_list src" 50.Ft void 51.Fn va_end "va_list ap" 52.Sh DESCRIPTION 53A function may be called with a varying number of arguments of varying 54types. 55The include file 56.In stdarg.h 57declares a type 58.Pq Em va_list 59and defines three macros for stepping 60through a list of arguments whose number and types are not known to 61the called function. 62.Pp 63The called function must declare an object of type 64.Em va_list 65which is used by the macros 66.Fn va_start , 67.Fn va_arg , 68.Fn va_copy , 69and 70.Fn va_end . 71.Pp 72The 73.Fn va_start 74macro initializes 75.Fa ap 76for subsequent use by 77.Fn va_arg 78and 79.Fn va_end , 80and must be called first. 81.Pp 82The parameter 83.Fa last 84is the name of the last parameter before the variable argument list, 85i.e., the last parameter of which the calling function knows the type. 86.Pp 87Because the address of this parameter is used in the 88.Fn va_start 89macro, it should not be declared as a register variable, or as a 90function or an array type. 91.Pp 92The 93.Fn va_start 94macro returns no value. 95.Pp 96The 97.Fn va_arg 98macro expands to an expression that has the type and value of the next 99argument in the call. 100The parameter 101.Fa ap 102is the 103.Em va_list Fa ap 104initialized by 105.Fn va_start . 106Each call to 107.Fn va_arg 108modifies 109.Fa ap 110so that the next call returns the next argument. 111The parameter 112.Fa type 113is a type name specified so that the type of a pointer to an 114object that has the specified type can be obtained simply by 115adding a * 116to 117.Fa type . 118.Pp 119If there is no next argument, or if 120.Fa type 121is not compatible with the type of the actual next argument 122(as promoted according to the default argument promotions), 123random errors will occur. 124.Pp 125The first use of the 126.Fn va_arg 127macro after that of the 128.Fn va_start 129macro returns the argument after 130.Fa last . 131Successive invocations return the values of the remaining 132arguments. 133.Pp 134The 135.Fn va_copy 136macro copies a variable argument list, previously initialized by 137.Fn va_start , 138from 139.Fa src 140to 141.Fa dest . 142The state is preserved such that it is equivalent to calling 143.Fn va_start 144with the same second argument used with 145.Fa src , 146and calling 147.Fn va_arg 148the same number of times as called with 149.Fa src . 150.Pp 151The 152.Fn va_copy 153macro returns no value. 154.Pp 155The 156.Fn va_end 157macro handles a normal return from the function whose variable argument 158list was initialized by 159.Fn va_start . 160.Pp 161The 162.Fn va_end 163macro returns no value. 164.Sh EXAMPLES 165The function 166.Em foo 167takes a string of format characters and prints out the argument 168associated with each format character based on the type. 169.Bd -literal -offset indent 170void foo(char *fmt, ...) 171{ 172 va_list ap; 173 int d; 174 char c, *s; 175 176 va_start(ap, fmt); 177 while (*fmt) 178 switch(*fmt++) { 179 case 's': /* string */ 180 s = va_arg(ap, char *); 181 printf("string %s\en", s); 182 break; 183 case 'd': /* int */ 184 d = va_arg(ap, int); 185 printf("int %d\en", d); 186 break; 187 case 'c': /* char */ 188 /* Note: char is promoted to int. */ 189 c = va_arg(ap, int); 190 printf("char %c\en", c); 191 break; 192 } 193 va_end(ap); 194} 195.Ed 196.Sh COMPATIBILITY 197These macros are 198.Em not 199compatible with the historic macros they replace. 200A backward compatible version can be found in the include 201file 202.In varargs.h . 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 -isoC-99 . 212.Sh BUGS 213Unlike the 214.Em varargs 215macros, the 216.Nm 217macros do not permit programmers to 218code a function with no fixed arguments. 219This problem generates work mainly when converting 220.Em varargs 221code to 222.Nm 223code, 224but it also creates difficulties for variadic functions that 225wish to pass all of their arguments on to a function 226that takes a 227.Em va_list 228argument, such as 229.Xr vfprintf 3 . 230