From b5982523b120586c33c8b9d47dcbbc3edfaec064 Mon Sep 17 00:00:00 2001
From: Joseph Myers <joseph@codesourcery.com>
Date: Fri, 20 Jul 2012 23:49:24 +0000
Subject: [PATCH] Document va_copy in preference to __va_copy.

---
 ChangeLog          |  8 ++++++++
 manual/lang.texi   | 25 +++++++++++++++----------
 manual/string.texi |  5 +----
 3 files changed, 24 insertions(+), 14 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index f50bf6f..f37974a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2012-07-20  Joseph Myers  <joseph@codesourcery.com>
+
+	* manual/lang.texi (__va_copy): Document primarily as ISO C99
+	va_copy.  Document allowing for unavailable va_copy only as
+	pre-C99 compatibility.
+	* manual/string.texi (Copying and Concatenation): Use va_copy
+	instead of __va_copy in concat example.
+
 2012-07-20  Pino Toscano  <toscano.pino@tiscali.it>
 
 	* sysdeps/mach/hurd/sendto.c (create_address_port): New subroutine.
diff --git a/manual/lang.texi b/manual/lang.texi
index baaccaa..ee04e23 100644
--- a/manual/lang.texi
+++ b/manual/lang.texi
@@ -463,28 +463,33 @@ assign the value of one variable of type @code{va_list} to another variable
 of the same type.
 
 @comment stdarg.h
-@comment GNU
-@deftypefn {Macro} void __va_copy (va_list @var{dest}, va_list @var{src})
-The @code{__va_copy} macro allows copying of objects of type
+@comment ISO
+@deftypefn {Macro} void va_copy (va_list @var{dest}, va_list @var{src})
+@deftypefnx {Macro} void __va_copy (va_list @var{dest}, va_list @var{src})
+The @code{va_copy} macro allows copying of objects of type
 @code{va_list} even if this is not an integral type.  The argument pointer
 in @var{dest} is initialized to point to the same argument as the
 pointer in @var{src}.
 
-This macro is a GNU extension but it will hopefully also be available in
-the next update of the ISO C standard.
+This macro was added in ISO C99.  When building for strict conformance
+to ISO C90 (@samp{gcc -ansi}), it is not available.  The macro
+@code{__va_copy} is available as a GNU extension in any standards
+mode; before GCC 3.0, it was the only macro for this functionality.
 @end deftypefn
 
-If you want to use @code{__va_copy} you should always be prepared for the
+If you want to use @code{va_copy} and be portable to pre-C99 systems,
+you should always be prepared for the
 possibility that this macro will not be available.  On architectures where a
-simple assignment is invalid, hopefully @code{__va_copy} @emph{will} be available,
-so one should always write something like this:
+simple assignment is invalid, hopefully @code{va_copy} @emph{will} be available,
+so one should always write something like this if concerned about
+pre-C99 portability:
 
 @smallexample
 @{
   va_list ap, save;
   @dots{}
-#ifdef __va_copy
-  __va_copy (save, ap);
+#ifdef va_copy
+  va_copy (save, ap);
 #else
   save = ap;
 #endif
diff --git a/manual/string.texi b/manual/string.texi
index 831873b..2844bc6 100644
--- a/manual/string.texi
+++ b/manual/string.texi
@@ -824,7 +824,6 @@ to use @code{strcat}/@code{wcscat}.  A lot of time is wasted finding the
 end of the destination string so that the actual copying can start.
 This is a common example:
 
-@cindex __va_copy
 @cindex va_copy
 @smallexample
 /* @r{This function concatenates arbitrarily many strings.  The last}
@@ -838,9 +837,7 @@ concat (const char *str, @dots{})
   char *result;
 
   va_start (ap, str);
-  /* @r{Actually @code{va_copy}, but this is the name more gcc versions}
-     @r{understand.}  */
-  __va_copy (ap2, ap);
+  va_copy (ap2, ap);
 
   /* @r{Determine how much space we need.}  */
   for (s = str; s != NULL; s = va_arg (ap, const char *))
-- 
2.7.4