Re: [Patch] Minor documentation clarification

[Carlos O'Donell <carlos_odonell at mentor dot com>]

On 8/13/2012 1:08 PM, Jeff Law wrote:
> It's been reported that the documentation for snprintf is a bit unclear as to if/when the output string is NULL terminated.
> 
> As far as I was able to tell, the output string is always NULL terminated unless SIZE is zero.

That's correct. If size is zero we use an internal buffer to count the written bytes because the result still has to be accurate.
 
> This patch adds that clarification to the glibc manual.
> 
> 2012-08-13  Jeff Law <law@redhat.com>
> 
> 	* manual/stdio.texi (snprintf): Clarify handling of the trailing
> 	null byte in the output string.
> 
> diff --git a/manual/stdio.texi b/manual/stdio.texi
> index c58ca22..605096e 100644
> --- a/manual/stdio.texi
> +++ b/manual/stdio.texi
> @@ -2342,6 +2342,8 @@ the @var{size} argument specifies the maximum number of characters to
>  produce.  The trailing null character is counted towards this limit, so
>  you should allocate at least @var{size} characters for the string @var{s}.
>  
> +The trailing null byte is added to @var{s}, unless @var{size} is zero.
> +

Might I suggest:

If @var{size} is zero, nothing, not even the null byte, shall be written and @var{s} may be a null pointer.

Which is in line with what POSIX says.

I would also keep it part of the first paragraph.

>  The return value is the number of characters which would be generated
>  for the given input, excluding the trailing null.  If this value is
>  greater or equal to @var{size}, not all characters from the result have

Cheers,
Carlos.
-- 
Carlos O'Donell
Mentor Graphics / CodeSourcery
carlos_odonell@mentor.com
carlos@codesourcery.com
+1 (613) 963 1026