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