svn commit: r262190 - in stable: 10/share/man/man3 8/share/man/man3 9/share/man/man3

[John Baldwin]

Author: jhb
Date: Tue Feb 18 20:16:32 2014
New Revision: 262190
URL: http://svnweb.freebsd.org/changeset/base/262190

Log:
  MFC 261518:
  - Update a few places to account for va_copy().
  - Create a separate 'return values' section and move some statements about
    return values to that section.
  - Note that each invocation of va_start() and va_copy() must be paired with
    va_end() in the same function.

Modified:
  stable/10/share/man/man3/stdarg.3
Directory Properties:
  stable/10/   (props changed)

Changes in other areas also in this revision:
Modified:
  stable/8/share/man/man3/stdarg.3
  stable/9/share/man/man3/stdarg.3
Directory Properties:
  stable/8/share/man/man3/   (props changed)
  stable/9/share/man/man3/   (props changed)

Modified: stable/10/share/man/man3/stdarg.3
==============================================================================
--- stable/10/share/man/man3/stdarg.3	Tue Feb 18 19:58:01 2014	(r262189)
+++ stable/10/share/man/man3/stdarg.3	Tue Feb 18 20:16:32 2014	(r262190)
@@ -59,7 +59,7 @@ The include file
 .In stdarg.h
 declares a type
 .Pq Em va_list
-and defines three macros for stepping
+and defines four macros for stepping
 through a list of arguments whose number and types are not known to
 the called function.
 .Pp
@@ -77,7 +77,8 @@ The
 macro initializes
 .Fa ap
 for subsequent use by
-.Fn va_arg
+.Fn va_arg ,
+.Fn va_copy ,
 and
 .Fn va_end ,
 and must be called first.
@@ -93,10 +94,6 @@ macro, it should not be declared as a re
 function or an array type.
 .Pp
 The
-.Fn va_start
-macro returns no value.
-.Pp
-The
 .Fn va_arg
 macro expands to an expression that has the type and value of the next
 argument in the call.
@@ -105,7 +102,9 @@ The parameter
 is the
 .Em va_list Fa ap
 initialized by
-.Fn va_start .
+.Fn va_start
+or
+.Fn va_copy .
 Each call to
 .Fn va_arg
 modifies
@@ -152,18 +151,28 @@ the same number of times as called with
 .Fa src .
 .Pp
 The
-.Fn va_copy
-macro returns no value.
+.Fn va_end
+macro cleans up any state associated with the variable argument list
+.Fa ap .
 .Pp
-The
+Each invocation of
+.Fn va_start
+or
+.Fn va_copy
+must be paired with a corresponding invocation of
 .Fn va_end
-macro handles a normal return from the function whose variable argument
-list was initialized by
-.Fn va_start .
+in the same function.
+.Sh RETURN VALUES
+The
+.Fn va_arg
+macro returns the value of the next argument.
 .Pp
 The
+.Fn va_start ,
+.Fn va_copy ,
+and
 .Fn va_end
-macro returns no value.
+macros return no value.
 .Sh EXAMPLES
 The function
 .Em foo