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  2021-03-22 "" "Linux Programmer's Manual"
  44 .SH NAME
  45 stdarg, va_start, va_arg, va_end, va_copy \- variable argument lists
  46 .SH SYNOPSIS
  47 .nf
  48 .B #include <stdarg.h>
  49 .PP
  50 .BI "void va_start(va_list " ap ", " last );
  51 .IB type " va_arg(va_list " ap ", " type );
  52 .BI "void va_end(va_list " ap );
  53 .BI "void va_copy(va_list " dest ", va_list " src );
  54 .fi
  55 .SH DESCRIPTION
  56 A function may be called with a varying number of arguments of varying
  57 types.
  58 The include file
  59 .I <stdarg.h>
  60 declares a type
  61 .I va_list
  62 and defines three macros for stepping through a list of arguments whose
  63 number and types are not known to the called function.
  64 .PP
  65 The called function must declare an object of type
  66 .I va_list
  67 which is used by the macros
  68 .BR va_start (),
  69 .BR va_arg (),
  70 and
  71 .BR va_end ().
  72 .SS va_start()
  73 The
  74 .BR va_start ()
  75 macro initializes
  76 .I ap
  77 for subsequent use by
  78 .BR va_arg ()
  79 and
  80 .BR va_end (),
  81 and must be called first.
  82 .PP
  83 The argument
  84 .I last
  85 is the name of the last argument before the variable argument list, that is,
  86 the last argument of which the calling function knows the type.
  87 .PP
  88 Because the address of this argument may be used in the
  89 .BR va_start ()
  90 macro, it should not be declared as a register variable,
  91 or as a function or an array type.
  92 .SS va_arg()
  93 The
  94 .BR va_arg ()
  95 macro expands to an expression that has the type and value of the next
  96 argument in the call.
  97 The argument
  98 .I ap
  99 is the
 100 .I va_list
 101 .I ap
 102 initialized by
 103 .BR va_start ().
 104 Each call to
 105 .BR va_arg ()
 106 modifies
 107 .I ap
 108 so that the next call returns the next argument.
 109 The argument
 110 .I type
 111 is a type name specified so that the type of a pointer to an object that
 112 has the specified type can be obtained simply by adding a * to
 113 .IR type .
 114 .PP
 115 The first use of the
 116 .BR va_arg ()
 117 macro after that of the
 118 .BR va_start ()
 119 macro returns the argument after
 120 .IR last .
 121 Successive invocations return the values of the remaining arguments.
 122 .PP
 123 If there is no next argument, or if
 124 .I type
 125 is not compatible with the type of the actual next argument (as promoted
 126 according to the default argument promotions), random errors will occur.
 127 .PP
 128 If
 129 .I ap
 130 is passed to a function that uses
 131 .BI va_arg( ap , type ),
 132 then the value of
 133 .I ap
 134 is undefined after the return of that function.
 135 .SS va_end()
 136 Each invocation of
 137 .BR va_start ()
 138 must be matched by a corresponding invocation of
 139 .BR va_end ()
 140 in the same function.
 141 After the call
 142 .BI va_end( ap )
 143 the variable
 144 .I ap
 145 is undefined.
 146 Multiple traversals of the list, each
 147 bracketed by
 148 .BR va_start ()
 149 and
 150 .BR va_end ()
 151 are possible.
 152 .BR va_end ()
 153 may be a macro or a function.
 154 .SS va_copy()
 155 The
 156 .BR va_copy ()
 157 macro copies the (previously initialized) variable argument list
 158 .I src
 159 to
 160 .IR dest .
 161 The behavior is as if
 162 .BR va_start ()
 163 were applied to
 164 .IR dest
 165 with the same
 166 .I last
 167 argument, followed by the same number of
 168 .BR va_arg ()
 169 invocations that was used to reach the current state of
 170 .IR src .
 171 .PP
 172 .\" Proposal from clive@demon.net, 1997-02-28
 173 An obvious implementation would have a
 174 .I va_list
 175 be a pointer to the stack frame of the variadic function.
 176 In such a setup (by far the most common) there seems
 177 nothing against an assignment
 178 .PP
 179 .in +4n
 180 .EX
 181 va_list aq = ap;
 182 .EE
 183 .in
 184 .PP
 185 Unfortunately, there are also systems that make it an
 186 array of pointers (of length 1), and there one needs
 187 .PP
 188 .in +4n
 189 .EX
 190 va_list aq;
 191 *aq = *ap;
 192 .EE
 193 .in
 194 .PP
 195 Finally, on systems where arguments are passed in registers,
 196 it may be necessary for
 197 .BR va_start ()
 198 to allocate memory, store the arguments there, and also
 199 an indication of which argument is next, so that
 200 .BR va_arg ()
 201 can step through the list.
 202 Now
 203 .BR va_end ()
 204 can free the allocated memory again.
 205 To accommodate this situation, C99 adds a macro
 206 .BR va_copy (),
 207 so that the above assignment can be replaced by
 208 .PP
 209 .in +4n
 210 .EX
 211 va_list aq;
 212 va_copy(aq, ap);
 213 \&...
 214 va_end(aq);
 215 .EE
 216 .in
 217 .PP
 218 Each invocation of
 219 .BR va_copy ()
 220 must be matched by a corresponding invocation of
 221 .BR va_end ()
 222 in the same function.
 223 Some systems that do not supply
 224 .BR va_copy ()
 225 have
 226 .B __va_copy
 227 instead, since that was the name used in the draft proposal.
 228 .SH ATTRIBUTES
 229 For an explanation of the terms used in this section, see
 230 .BR attributes (7).
 231 .ad l
 232 .nh
 233 .TS
 234 allbox;
 235 lbx lb lb
 236 l l l.
 237 Interface       Attribute       Value
 238 T{
 239 .BR va_start (),
 240 .BR va_end (),
 241 .BR va_copy ()
 242 T}      Thread safety   MT-Safe
 243 T{
 244 .BR va_arg ()
 245 T}      Thread safety   MT-Safe race:ap
 246 .TE
 247 .hy
 248 .ad
 249 .sp 1
 250 .SH CONFORMING TO
 251 The
 252 .BR va_start (),
 253 .BR va_arg (),
 254 and
 255 .BR va_end ()
 256 macros conform to C89.
 257 C99 defines the
 258 .BR va_copy ()
 259 macro.
 260 .SH BUGS
 261 Unlike the historical
 262 .B varargs
 263 macros, the
 264 .B stdarg
 265 macros do not permit programmers to code a function with no fixed
 266 arguments.
 267 This problem generates work mainly when converting
 268 .B varargs
 269 code to
 270 .B stdarg
 271 code, but it also creates difficulties for variadic functions that wish to
 272 pass all of their arguments on to a function that takes a
 273 .I va_list
 274 argument, such as
 275 .BR vfprintf (3).
 276 .SH EXAMPLES
 277 The function
 278 .I foo
 279 takes a string of format characters and prints out the argument associated
 280 with each format character based on the type.
 281 .PP
 282 .EX
 283 #include <stdio.h>
 284 #include <stdarg.h>
 285
 286 void
 287 foo(char *fmt, ...)   /* \(aq...\(aq is C syntax for a variadic function */
 288
 289 {
 290     va_list ap;
 291     int d;
 292     char c;
 293     char *s;
 294
 295     va_start(ap, fmt);
 296     while (*fmt)
 297         switch (*fmt++) {
 298         case \(aqs\(aq:              /* string */
 299             s = va_arg(ap, char *);
 300             printf("string %s\en", s);
 301             break;
 302         case \(aqd\(aq:              /* int */
 303             d = va_arg(ap, int);
 304             printf("int %d\en", d);
 305             break;
 306         case \(aqc\(aq:              /* char */
 307             /* need a cast here since va_arg only
 308                takes fully promoted types */
 309             c = (char) va_arg(ap, int);
 310             printf("char %c\en", c);
 311             break;
 312         }
 313     va_end(ap);
 314 }
 315 .EE
 316 .SH SEE ALSO
 317 .BR vprintf (3),
 318 .BR vscanf (3),
 319 .BR vsyslog (3)