Commit | Line | Data |
---|---|---|
ae59e04c | 1 | .\" Copyright (c) 1990, 1991 The Regents of the University of California. |
b9b35ab6 KB |
2 | .\" All rights reserved. |
3 | .\" | |
043368e6 KB |
4 | .\" This code is derived from software contributed to Berkeley by |
5 | .\" the American National Standards Committee X3, on Information | |
6 | .\" Processing Systems. | |
7 | .\" | |
b9b35ab6 KB |
8 | .\" %sccs.include.redist.man% |
9 | .\" | |
043368e6 | 10 | .\" @(#)stdarg.3 6.8 (Berkeley) %G% |
41a44cfa | 11 | .\" |
ae59e04c | 12 | .Dd |
e07c32e7 | 13 | .Dt STDARG 3 |
c2a8cfad | 14 | .Os |
ae59e04c | 15 | .Sh NAME |
e07c32e7 | 16 | .Nm stdarg |
ae59e04c CL |
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 | |
b9b35ab6 KB |
27 | A function may be called with a varying number of arguments of varying |
28 | types. | |
29 | The include file | |
ae59e04c CL |
30 | .Aq Pa stdarg.h |
31 | declares a type | |
32 | .Pq Em va_list | |
33 | and defines three macros for stepping | |
b9b35ab6 KB |
34 | through a list of arguments whose number and types are not known to |
35 | the called function. | |
ae59e04c | 36 | .Pp |
b9b35ab6 | 37 | The called function must declare an object of type |
ae59e04c | 38 | .Em va_list |
b9b35ab6 | 39 | which is used by the macros |
ae59e04c CL |
40 | .Fn va_start , |
41 | .Fn va_arg , | |
b9b35ab6 | 42 | and |
ae59e04c CL |
43 | .Fn va_end . |
44 | .Pp | |
b9b35ab6 | 45 | The |
ae59e04c | 46 | .Fn va_start |
b9b35ab6 | 47 | macro initializes |
ae59e04c | 48 | .Fa ap |
b9b35ab6 | 49 | for subsequent use by |
ae59e04c | 50 | .Fn va_arg |
b9b35ab6 | 51 | and |
ae59e04c | 52 | .Fn va_end , |
b9b35ab6 | 53 | and must be called first. |
ae59e04c | 54 | .Pp |
b9b35ab6 | 55 | The parameter |
ae59e04c | 56 | .Fa last |
b9b35ab6 KB |
57 | is the name of the last parameter before the variable argument list, |
58 | i.e. the last parameter of which the calling function knows the type. | |
ae59e04c | 59 | .Pp |
b9b35ab6 | 60 | Because the address of this parameter is used in the |
ae59e04c | 61 | .Fn va_start |
b9b35ab6 | 62 | macro, it should not be declared as a register variable, or as a |
ae59e04c CL |
63 | function or an array type. |
64 | .Pp | |
b9b35ab6 | 65 | The |
ae59e04c | 66 | .Fn va_start |
b9b35ab6 | 67 | macro returns no value. |
ae59e04c | 68 | .Pp |
b9b35ab6 | 69 | The |
ae59e04c | 70 | .Fn va_arg |
b9b35ab6 KB |
71 | macro expands to an expression that has the type and value of the next |
72 | argument in the call. | |
73 | The parameter | |
ae59e04c | 74 | .Fa ap |
b9b35ab6 | 75 | is the |
ae59e04c | 76 | .Em va_list Fa ap |
b9b35ab6 | 77 | initialized by |
ae59e04c | 78 | .Fn va_start . |
b9b35ab6 | 79 | Each call to |
ae59e04c | 80 | .Fn va_arg |
b9b35ab6 | 81 | modifies |
ae59e04c | 82 | .Fa ap |
b9b35ab6 KB |
83 | so that the next call returns the next argument. |
84 | The parameter | |
ae59e04c | 85 | .Fa type |
b9b35ab6 KB |
86 | is a type name specified so that the type of a pointer to an |
87 | object that has the specified type can be obtained simply by | |
ae59e04c | 88 | adding a * |
b9b35ab6 | 89 | to |
ae59e04c CL |
90 | .Fa type . |
91 | .Pp | |
b9b35ab6 | 92 | If there is no next argument, or if |
ae59e04c | 93 | .Fa type |
b9b35ab6 KB |
94 | is not compatible with the type of the actual next argument |
95 | (as promoted according to the default argument promotions), | |
96 | random errors will occur. | |
ae59e04c | 97 | .Pp |
b9b35ab6 | 98 | The first use of the |
ae59e04c | 99 | .Fn va_arg |
b9b35ab6 | 100 | macro after that of the |
ae59e04c | 101 | .Fn va_start |
b9b35ab6 | 102 | macro returns the argument after |
ae59e04c | 103 | .Fa last . |
b9b35ab6 KB |
104 | Successive invocations return the values of the remaining |
105 | arguments. | |
ae59e04c | 106 | .Pp |
b9b35ab6 | 107 | The |
ae59e04c | 108 | .Fn va_end |
b9b35ab6 KB |
109 | macro handles a normal return from the function whose variable argument |
110 | list was initialized by | |
ae59e04c CL |
111 | .Fn va_start . |
112 | .Pp | |
b9b35ab6 | 113 | The |
ae59e04c | 114 | .Fn va_end |
b9b35ab6 | 115 | macro returns no value. |
ae59e04c | 116 | .Sh EXAMPLES |
b9b35ab6 | 117 | The function |
ae59e04c | 118 | .Em foo |
b9b35ab6 KB |
119 | takes a string of format characters and prints out the argument |
120 | associated with each format character based on the type. | |
ae59e04c | 121 | .Bd -literal -offset indent |
c2a8cfad | 122 | void foo(char *fmt, ...) |
b9b35ab6 KB |
123 | { |
124 | va_list ap; | |
125 | int d; | |
126 | char c, *p, *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 | } | |
ae59e04c CL |
146 | .Ed |
147 | .Sh STANDARDS | |
148 | The | |
149 | .Fn va_start , | |
150 | .Fn va_arg , | |
151 | and | |
152 | .Fn va_end | |
153 | macros conform to | |
154 | .St -ansiC . | |
155 | .Sh COMPATIBILITY | |
156 | These macros are | |
157 | .Em not | |
158 | compatible with the historic macros they replace. | |
159 | A backward compatible version can be found in the include | |
160 | file | |
161 | .Aq Pa varargs.h . | |
c2a8cfad DS |
162 | .Sh BUGS |
163 | Unlike the | |
164 | .Em varargs | |
165 | macros, the | |
166 | .Nm stdarg | |
167 | macros do not permit programmers to | |
168 | code a function with no fixed arguments. | |
169 | This problem generates work mainly when converting | |
170 | .Em varargs | |
171 | code to | |
172 | .Nm stdarg | |
173 | code, | |
174 | but it also creates difficulties for variadic functions that | |
175 | wish to pass all of their arguments on to a function | |
176 | that takes a | |
177 | .Em va_list | |
178 | argument, such as | |
179 | .Xr vfprintf 3 . |