This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Re: [RFA] Fix documentation of snprintf and vsnprintf
- From: Dave Korn <dave dot korn dot cygwin at googlemail dot com>
- To: Eli Zaretskii <eliz at gnu dot org>
- Cc: gcc at gcc dot gnu dot org, gcc-patches at gcc dot gnu dot org
- Date: Sat, 23 May 2009 15:29:20 +0100
- Subject: Re: [RFA] Fix documentation of snprintf and vsnprintf
- References: <83d4a0szry.fsf@gnu.org>
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?
I think it's still a little bit unclear:
> +This function is similar to @code{sprintf}, but it will write at most
> +var{n} bytes (including the terminating null byte) to @var{buf}.
It could still be perceived as ambiguous. That sentence says that the
terminating null byte is included in the count of
"the-most-bytes-it-will-write", but it doesn't explicitly say that it won't be
truncated off like the rest of the characters if the output is too long. How
about
> +This function is similar to @code{sprintf}, but it will write at most
> +var{n} bytes (truncating the output if necessary, so that there is
> +always guaranteed to be a terminating null byte) to @var{buf}.
I got this wrong in some code I was writing just the other day, when I
wanted to produce a non-null terminated string in an exact-length buffer, and
had to go back and fix it after reading the documentation three times and
inferring which of the meanings it must have intended from the behaviour I had
observed...
cheers,
DaveK