Re: [RFA] Fix documentation of snprintf and vsnprintf

[Eli Zaretskii <eliz@gnu.org>]

> Date: Sat, 23 May 2009 16:48:23 +0300
> From: Eli Zaretskii <eliz@gnu.org>

Ping!

> 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
>