share/man/man3/stdarg.3

   1 .\"     $NetBSD: stdarg.3,v 1.17 2003/08/07 10:31:01 agc Exp $
   2 .\"
   3 .\" Copyright (c) 1990, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" the American National Standards Committee X3, on Information
   8 .\" Processing Systems.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)stdarg.3    8.1 (Berkeley) 6/5/93
  35 .\"
  36 .Dd August 18, 2002
  37 .Dt STDARG 3
  38 .Os
  39 .Sh NAME
  40 .Nm stdarg ,
  41 .Nm va_arg  ,
  42 .Nm va_copy  ,
  43 .Nm va_end ,
  44 .Nm va_start
  45 .Nd variable argument lists
  46 .Sh SYNOPSIS
  47 .In stdarg.h
  48 .Ft void
  49 .Fn va_start "va_list ap" last
  50 .Ft type
  51 .Fn va_arg "va_list ap" type
  52 .Ft void
  53 .Fn va_copy "va_list dest" "va_list src"
  54 .Ft void
  55 .Fn va_end "va_list ap"
  56 .Sh DESCRIPTION
  57 A function may be called with a varying number of arguments of varying
  58 types.
  59 The include file
  60 .Aq Pa stdarg.h
  61 declares a type
  62 .Pq Em va_list
  63 and defines three macros for stepping
  64 through a list of arguments whose number and types are not known to
  65 the called function.
  66 .Pp
  67 The called function must declare an object of type
  68 .Em va_list
  69 which is used by the macros
  70 .Fn va_start ,
  71 .Fn va_arg ,
  72 .Fn va_end ,
  73 and, optionally,
  74 .Fn va_copy .
  75 .Pp
  76 The
  77 .Fn va_start
  78 macro initializes
  79 .Fa ap
  80 for subsequent use by
  81 .Fn va_arg ,
  82 .Fn va_copy
  83 and
  84 .Fn va_end ,
  85 and must be called first.
  86 .Pp
  87 The parameter
  88 .Fa last
  89 is the name of the last parameter before the variable argument list,
  90 i.e. the last parameter of which the calling function knows the type.
  91 .Pp
  92 Because the address of this parameter is used in the
  93 .Fn va_start
  94 macro, it should not be declared as a register variable, or as a
  95 function or an array type.
  96 .Pp
  97 The
  98 .Fn va_start
  99 macro returns no value.
 100 .Pp
 101 The
 102 .Fn va_arg
 103 macro expands to an expression that has the type and value of the next
 104 argument in the call.
 105 The parameter
 106 .Fa ap
 107 is the
 108 .Em va_list Fa ap
 109 initialized by
 110 .Fn va_start .
 111 Each call to
 112 .Fn va_arg
 113 modifies
 114 .Fa ap
 115 so that the next call returns the next argument.
 116 The parameter
 117 .Fa type
 118 is a type name specified so that the type of a pointer to an
 119 object that has the specified type can be obtained simply by
 120 adding a *
 121 to
 122 .Fa type .
 123 .Pp
 124 If there is no next argument, or if
 125 .Fa type
 126 is not compatible with the type of the actual next argument
 127 (as promoted according to the default argument promotions),
 128 random errors will occur.
 129 .Pp
 130 If the type in question is one that gets promoted, the promoted type
 131 should be used as the argument to
 132 .Fn va_arg .
 133 The following describes which types are promoted (and to what):
 134 .Bl -dash -compact
 135 .It
 136 .Va short
 137 is promoted to
 138 .Va int
 139 .It
 140 .Va float
 141 is promoted to
 142 .Va double
 143 .It
 144 .Va char
 145 is promoted to
 146 .Va int
 147 .El
 148 .Pp
 149 The first use of the
 150 .Fn va_arg
 151 macro after that of the
 152 .Fn va_start
 153 macro returns the argument after
 154 .Fa last .
 155 Successive invocations return the values of the remaining
 156 arguments.
 157 .Pp
 158 The
 159 .Fn va_copy
 160 macro makes
 161 .Fa dest
 162 a copy of
 163 .Fa src
 164 as if the
 165 .Fn va_start
 166 macro had been applied to it followed by the same sequence of uses of the
 167 .Fn va_arg
 168 macro as had previously been used to reach the present state of
 169 .Fa src .
 170 .Pp
 171 The
 172 .Fn va_copy
 173 macro returns no value.
 174 .Pp
 175 The
 176 .Fn va_end
 177 macro handles a normal return from the function whose variable argument
 178 list was initialized by
 179 .Fn va_start
 180 or
 181 .Fn va_copy .
 182 .Pp
 183 The
 184 .Fn va_end
 185 macro returns no value.
 186 .Sh EXAMPLES
 187 The function
 188 .Fn foo
 189 takes a string of format characters and prints out the argument
 190 associated with each format character based on the type.
 191 .Bd -literal -offset indent
 192 void
 193 foo(char *fmt, ...)
 194 {
 195         va_list ap;
 196         int d, c;
 197         char *s;
 198         double f;
 199
 200         va_start(ap, fmt);
 201         while (*fmt)
 202                 switch (*fmt++) {
 203                 case 's':                       /* string */
 204                         s = va_arg(ap, char *);
 205                         printf("string %s\en", s);
 206                         break;
 207                 case 'd':                       /* int */
 208                         d = va_arg(ap, int);
 209                         printf("int %d\en", d);
 210                         break;
 211                 case 'c':                       /* char */
 212                         c = va_arg(ap, int);    /* promoted */
 213                         printf("char %c\en", c);
 214                         break;
 215                 case 'f':                       /* float */
 216                         f = va_arg(ap, double); /* promoted */
 217                         printf("float %f\en", f);
 218                 }
 219         va_end(ap);
 220 }
 221 .Ed
 222 .Sh STANDARDS
 223 The
 224 .Fn va_start ,
 225 .Fn va_arg ,
 226 .Fn va_copy ,
 227 and
 228 .Fn va_end
 229 macros conform to
 230 .St -isoC-99 .
 231 .Sh HISTORY
 232 The
 233 .Fn va_start ,
 234 .Fn va_arg
 235 and
 236 .Fn va_end
 237 macros were introduced in
 238 .St -ansiC .
 239 The
 240 .Fn va_copy
 241 macro was introduced in
 242 .St -isoC-99 .
 243 .Sh COMPATIBILITY
 244 These macros are
 245 .Em not
 246 compatible with the historic macros they replace.
 247 A backward compatible version can be found in the include
 248 file
 249 .Aq Pa varargs.h .
 250 .Sh BUGS
 251 Unlike the
 252 .Em varargs
 253 macros, the
 254 .Nm stdarg
 255 macros do not permit programmers to
 256 code a function with no fixed arguments.
 257 This problem generates work mainly when converting
 258 .Em varargs
 259 code to
 260 .Nm stdarg
 261 code,
 262 but it also creates difficulties for variadic functions that
 263 wish to pass all of their arguments on to a function
 264 that takes a
 265 .Em va_list
 266 argument, such as
 267 .Xr vfprintf 3 .