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  2001-10-14 "" "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 .\" Proposal from clive@demon.net, 1997-02-28
 157 An obvious implementation would have a
 158 .I va_list
 159 be a pointer to the stack frame of the variadic function.
 160 In such a setup (by far the most common) there seems
 161 nothing against an assignment
 162 .in +4n
 163 .nf
 164
 165 va_list aq = ap;
 166
 167 .fi
 168 .in
 169 Unfortunately, there are also systems that make it an
 170 array of pointers (of length 1), and there one needs
 171 .in +4n
 172 .nf
 173
 174 va_list aq;
 175 *aq = *ap;
 176
 177 .fi
 178 .in
 179 Finally, on systems where arguments are passed in registers,
 180 it may be necessary for
 181 .BR va_start ()
 182 to allocate memory, store the arguments there, and also
 183 an indication of which argument is next, so that
 184 .BR va_arg ()
 185 can step through the list.
 186 Now
 187 .BR va_end ()
 188 can free the allocated memory again.
 189 To accommodate this situation, C99 adds a macro
 190 .BR va_copy (),
 191 so that the above assignment can be replaced by
 192 .in +4n
 193 .nf
 194
 195 va_list aq;
 196 va_copy(aq, ap);
 197 \&...
 198 va_end(aq);
 199
 200 .fi
 201 .in
 202 Each invocation of
 203 .BR va_copy ()
 204 must be matched by a corresponding invocation of
 205 .BR va_end ()
 206 in the same function.
 207 Some systems that do not supply
 208 .BR va_copy ()
 209 have
 210 .B __va_copy
 211 instead, since that was the name used in the draft proposal.
 212 .SH CONFORMING TO
 213 The
 214 .BR va_start (),
 215 .BR va_arg (),
 216 and
 217 .BR va_end ()
 218 macros conform to C89.
 219 C99 defines the
 220 .BR va_copy ()
 221 macro.
 222 .SH NOTES
 223 These macros are
 224 .I not
 225 compatible with the historic macros they replace.
 226 A backward-compatible version can be found in the include file
 227 .IR <varargs.h> .
 228 .PP
 229 The historic setup is:
 230 .in +4n
 231 .nf
 232
 233 #include <varargs.h>
 234
 235 void
 236 foo(va_alist)
 237     va_dcl
 238 {
 239     va_list ap;
 240
 241     va_start(ap);
 242     while (...) {
 243         ...
 244         x = va_arg(ap, type);
 245         ...
 246     }
 247     va_end(ap);
 248 }
 249
 250 .fi
 251 .in
 252 On some systems,
 253 .I va_end
 254 contains a closing \(aq}\(aq matching a \(aq{\(aq in
 255 .IR va_start ,
 256 so that both macros must occur in the same function, and in a way
 257 that allows this.
 258 .SH BUGS
 259 Unlike the
 260 .B varargs
 261 macros, the
 262 .B stdarg
 263 macros do not permit programmers to code a function with no fixed
 264 arguments.
 265 This problem generates work mainly when converting
 266 .B varargs
 267 code to
 268 .B stdarg
 269 code, but it also creates difficulties for variadic functions that wish to
 270 pass all of their arguments on to a function that takes a
 271 .I va_list
 272 argument, such as
 273 .BR vfprintf (3).
 274 .SH EXAMPLE
 275 The function
 276 .I foo
 277 takes a string of format characters and prints out the argument associated
 278 with each format character based on the type.
 279 .nf
 280
 281 #include <stdio.h>
 282 #include <stdarg.h>
 283
 284 void
 285 foo(char *fmt, ...)
 286 {
 287     va_list ap;
 288     int d;
 289     char c, *s;
 290
 291     va_start(ap, fmt);
 292     while (*fmt)
 293         switch (*fmt++) {
 294         case \(aqs\(aq:              /* string */
 295             s = va_arg(ap, char *);
 296             printf("string %s\en", s);
 297             break;
 298         case \(aqd\(aq:              /* int */
 299             d = va_arg(ap, int);
 300             printf("int %d\en", d);
 301             break;
 302         case \(aqc\(aq:              /* char */
 303             /* need a cast here since va_arg only
 304                takes fully promoted types */
 305             c = (char) va_arg(ap, int);
 306             printf("char %c\en", c);
 307             break;
 308         }
 309     va_end(ap);
 310 }
 311 .fi