Re: [RFA] Fix documentation of snprintf and vsnprintf

[Dave Korn <dave dot korn dot cygwin at googlemail dot com>]

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