man/FreeBSD/stdarg.3

   1 .\" Copyright (c) 1990, 1991, 1993
   2 .\"     The Regents of the University of California.  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    8.1 (Berkeley) 6/5/93
  37 .\" $FreeBSD: src/share/man/man3/stdarg.3,v 1.15 2005/01/21 08:36:36 ru Exp $
  38 .\"
  39 .Dd October 25, 2002
  40 .Dt STDARG 3
  41 .Os
  42 .Sh NAME
  43 .Nm stdarg
  44 .Nd variable argument lists
  45 .Sh SYNOPSIS
  46 .In stdarg.h
  47 .Ft void
  48 .Fn va_start "va_list ap" last
  49 .Ft type
  50 .Fn va_arg "va_list ap" type
  51 .Ft void
  52 .Fn va_copy "va_list dest" "va_list src"
  53 .Ft void
  54 .Fn va_end "va_list ap"
  55 .Sh DESCRIPTION
  56 A function may be called with a varying number of arguments of varying
  57 types.
  58 The include file
  59 .In stdarg.h
  60 declares a type
  61 .Pq Em va_list
  62 and defines three macros for stepping
  63 through a list of arguments whose number and types are not known to
  64 the called function.
  65 .Pp
  66 The called function must declare an object of type
  67 .Em va_list
  68 which is used by the macros
  69 .Fn va_start ,
  70 .Fn va_arg ,
  71 .Fn va_copy ,
  72 and
  73 .Fn va_end .
  74 .Pp
  75 The
  76 .Fn va_start
  77 macro must be called first, and it initializes
  78 .Fa ap ,
  79 which can be passed to
  80 .Fn va_arg
  81 for each argument to be processed.
  82 Calling
  83 .Fn va_end
  84 signals that there are no further arguments, and causes
  85 .Fa ap
  86 to be invalidated.
  87 Note that each call to
  88 .Fn va_start
  89 must be matched by a call to
  90 .Fn va_end ,
  91 from within the same function.
  92 .Pp
  93 The parameter
  94 .Fa last
  95 is the name of the last parameter before the variable argument list,
  96 i.e., the last parameter of which the calling function knows the type.
  97 .Pp
  98 Because the address of this parameter is used in the
  99 .Fn va_start
 100 macro, it should not be declared as a register variable, or as a
 101 function or an array type.
 102 .Pp
 103 The
 104 .Fn va_arg
 105 macro expands to an expression that has the type and value of the next
 106 argument in the call.
 107 The parameter
 108 .Fa ap
 109 is the
 110 .Em va_list Fa ap
 111 initialized by
 112 .Fn va_start .
 113 Each call to
 114 .Fn va_arg
 115 modifies
 116 .Fa ap
 117 so that the next call returns the next argument.
 118 The parameter
 119 .Fa type
 120 is a type name specified so that the type of a pointer to an
 121 object that has the specified type can be obtained simply by
 122 adding a *
 123 to
 124 .Fa type .
 125 .Pp
 126 If there is no next argument, or if
 127 .Fa type
 128 is not compatible with the type of the actual next argument
 129 (as promoted according to the default argument promotions),
 130 random errors will occur.
 131 .Pp
 132 The first use of the
 133 .Fn va_arg
 134 macro after that of the
 135 .Fn va_start
 136 macro returns the argument after
 137 .Fa last .
 138 Successive invocations return the values of the remaining
 139 arguments.
 140 .Pp
 141 The
 142 .Fn va_copy
 143 macro copies the state of the variable argument list,
 144 .Fa src ,
 145 previously initialized by
 146 .Fn va_start ,
 147 to the variable argument list,
 148 .Fa dest ,
 149 which must not have been previously initialized by
 150 .Fn va_start ,
 151 without an intervening call to
 152 .Fn va_end .
 153 The state preserved in
 154 .Fa dest
 155 is equivalent to calling
 156 .Fn va_start
 157 and
 158 .Fn va_arg
 159 on
 160 .Fa dest
 161 in the same way as was used on
 162 .Fa src .
 163 The copied variable argument list can subsequently be passed to
 164 .Fn va_arg ,
 165 and must finally be passed to
 166 .Fn va_end
 167 when through with it.
 168 .Pp
 169 After a variable argument list is invalidated by
 170 .Fn va_end ,
 171 it can be reinitialized with
 172 .Fn va_start
 173 or made a copy of another variable argument list with
 174 .Fn va_copy .
 175 .Sh EXAMPLES
 176 The function
 177 .Em foo
 178 takes a string of format characters and prints out the argument
 179 associated with each format character based on the type.
 180 .Bd -literal -offset indent
 181 void foo(char *fmt, ...)
 182 {
 183         va_list ap, ap2;
 184         int d;
 185         char c, *s;
 186
 187         va_start(ap, fmt);
 188         va_copy(ap2, ap);
 189         while (*fmt)
 190                 switch(*fmt++) {
 191                 case 's':                       /* string */
 192                         s = va_arg(ap, char *);
 193                         printf("string %s\en", s);
 194                         break;
 195                 case 'd':                       /* int */
 196                         d = va_arg(ap, int);
 197                         printf("int %d\en", d);
 198                         break;
 199                 case 'c':                       /* char */
 200                         /* Note: char is promoted to int. */
 201                         c = va_arg(ap, int);
 202                         printf("char %c\en", c);
 203                         break;
 204                 }
 205         va_end(ap);
 206         ...
 207         /* use ap2 to iterate over the arguments again */
 208         ...
 209         va_end(ap2);
 210 }
 211 .Ed
 212 .Sh COMPATIBILITY
 213 These macros are
 214 .Em not
 215 compatible with the historic macros they replace.
 216 A backward compatible version can be found in the include
 217 file
 218 .In varargs.h .
 219 .Sh STANDARDS
 220 The
 221 .Fn va_start ,
 222 .Fn va_arg ,
 223 .Fn va_copy ,
 224 and
 225 .Fn va_end
 226 macros conform to
 227 .St -isoC-99 .
 228 .Sh BUGS
 229 Unlike the
 230 .Em varargs
 231 macros, the
 232 .Nm
 233 macros do not permit programmers to
 234 code a function with no fixed arguments.
 235 This problem generates work mainly when converting
 236 .Em varargs
 237 code to
 238 .Nm
 239 code,
 240 but it also creates difficulties for variadic functions that
 241 wish to pass all of their arguments on to a function
 242 that takes a
 243 .Em va_list
 244 argument, such as
 245 .Xr vfprintf 3 .