man3/stdarg.3

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