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$ 34.\" 35.Dd October 25, 2002 36.Dt STDARG 3 37.Os 38.Sh NAME 39.Nm stdarg 40.Nd variable argument lists 41.Sh SYNOPSIS 42.In stdarg.h 43.Ft void 44.Fn va_start "va_list ap" last 45.Ft type 46.Fn va_arg "va_list ap" type 47.Ft void 48.Fn va_copy "va_list dest" "va_list src" 49.Ft void 50.Fn va_end "va_list ap" 51.Sh DESCRIPTION 52A function may be called with a varying number of arguments of varying 53types. 54The include file 55.In stdarg.h 56declares a type 57.Pq Em va_list 58and defines four macros for stepping 59through a list of arguments whose number and types are not known to 60the called function. 61.Pp 62The called function must declare an object of type 63.Em va_list 64which is used by the macros 65.Fn va_start , 66.Fn va_arg , 67.Fn va_copy , 68and 69.Fn va_end . 70.Pp 71The 72.Fn va_start 73macro initializes 74.Fa ap 75for subsequent use by 76.Fn va_arg , 77.Fn va_copy , 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_arg 94macro expands to an expression that has the type and value of the next 95argument in the call. 96The parameter 97.Fa ap 98is the 99.Em va_list Fa ap 100initialized by 101.Fn va_start 102or 103.Fn va_copy . 104Each call to 105.Fn va_arg 106modifies 107.Fa ap 108so that the next call returns the next argument. 109The parameter 110.Fa type 111is a type name specified so that the type of a pointer to an 112object that has the specified type can be obtained simply by 113adding a * 114to 115.Fa type . 116.Pp 117If there is no next argument, or if 118.Fa type 119is not compatible with the type of the actual next argument 120(as promoted according to the default argument promotions), 121random errors will occur. 122.Pp 123The first use of the 124.Fn va_arg 125macro after that of the 126.Fn va_start 127macro returns the argument after 128.Fa last . 129Successive invocations return the values of the remaining 130arguments. 131.Pp 132The 133.Fn va_copy 134macro copies a variable argument list, previously initialized by 135.Fn va_start , 136from 137.Fa src 138to 139.Fa dest . 140The state is preserved such that it is equivalent to calling 141.Fn va_start 142with the same second argument used with 143.Fa src , 144and calling 145.Fn va_arg 146the same number of times as called with 147.Fa src . 148.Pp 149The 150.Fn va_end 151macro cleans up any state associated with the variable argument list 152.Fa ap . 153.Pp 154Each invocation of 155.Fn va_start 156or 157.Fn va_copy 158must be paired with a corresponding invocation of 159.Fn va_end 160in the same function. 161.Sh RETURN VALUES 162The 163.Fn va_arg 164macro returns the value of the next argument. 165.Pp 166The 167.Fn va_start , 168.Fn va_copy , 169and 170.Fn va_end 171macros return 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, *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 /* Note: char is promoted to int. */ 197 c = va_arg(ap, int); 198 printf("char %c\en", c); 199 break; 200 } 201 va_end(ap); 202} 203.Ed 204.Sh COMPATIBILITY 205These macros are 206.Em not 207compatible with the historic macros they replace. 208A backward compatible version can be found in the include 209file 210.In varargs.h . 211.Sh STANDARDS 212The 213.Fn va_start , 214.Fn va_arg , 215.Fn va_copy , 216and 217.Fn va_end 218macros conform to 219.St -isoC-99 . 220.Sh BUGS 221Unlike the 222.Em varargs 223macros, the 224.Nm 225macros do not permit programmers to 226code a function with no fixed arguments. 227This problem generates work mainly when converting 228.Em varargs 229code to 230.Nm 231code, 232but it also creates difficulties for variadic functions that 233wish to pass all of their arguments on to a function 234that takes a 235.Em va_list 236argument, such as 237.Xr vfprintf 3 . 238