original/man3/stdarg.3

   1 .\" Copyright (c) 1990, 1991 The Regents of the University of California.
   2 .\" 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 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. All advertising materials mentioning features or use of this software
  18 .\"    must display the following acknowledgement:
  19 .\"     This product includes software developed by the University of
  20 .\"     California, Berkeley and its contributors.
  21 .\" 4. Neither the name of the University nor the names of its contributors
  22 .\"    may be used to endorse or promote products derived from this software
  23 .\"    without specific prior written permission.
  24 .\"
  25 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  28 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  35 .\" SUCH DAMAGE.
  36 .\" %%%LICENSE_END
  37 .\"
  38 .\"     @(#)stdarg.3    6.8 (Berkeley) 6/29/91
  39 .\"
  40 .\" Converted for Linux, Mon Nov 29 15:11:11 1993, faith@cs.unc.edu
  41 .\" Additions, 2001-10-14, aeb
  42 .\"
  43 .TH STDARG 3  2013-03-15 "" "Linux Programmer's Manual"
  44 .SH NAME
  45 stdarg, va_start, va_arg, va_end, va_copy \- variable argument lists
  46 .SH SYNOPSIS
  47 .B #include <stdarg.h>
  48 .sp
  49 .BI "void va_start(va_list " ap ", " last );
  50 .br
  51 .IB type " va_arg(va_list " ap ", " type );
  52 .br
  53 .BI "void va_end(va_list " ap );
  54 .br
  55 .BI "void va_copy(va_list " dest ", va_list " src );
  56 .SH DESCRIPTION
  57 A function may be called with a varying number of arguments of varying
  58 types.
  59 The include file
  60 .I <stdarg.h>
  61 declares a type
  62 .I va_list
  63 and defines three macros for stepping through a list of arguments whose
  64 number and types are not known to the called function.
  65 .PP
  66 The called function must declare an object of type
  67 .I va_list
  68 which is used by the macros
  69 .BR va_start (),
  70 .BR va_arg (),
  71 and
  72 .BR va_end ().
  73 .SS va_start()
  74 The
  75 .BR va_start ()
  76 macro initializes
  77 .I ap
  78 for subsequent use by
  79 .BR va_arg ()
  80 and
  81 .BR va_end (),
  82 and must be called first.
  83 .PP
  84 The argument
  85 .I last
  86 is the name of the last argument before the variable argument list, that is,
  87 the last argument of which the calling function knows the type.
  88 .PP
  89 Because the address of this argument may be used in the
  90 .BR va_start ()
  91 macro, it should not be declared as a register variable,
  92 or as a function or an array type.
  93 .SS va_arg()
  94 The
  95 .BR va_arg ()
  96 macro expands to an expression that has the type and value of the next
  97 argument in the call.
  98 The argument
  99 .I ap
 100 is the
 101 .I va_list
 102 .I ap
 103 initialized by
 104 .BR va_start ().
 105 Each call to
 106 .BR va_arg ()
 107 modifies
 108 .I ap
 109 so that the next call returns the next argument.
 110 The argument
 111 .I type
 112 is a type name specified so that the type of a pointer to an object that
 113 has the specified type can be obtained simply by adding a * to
 114 .IR type .
 115 .PP
 116 The first use of the
 117 .BR va_arg ()
 118 macro after that of the
 119 .BR va_start ()
 120 macro returns the argument after
 121 .IR last .
 122 Successive invocations return the values of the remaining arguments.
 123 .PP
 124 If there is no next argument, or if
 125 .I type
 126 is not compatible with the type of the actual next argument (as promoted
 127 according to the default argument promotions), random errors will occur.
 128 .PP
 129 If
 130 .I ap
 131 is passed to a function that uses
 132 .BI va_arg( ap , type )
 133 then the value of
 134 .I ap
 135 is undefined after the return of that function.
 136 .SS va_end()
 137 Each invocation of
 138 .BR va_start ()
 139 must be matched by a corresponding invocation of
 140 .BR va_end ()
 141 in the same function.
 142 After the call
 143 .BI va_end( ap )
 144 the variable
 145 .I ap
 146 is undefined.
 147 Multiple traversals of the list, each
 148 bracketed by
 149 .BR va_start ()
 150 and
 151 .BR va_end ()
 152 are possible.
 153 .BR va_end ()
 154 may be a macro or a function.
 155 .SS va_copy()
 156 The
 157 .BR va_copy ()
 158 macro copies the (previously initialized) variable argument list
 159 .I src
 160 to
 161 .IR dest .
 162 The behavior is as if
 163 .BR va_start ()
 164 were applied to
 165 .IR dest
 166 with the same
 167 .I last
 168 argument, followed by the same number of
 169 .BR va_arg ()
 170 invocations that was used to reach the current state of
 171 .IR src .
 172
 173 .\" Proposal from clive@demon.net, 1997-02-28
 174 An obvious implementation would have a
 175 .I va_list
 176 be a pointer to the stack frame of the variadic function.
 177 In such a setup (by far the most common) there seems
 178 nothing against an assignment
 179 .in +4n
 180 .nf
 181
 182 va_list aq = ap;
 183
 184 .fi
 185 .in
 186 Unfortunately, there are also systems that make it an
 187 array of pointers (of length 1), and there one needs
 188 .in +4n
 189 .nf
 190
 191 va_list aq;
 192 *aq = *ap;
 193
 194 .fi
 195 .in
 196 Finally, on systems where arguments are passed in registers,
 197 it may be necessary for
 198 .BR va_start ()
 199 to allocate memory, store the arguments there, and also
 200 an indication of which argument is next, so that
 201 .BR va_arg ()
 202 can step through the list.
 203 Now
 204 .BR va_end ()
 205 can free the allocated memory again.
 206 To accommodate this situation, C99 adds a macro
 207 .BR va_copy (),
 208 so that the above assignment can be replaced by
 209 .in +4n
 210 .nf
 211
 212 va_list aq;
 213 va_copy(aq, ap);
 214 \&...
 215 va_end(aq);
 216
 217 .fi
 218 .in
 219 Each invocation of
 220 .BR va_copy ()
 221 must be matched by a corresponding invocation of
 222 .BR va_end ()
 223 in the same function.
 224 Some systems that do not supply
 225 .BR va_copy ()
 226 have
 227 .B __va_copy
 228 instead, since that was the name used in the draft proposal.
 229 .SH CONFORMING TO
 230 The
 231 .BR va_start (),
 232 .BR va_arg (),
 233 and
 234 .BR va_end ()
 235 macros conform to C89.
 236 C99 defines the
 237 .BR va_copy ()
 238 macro.
 239 .SH NOTES
 240 These macros are
 241 .I not
 242 compatible with the historic macros they replace.
 243 A backward-compatible version can be found in the include file
 244 .IR <varargs.h> .
 245 .PP
 246 The historic setup is:
 247 .in +4n
 248 .nf
 249
 250 #include <varargs.h>
 251
 252 void
 253 foo(va_alist)
 254     va_dcl
 255 {
 256     va_list ap;
 257
 258     va_start(ap);
 259     while (...) {
 260         ...
 261         x = va_arg(ap, type);
 262         ...
 263     }
 264     va_end(ap);
 265 }
 266
 267 .fi
 268 .in
 269 On some systems,
 270 .I va_end
 271 contains a closing \(aq}\(aq matching a \(aq{\(aq in
 272 .IR va_start ,
 273 so that both macros must occur in the same function, and in a way
 274 that allows this.
 275 .SH BUGS
 276 Unlike the
 277 .B varargs
 278 macros, the
 279 .B stdarg
 280 macros do not permit programmers to code a function with no fixed
 281 arguments.
 282 This problem generates work mainly when converting
 283 .B varargs
 284 code to
 285 .B stdarg
 286 code, but it also creates difficulties for variadic functions that wish to
 287 pass all of their arguments on to a function that takes a
 288 .I va_list
 289 argument, such as
 290 .BR vfprintf (3).
 291 .SH EXAMPLE
 292 The function
 293 .I foo
 294 takes a string of format characters and prints out the argument associated
 295 with each format character based on the type.
 296 .nf
 297
 298 #include <stdio.h>
 299 #include <stdarg.h>
 300
 301 void
 302 foo(char *fmt, ...)
 303 {
 304     va_list ap;
 305     int d;
 306     char c, *s;
 307
 308     va_start(ap, fmt);
 309     while (*fmt)
 310         switch (*fmt++) {
 311         case \(aqs\(aq:              /* string */
 312             s = va_arg(ap, char *);
 313             printf("string %s\en", s);
 314             break;
 315         case \(aqd\(aq:              /* int */
 316             d = va_arg(ap, int);
 317             printf("int %d\en", d);
 318             break;
 319         case \(aqc\(aq:              /* char */
 320             /* need a cast here since va_arg only
 321                takes fully promoted types */
 322             c = (char) va_arg(ap, int);
 323             printf("char %c\en", c);
 324             break;
 325         }
 326     va_end(ap);
 327 }
 328 .fi