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-12-10 "" "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 ATTRIBUTES
 230 .SS Multithreading (see pthreads(7))
 231 The
 232 .BR va_start (),
 233 .BR va_arg (),
 234 .BR va_end (),
 235 and
 236 .BR va_copy ()
 237 macros are thread-safe.
 238 .SH CONFORMING TO
 239 The
 240 .BR va_start (),
 241 .BR va_arg (),
 242 and
 243 .BR va_end ()
 244 macros conform to C89.
 245 C99 defines the
 246 .BR va_copy ()
 247 macro.
 248 .SH NOTES
 249 These macros are
 250 .I not
 251 compatible with the historic macros they replace.
 252 A backward-compatible version can be found in the include file
 253 .IR <varargs.h> .
 254 .PP
 255 The historic setup is:
 256 .in +4n
 257 .nf
 258
 259 #include <varargs.h>
 260
 261 void
 262 foo(va_alist)
 263     va_dcl
 264 {
 265     va_list ap;
 266
 267     va_start(ap);
 268     while (...) {
 269         ...
 270         x = va_arg(ap, type);
 271         ...
 272     }
 273     va_end(ap);
 274 }
 275
 276 .fi
 277 .in
 278 On some systems,
 279 .I va_end
 280 contains a closing \(aq}\(aq matching a \(aq{\(aq in
 281 .IR va_start ,
 282 so that both macros must occur in the same function, and in a way
 283 that allows this.
 284 .SH BUGS
 285 Unlike the
 286 .B varargs
 287 macros, the
 288 .B stdarg
 289 macros do not permit programmers to code a function with no fixed
 290 arguments.
 291 This problem generates work mainly when converting
 292 .B varargs
 293 code to
 294 .B stdarg
 295 code, but it also creates difficulties for variadic functions that wish to
 296 pass all of their arguments on to a function that takes a
 297 .I va_list
 298 argument, such as
 299 .BR vfprintf (3).
 300 .SH EXAMPLE
 301 The function
 302 .I foo
 303 takes a string of format characters and prints out the argument associated
 304 with each format character based on the type.
 305 .nf
 306
 307 #include <stdio.h>
 308 #include <stdarg.h>
 309
 310 void
 311 foo(char *fmt, ...)
 312 {
 313     va_list ap;
 314     int d;
 315     char c, *s;
 316
 317     va_start(ap, fmt);
 318     while (*fmt)
 319         switch (*fmt++) {
 320         case \(aqs\(aq:              /* string */
 321             s = va_arg(ap, char *);
 322             printf("string %s\en", s);
 323             break;
 324         case \(aqd\(aq:              /* int */
 325             d = va_arg(ap, int);
 326             printf("int %d\en", d);
 327             break;
 328         case \(aqc\(aq:              /* char */
 329             /* need a cast here since va_arg only
 330                takes fully promoted types */
 331             c = (char) va_arg(ap, int);
 332             printf("char %c\en", c);
 333             break;
 334         }
 335     va_end(ap);
 336 }
 337 .fi