share/man/man3/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$
  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 four 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 initializes
  78 .Fa ap
  79 for subsequent use by
  80 .Fn va_arg ,
  81 .Fn va_copy ,
  82 and
  83 .Fn va_end ,
  84 and must be called first.
  85 .Pp
  86 The parameter
  87 .Fa last
  88 is the name of the last parameter before the variable argument list,
  89 i.e., the last parameter of which the calling function knows the type.
  90 .Pp
  91 Because the address of this parameter is used in the
  92 .Fn va_start
  93 macro, it should not be declared as a register variable, or as a
  94 function or an array type.
  95 .Pp
  96 The
  97 .Fn va_arg
  98 macro expands to an expression that has the type and value of the next
  99 argument in the call.
 100 The parameter
 101 .Fa ap
 102 is the
 103 .Em va_list Fa ap
 104 initialized by
 105 .Fn va_start
 106 or
 107 .Fn va_copy .
 108 Each call to
 109 .Fn va_arg
 110 modifies
 111 .Fa ap
 112 so that the next call returns the next argument.
 113 The parameter
 114 .Fa type
 115 is a type name specified so that the type of a pointer to an
 116 object that has the specified type can be obtained simply by
 117 adding a *
 118 to
 119 .Fa type .
 120 .Pp
 121 If there is no next argument, or if
 122 .Fa type
 123 is not compatible with the type of the actual next argument
 124 (as promoted according to the default argument promotions),
 125 random errors will occur.
 126 .Pp
 127 The first use of the
 128 .Fn va_arg
 129 macro after that of the
 130 .Fn va_start
 131 macro returns the argument after
 132 .Fa last .
 133 Successive invocations return the values of the remaining
 134 arguments.
 135 .Pp
 136 The
 137 .Fn va_copy
 138 macro copies a variable argument list, previously initialized by
 139 .Fn va_start ,
 140 from
 141 .Fa src
 142 to
 143 .Fa dest .
 144 The state is preserved such that it is equivalent to calling
 145 .Fn va_start
 146 with the same second argument used with
 147 .Fa src ,
 148 and calling
 149 .Fn va_arg
 150 the same number of times as called with
 151 .Fa src .
 152 .Pp
 153 The
 154 .Fn va_end
 155 macro cleans up any state associated with the variable argument list
 156 .Fa ap .
 157 .Pp
 158 Each invocation of
 159 .Fn va_start
 160 or
 161 .Fn va_copy
 162 must be paired with a corresponding invocation of
 163 .Fn va_end
 164 in the same function.
 165 .Sh RETURN VALUES
 166 The
 167 .Fn va_arg
 168 macro returns the value of the next argument.
 169 .Pp
 170 The
 171 .Fn va_start ,
 172 .Fn va_copy ,
 173 and
 174 .Fn va_end
 175 macros return no value.
 176 .Sh EXAMPLES
 177 The function
 178 .Em foo
 179 takes a string of format characters and prints out the argument
 180 associated with each format character based on the type.
 181 .Bd -literal -offset indent
 182 void foo(char *fmt, ...)
 183 {
 184         va_list ap;
 185         int d;
 186         char c, *s;
 187
 188         va_start(ap, fmt);
 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 .Ed
 208 .Sh COMPATIBILITY
 209 These macros are
 210 .Em not
 211 compatible with the historic macros they replace.
 212 A backward compatible version can be found in the include
 213 file
 214 .In varargs.h .
 215 .Sh STANDARDS
 216 The
 217 .Fn va_start ,
 218 .Fn va_arg ,
 219 .Fn va_copy ,
 220 and
 221 .Fn va_end
 222 macros conform to
 223 .St -isoC-99 .
 224 .Sh BUGS
 225 Unlike the
 226 .Em varargs
 227 macros, the
 228 .Nm
 229 macros do not permit programmers to
 230 code a function with no fixed arguments.
 231 This problem generates work mainly when converting
 232 .Em varargs
 233 code to
 234 .Nm
 235 code,
 236 but it also creates difficulties for variadic functions that
 237 wish to pass all of their arguments on to a function
 238 that takes a
 239 .Em va_list
 240 argument, such as
 241 .Xr vfprintf 3 .