1.\" $NetBSD: stdarg.3,v 1.21 2015/06/15 02:06:18 dholland 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. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)stdarg.3 8.1 (Berkeley) 6/5/93 35.\" 36.Dd June 14, 2015 37.Dt STDARG 3 38.Os 39.Sh NAME 40.Nm stdarg , 41.Nm va_arg , 42.Nm va_copy , 43.Nm va_end , 44.Nm va_start 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_end , 73and, optionally, 74.Fn va_copy . 75.Pp 76The 77.Fn va_start 78macro initializes 79.Fa ap 80for subsequent use by 81.Fn va_arg , 82.Fn va_copy 83and 84.Fn va_end , 85and must be called first. 86.Pp 87The parameter 88.Fa last 89is the name of the last parameter before the variable argument list, 90i.e. the last parameter of which the calling function knows the type. 91.Pp 92Because the address of this parameter is used in the 93.Fn va_start 94macro, it should not be declared as a register variable, or as a 95function or an array type. 96.Pp 97The 98.Fn va_start 99macro returns no value. 100.Pp 101The 102.Fn va_arg 103macro expands to an expression that has the type and value of the next 104argument in the call. 105The parameter 106.Fa ap 107is the 108.Em va_list Fa ap 109initialized by 110.Fn va_start . 111Each call to 112.Fn va_arg 113modifies 114.Fa ap 115so that the next call returns the next argument. 116The parameter 117.Fa type 118is a type name specified so that the type of a pointer to an 119object that has the specified type can be obtained simply by 120adding a * 121to 122.Fa type . 123.Pp 124If there is no next argument, or if 125.Fa type 126is not compatible with the type of the actual next argument 127(as promoted according to the default argument promotions), 128random errors will occur. 129.Pp 130If the type in question is one that gets promoted, the promoted type 131should be used as the argument to 132.Fn va_arg . 133The following describes which types are promoted (and to what): 134.Bl -dash -compact 135.It 136.Va short 137is promoted to 138.Va int 139.It 140.Va float 141is promoted to 142.Va double 143.It 144.Va char 145is promoted to 146.Va int 147.El 148.Pp 149The first use of the 150.Fn va_arg 151macro after that of the 152.Fn va_start 153macro returns the argument after 154.Fa last . 155Successive invocations return the values of the remaining 156arguments. 157.Pp 158The 159.Fn va_copy 160macro makes 161.Fa dest 162a copy of 163.Fa src 164as if the 165.Fn va_start 166macro had been applied to it followed by the same sequence of uses of the 167.Fn va_arg 168macro as had previously been used to reach the present state of 169.Fa src . 170.Pp 171The 172.Fn va_copy 173macro returns no value. 174.Pp 175The 176.Fn va_end 177macro handles a normal return from the function whose variable argument 178list was initialized by 179.Fn va_start 180or 181.Fn va_copy . 182.Pp 183The 184.Fn va_end 185macro returns no value. 186.Sh EXAMPLES 187The function 188.Fn foo 189takes a string of format characters and prints out the argument 190associated with each format character based on the type. 191.Bd -literal -offset indent 192void 193foo(char *fmt, ...) 194{ 195 va_list ap; 196 int d, c; 197 char *s; 198 double f; 199 200 va_start(ap, fmt); 201 while (*fmt) 202 switch (*fmt++) { 203 case 's': /* string */ 204 s = va_arg(ap, char *); 205 printf("string %s\en", s); 206 break; 207 case 'd': /* int */ 208 d = va_arg(ap, int); 209 printf("int %d\en", d); 210 break; 211 case 'c': /* char */ 212 c = va_arg(ap, int); /* promoted */ 213 printf("char %c\en", c); 214 break; 215 case 'f': /* float */ 216 f = va_arg(ap, double); /* promoted */ 217 printf("float %f\en", f); 218 } 219 va_end(ap); 220} 221.Ed 222.Sh COMPATIBILITY 223These macros are 224.Em not 225compatible with the historic 226.In varargs.h 227macros they replaced. 228Any remaining code using the pre-C89 229.In varargs.h 230interface should be updated. 231.Sh STANDARDS 232The 233.Fn va_start , 234.Fn va_arg , 235.Fn va_copy , 236and 237.Fn va_end 238macros conform to 239.St -isoC-99 . 240.Sh HISTORY 241The 242.Fn va_start , 243.Fn va_arg 244and 245.Fn va_end 246macros were introduced in 247.St -ansiC . 248The 249.Fn va_copy 250macro was introduced in 251.St -isoC-99 . 252.Sh BUGS 253Unlike the 254.Em varargs 255macros, the 256.Nm stdarg 257macros do not permit programmers to 258code a function with no fixed arguments. 259This problem generates work mainly when converting 260.Em varargs 261code to 262.Nm stdarg 263code, 264but it also creates difficulties for variadic functions that 265wish to pass all of their arguments on to a function 266that takes a 267.Em va_list 268argument, such as 269.Xr vfprintf 3 . 270