Re: [RFA] Fix documentation of snprintf and vsnprintf

Pedro Alves
2009-05-23T13:55:26Z

Hi Eli,

libiberty is maintained by gcc. You should send this to gcc-patches@.

(I always have to peek at src/MAINTAINERS to remind myself.)

--
Pedro Alves

On Saturday 23 May 2009 14:48:23, Eli Zaretskii wrote:
> 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
>
>
>