Re: [RFA] Fix documentation of snprintf and vsnprintf

[Eli Zaretskii <eliz@gnu.org>]

> Date: Fri, 29 May 2009 21:50:41 +0100
> From: Dave Korn <dave.korn.cygwin@googlemail.com>
> CC: Dave Korn <dave.korn.cygwin@googlemail.com>, eliz@gnu.org, 
>  gcc-patches@gcc.gnu.org, gdb-patches@sourceware.org
> 
> DJ Delorie wrote:
> >> Also, how about that proposed variation to the wording?
> >>
> >> http://gcc.gnu.org/ml/gcc-patches/2009-05/msg01524.html
> > 
> > When it comes to documentation, I'm willing to trust Eli's judgement.
> 
>   Sorry for piggybacking, that question was directed at Eli!

Here's the modified version:

--- libiberty/snprintf.c~0	2005-05-10 21:33:34.000000000 +0300
+++ libiberty/snprintf.c	2009-05-29 23:51:35.453125000 +0300
@@ -27,13 +27,15 @@
 
 @deftypefn Supplemental int snprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, ...)
 
-This function is similar to sprintf, but it will print at most @var{n}
-characters.  On error the return value is -1, otherwise it returns the
-number of characters that would have been printed had @var{n} been
-sufficiently large, regardless of the actual value of @var{n}.  Note
-some pre-C99 system libraries do not implement this correctly so users
-cannot generally rely on the return value if the system version of
-this function is used.
+This function is similar to @code{sprintf}, but it will write to
+@var{buf} at most @code{@var{n}-1} bytes of text, followed by a
+terminating null byte, for a total of @var{n} bytes.
+On error the return value is -1, otherwise it returns the number of
+bytes, not including the terminating null byte, that would have been
+written had @var{n} been sufficiently large, regardless of the actual
+value of @var{n}.  Note some pre-C99 system libraries do not implement
+this correctly so users cannot generally rely on the return value if
+the system version of this function is used.
 
 @end deftypefn
 
--- libiberty/vsnprintf.c~	2009-05-23 16:36:07.265625000 +0300
+++ libiberty/vsnprintf.c	2009-05-29 23:52:35.203125000 +0300
@@ -27,8 +27,9 @@
 
 @deftypefn Supplemental int vsnprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, va_list @var{ap})
 
-This function is similar to @code{vsprintf}, but it will write at most
-@var{n} bytes (including the terminating null byte) to @var{buf}.
+This function is similar to @code{vsprintf}, but it will write to
+@var{buf} at most @code{@var{n}-1} bytes of text, followed by a
+terminating null byte, for a total of @var{n} bytes.
 On error the return value is -1, otherwise it returns the number of
 bytes, not including the terminating null byte, that would have been
 written had @var{n} been sufficiently large, regardless of the actual