[RFA] Fix documentation of snprintf and vsnprintf

[Eli Zaretskii <eliz@gnu.org>]

The current documentation of these two functions is misleading, and can
easily cause off-by-one bugs, if one follows it to the letter and
doesn't double-check with what the source actually does.

I tried to be more accurate in the patch below.

OK?

2009-05-23  Eli Zaretskii  <eliz@gnu.org>

	* snprintf.c: Doc fix.

	* vsnprintf.c: Doc fix.

--- libiberty/snprintf.c~0	2005-05-10 21:33:34.000000000 +0300
+++ libiberty/snprintf.c	2009-05-23 16:34:39.265625000 +0300
@@ -27,13 +27,14 @@
 
 @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 at most
+var{n} bytes (including the terminating null byte) to @var{buf}.
+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~0	2005-05-10 21:33:34.000000000 +0300
+++ libiberty/vsnprintf.c	2009-05-23 16:36:07.265625000 +0300
@@ -27,13 +27,14 @@
 
 @deftypefn Supplemental int vsnprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, va_list @var{ap})
 
-This function is similar to vsprintf, 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{vsprintf}, but it will write at most
+@var{n} bytes (including the terminating null byte) to @var{buf}.
+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