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