Re: [RFA] Fix documentation of snprintf and vsnprintf

Eli Zaretskii
2009-05-23T17:13:24Z

> Date: Sat, 23 May 2009 15:29:20 +0100
> From: Dave Korn <dave.korn.cygwin@googlemail.com>
> CC: gcc@gcc.gnu.org, gcc-patches@gcc.gnu.org
>
> 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.

I thought it did say that, as

"write at most N bytes (including the terminating null byte)"

means that it will write no more than N bytes, and those N bytes
include the null byte.

However, I don't mind the text you suggest if people think it says the
same more clearly:

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

Or maybe we should make it clearer still:

This function is similar to @code{sprintf}, but it will write to
@var{buf} at most @code{var{n}-1} bytes of text, followed by a
terminating null byte, for the total of @var{n} bytes.

WDYT?