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.\" %sccs.include.redist.man% 9.\" 10.\" @(#)stdarg.3 8.2 (Berkeley) 04/28/95 11.\" 12.Dd 13.Dt STDARG 3 14.Os 15.Sh NAME 16.Nm stdarg 17.Nd variable argument lists 18.Sh SYNOPSIS 19.Fd #include <stdarg.h> 20.Ft void 21.Fn va_start "va_list ap" last 22.Ft type 23.Fn va_arg "va_list ap" type 24.Ft void 25.Fn va_end "va_list ap" 26.Sh DESCRIPTION 27A function may be called with a varying number of arguments of varying 28types. 29The include file 30.Aq Pa stdarg.h 31declares a type 32.Pq Em va_list 33and defines three macros for stepping 34through a list of arguments whose number and types are not known to 35the called function. 36.Pp 37The called function must declare an object of type 38.Em va_list 39which is used by the macros 40.Fn va_start , 41.Fn va_arg , 42and 43.Fn va_end . 44.Pp 45The 46.Fn va_start 47macro initializes 48.Fa ap 49for subsequent use by 50.Fn va_arg 51and 52.Fn va_end , 53and must be called first. 54.Pp 55The parameter 56.Fa last 57is the name of the last parameter before the variable argument list, 58i.e. the last parameter of which the calling function knows the type. 59.Pp 60Because the address of this parameter is used in the 61.Fn va_start 62macro, it should not be declared as a register variable, or as a 63function or an array type. 64.Pp 65The 66.Fn va_start 67macro returns no value. 68.Pp 69The 70.Fn va_arg 71macro expands to an expression that has the type and value of the next 72argument in the call. 73The parameter 74.Fa ap 75is the 76.Em va_list Fa ap 77initialized by 78.Fn va_start . 79Each call to 80.Fn va_arg 81modifies 82.Fa ap 83so that the next call returns the next argument. 84The parameter 85.Fa type 86is a type name specified so that the type of a pointer to an 87object that has the specified type can be obtained simply by 88adding a * 89to 90.Fa type . 91.Pp 92If there is no next argument, or if 93.Fa type 94is not compatible with the type of the actual next argument 95(as promoted according to the default argument promotions), 96random errors will occur. 97.Pp 98The first use of the 99.Fn va_arg 100macro after that of the 101.Fn va_start 102macro returns the argument after 103.Fa last . 104Successive invocations return the values of the remaining 105arguments. 106.Pp 107The 108.Fn va_end 109macro handles a normal return from the function whose variable argument 110list was initialized by 111.Fn va_start . 112.Pp 113The 114.Fn va_end 115macro returns no value. 116.Sh EXAMPLES 117The function 118.Em foo 119takes a string of format characters and prints out the argument 120associated with each format character based on the type. 121.Bd -literal -offset indent 122void foo(char *fmt, ...) 123{ 124 va_list ap; 125 int d; 126 char c, *s; 127 128 va_start(ap, fmt); 129 while (*fmt) 130 switch (*fmt++) { 131 case 's': /* string */ 132 s = va_arg(ap, char *); 133 printf("string %s\en", s); 134 break; 135 case 'd': /* int */ 136 d = va_arg(ap, int); 137 printf("int %d\en", d); 138 break; 139 case 'c': /* char */ 140 c = va_arg(ap, char); 141 printf("char %c\en", c); 142 break; 143 } 144 va_end(ap); 145} 146.Ed 147.Sh STANDARDS 148The 149.Fn va_start , 150.Fn va_arg , 151and 152.Fn va_end 153macros conform to 154.St -ansiC . 155.Sh COMPATIBILITY 156These macros are 157.Em not 158compatible with the historic macros they replace. 159A backward compatible version can be found in the include 160file 161.Aq Pa varargs.h . 162.Sh BUGS 163Unlike the 164.Em varargs 165macros, the 166.Nm stdarg 167macros do not permit programmers to 168code a function with no fixed arguments. 169This problem generates work mainly when converting 170.Em varargs 171code to 172.Nm stdarg 173code, 174but it also creates difficulties for variadic functions that 175wish to pass all of their arguments on to a function 176that takes a 177.Em va_list 178argument, such as 179.Xr vfprintf 3 . 180