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 .\" $FreeBSD: src/share/man/man3/stdarg.3,v 1.15 2005/01/21 08:36:36 ru Exp $
  34 .\"
  35 .Dd May 9, 2019
  36 .Dt STDARG 3
  37 .Os
  38 .Sh NAME
  39 .Nm stdarg
  40 .Nd variable argument lists
  41 .Sh SYNOPSIS
  42 .In stdarg.h
  43 .Ft void
  44 .Fn va_start "va_list ap" last
  45 .Ft type
  46 .Fn va_arg "va_list ap" type
  47 .Ft void
  48 .Fn va_copy "va_list dest" "va_list src"
  49 .Ft void
  50 .Fn va_end "va_list ap"
  51 .Sh DESCRIPTION
  52 A function may be called with a varying number of arguments of varying
  53 types.
  54 The include file
  55 .In stdarg.h
  56 declares a type
  57 .Pq Em va_list
  58 and defines three macros for stepping
  59 through a list of arguments whose number and types are not known to
  60 the called function.
  61 .Pp
  62 The called function must declare an object of type
  63 .Em va_list
  64 which is used by the macros
  65 .Fn va_start ,
  66 .Fn va_arg ,
  67 .Fn va_copy ,
  68 and
  69 .Fn va_end .
  70 .Pp
  71 The
  72 .Fn va_start
  73 macro initializes
  74 .Fa ap
  75 for subsequent use by
  76 .Fn va_arg
  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_start
  93 macro returns no value.
  94 .Pp
  95 The
  96 .Fn va_arg
  97 macro expands to an expression that has the type and value of the next
  98 argument in the call.
  99 The parameter
 100 .Fa ap
 101 is the
 102 .Em va_list Fa ap
 103 initialized by
 104 .Fn va_start .
 105 Each call to
 106 .Fn va_arg
 107 modifies
 108 .Fa ap
 109 so that the next call returns the next argument.
 110 The parameter
 111 .Fa type
 112 is a type name specified so that the type of a pointer to an
 113 object that has the specified type can be obtained simply by
 114 adding a *
 115 to
 116 .Fa type .
 117 .Pp
 118 If there is no next argument, or if
 119 .Fa type
 120 is not compatible with the type of the actual next argument
 121 (as promoted according to the default argument promotions),
 122 random errors will occur.
 123 .Pp
 124 The first use of the
 125 .Fn va_arg
 126 macro after that of the
 127 .Fn va_start
 128 macro returns the argument after
 129 .Fa last .
 130 Successive invocations return the values of the remaining
 131 arguments.
 132 .Pp
 133 The
 134 .Fn va_copy
 135 macro copies a variable argument list, previously initialized by
 136 .Fn va_start ,
 137 from
 138 .Fa src
 139 to
 140 .Fa dest .
 141 The state is preserved such that it is equivalent to calling
 142 .Fn va_start
 143 with the same second argument used with
 144 .Fa src ,
 145 and calling
 146 .Fn va_arg
 147 the same number of times as called with
 148 .Fa src .
 149 .Pp
 150 The
 151 .Fn va_copy
 152 macro returns no value.
 153 .Pp
 154 The
 155 .Fn va_end
 156 macro handles a normal return from the function whose variable argument
 157 list was initialized by
 158 .Fn va_start .
 159 .Pp
 160 The
 161 .Fn va_end
 162 macro returns no value.
 163 .Sh EXAMPLES
 164 The function
 165 .Em foo
 166 takes a string of format characters and prints out the argument
 167 associated with each format character based on the type.
 168 .Bd -literal -offset indent
 169 void foo(char *fmt, ...)
 170 {
 171         va_list ap;
 172         int d;
 173         char c, *s;
 174
 175         va_start(ap, fmt);
 176         while (*fmt)
 177                 switch(*fmt++) {
 178                 case 's':                       /* string */
 179                         s = va_arg(ap, char *);
 180                         printf("string %s\en", s);
 181                         break;
 182                 case 'd':                       /* int */
 183                         d = va_arg(ap, int);
 184                         printf("int %d\en", d);
 185                         break;
 186                 case 'c':                       /* char */
 187                         /* Note: char is promoted to int. */
 188                         c = va_arg(ap, int);
 189                         printf("char %c\en", c);
 190                         break;
 191                 }
 192         va_end(ap);
 193 }
 194 .Ed
 195 .Sh COMPATIBILITY
 196 These macros are
 197 .Em not
 198 compatible with the historic macros they replace.
 199 .Sh STANDARDS
 200 The
 201 .Fn va_start ,
 202 .Fn va_arg ,
 203 .Fn va_copy ,
 204 and
 205 .Fn va_end
 206 macros conform to
 207 .St -isoC-99 .
 208 .Sh BUGS
 209 Unlike the
 210 .Em varargs
 211 macros, the
 212 .Nm
 213 macros do not permit programmers to
 214 code a function with no fixed arguments.
 215 This problem generates work mainly when converting
 216 .Em varargs
 217 code to
 218 .Nm
 219 code,
 220 but it also creates difficulties for variadic functions that
 221 wish to pass all of their arguments on to a function
 222 that takes a
 223 .Em va_list
 224 argument, such as
 225 .Xr vfprintf 3 .