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