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.\" 38.Dd June 5, 1993 39.Dt STDARG 3 40.Os 41.Sh NAME 42.Nm stdarg 43.Nd variable argument lists 44.Sh SYNOPSIS 45.Fd #include <stdarg.h> 46.Ft void 47.Fn va_start "va_list ap" last 48.Ft type 49.Fn va_arg "va_list ap" type 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.Aq Pa 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 , 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 77and 78.Fn va_end , 79and must be called first. 80.Pp 81The parameter 82.Fa last 83is the name of the last parameter before the variable argument list, 84i.e. the last parameter of which the calling function knows the type. 85.Pp 86Because the address of this parameter is used in the 87.Fn va_start 88macro, it should not be declared as a register variable, or as a 89function or an array type. 90.Pp 91The 92.Fn va_start 93macro returns no value. 94.Pp 95The 96.Fn va_arg 97macro expands to an expression that has the type and value of the next 98argument in the call. 99The parameter 100.Fa ap 101is the 102.Em va_list Fa ap 103initialized by 104.Fn va_start . 105Each call to 106.Fn va_arg 107modifies 108.Fa ap 109so that the next call returns the next argument. 110The parameter 111.Fa type 112is a type name specified so that the type of a pointer to an 113object that has the specified type can be obtained simply by 114adding a * 115to 116.Fa type . 117.Pp 118If there is no next argument, or if 119.Fa type 120is not compatible with the type of the actual next argument 121(as promoted according to the default argument promotions), 122random errors will occur. 123.Pp 124The first use of the 125.Fn va_arg 126macro after that of the 127.Fn va_start 128macro returns the argument after 129.Fa last . 130Successive invocations return the values of the remaining 131arguments. 132.Pp 133The 134.Fn va_end 135macro handles a normal return from the function whose variable argument 136list was initialized by 137.Fn va_start . 138.Pp 139The 140.Fn va_end 141macro returns no value. 142.Sh EXAMPLES 143The function 144.Em foo 145takes a string of format characters and prints out the argument 146associated with each format character based on the type. 147.Bd -literal -offset indent 148void foo(char *fmt, ...) 149{ 150 va_list ap; 151 int d; 152 char c, *p, *s; 153 154 va_start(ap, fmt); 155 while (*fmt) 156 switch(*fmt++) { 157 case 's': /* string */ 158 s = va_arg(ap, char *); 159 printf("string %s\en", s); 160 break; 161 case 'd': /* int */ 162 d = va_arg(ap, int); 163 printf("int %d\en", d); 164 break; 165 case 'c': /* char */ 166 c = va_arg(ap, char); 167 printf("char %c\en", c); 168 break; 169 } 170 va_end(ap); 171} 172.Ed 173.Sh STANDARDS 174The 175.Fn va_start , 176.Fn va_arg , 177and 178.Fn va_end 179macros conform to 180.St -ansiC . 181.Sh COMPATIBILITY 182These macros are 183.Em not 184compatible with the historic macros they replace. 185A backward compatible version can be found in the include 186file 187.Aq Pa varargs.h . 188.Sh BUGS 189Unlike the 190.Em varargs 191macros, the 192.Nm stdarg 193macros do not permit programmers to 194code a function with no fixed arguments. 195This problem generates work mainly when converting 196.Em varargs 197code to 198.Nm stdarg 199code, 200but it also creates difficulties for variadic functions that 201wish to pass all of their arguments on to a function 202that takes a 203.Em va_list 204argument, such as 205.Xr vfprintf 3 . 206