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