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 <e...@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
