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