man/FreeBSD/stdarg.3.patch

   1 --- stdarg.3.orig       2008-07-30 02:46:51.000000000 -0700
   2 +++ stdarg.3    2008-07-30 04:06:35.000000000 -0700
   3 @@ -74,13 +74,21 @@
   4  .Pp
   5  The
   6  .Fn va_start
   7 -macro initializes
   8 -.Fa ap
   9 -for subsequent use by
  10 +macro must be called first, and it initializes
  11 +.Fa ap ,
  12 +which can be passed to
  13  .Fn va_arg
  14 -and
  15 +for each argument to be processed.
  16 +Calling
  17 +.Fn va_end
  18 +signals that there are no further arguments, and causes
  19 +.Fa ap
  20 +to be invalidated.
  21 +Note that each call to
  22 +.Fn va_start
  23 +must be matched by a call to
  24  .Fn va_end ,
  25 -and must be called first.
  26 +from within the same function.
  27  .Pp
  28  The parameter
  29  .Fa last
  30 @@ -93,10 +101,6 @@
  31  function or an array type.
  32  .Pp
  33  The
  34 -.Fn va_start
  35 -macro returns no value.
  36 -.Pp
  37 -The
  38  .Fn va_arg
  39  macro expands to an expression that has the type and value of the next
  40  argument in the call.
  41 @@ -136,34 +140,38 @@
  42  .Pp
  43  The
  44  .Fn va_copy
  45 -macro copies a variable argument list, previously initialized by
  46 +macro copies the state of the variable argument list,
  47 +.Fa src ,
  48 +previously initialized by
  49  .Fn va_start ,
  50 -from
  51 -.Fa src
  52 -to
  53 -.Fa dest .
  54 -The state is preserved such that it is equivalent to calling
  55 +to the variable argument list,
  56 +.Fa dest ,
  57 +which must not have been previously initialized by
  58 +.Fn va_start ,
  59 +without an intervening call to
  60 +.Fn va_end .
  61 +The state preserved in
  62 +.Fa dest
  63 +is equivalent to calling
  64  .Fn va_start
  65 -with the same second argument used with
  66 -.Fa src ,
  67 -and calling
  68 +and
  69  .Fn va_arg
  70 -the same number of times as called with
  71 +on
  72 +.Fa dest
  73 +in the same way as was used on
  74  .Fa src .
  75 -.Pp
  76 -The
  77 -.Fn va_copy
  78 -macro returns no value.
  79 -.Pp
  80 -The
  81 +The copied variable argument list can subsequently be passed to
  82 +.Fn va_arg ,
  83 +and must finally be passed to
  84  .Fn va_end
  85 -macro handles a normal return from the function whose variable argument
  86 -list was initialized by
  87 -.Fn va_start .
  88 +when through with it.
  89  .Pp
  90 -The
  91 -.Fn va_end
  92 -macro returns no value.
  93 +After a variable argument list is invalidated by
  94 +.Fn va_end ,
  95 +it can be reinitialized with
  96 +.Fn va_start
  97 +or made a copy of another variable argument list with
  98 +.Fn va_copy .
  99  .Sh EXAMPLES
 100  The function
 101  .Em foo
 102 @@ -172,11 +180,12 @@
 103  .Bd -literal -offset indent
 104  void foo(char *fmt, ...)
 105  {
 106 -       va_list ap;
 107 +       va_list ap, ap2;
 108         int d;
 109         char c, *s;
 110
 111         va_start(ap, fmt);
 112 +       va_copy(ap2, ap);
 113         while (*fmt)
 114                 switch(*fmt++) {
 115                 case 's':                       /* string */
 116 @@ -194,6 +203,10 @@
 117                         break;
 118                 }
 119         va_end(ap);
 120 +       ...
 121 +       /* use ap2 to iterate over the arguments again */
 122 +       ...
 123 +       va_end(ap2);
 124  }
 125  .Ed
 126  .Sh COMPATIBILITY