Re: [RFA] Fix documentation of snprintf and vsnprintf

[Eli Zaretskii <eliz@gnu.org>]

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