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