christos@zoulas.com (Christos Zoulas) wrote:
>
>  On Mar 3, 10:05pm, veenhuizen@users.sourceforge.net (Johan Veenhuizen) wrote:
>  -- Subject: standards/32981: man page is wrong on return values of printf/fpr
>  
>  | 	I have no copies of the C90/C99 standards in front of me,
>  | 	but "The C Programming Language, 2nd Ed.", POSIX and SUS
>  | 	document different return values for fprintf/sprintf/etc
>  | 	than the NetBSD manual page.
>  | 
>  | 	I have no clue about asprintf and vasprintf.  Maybe their
>  | 	return values should be changed as well, but they are not
>  | 	standardised yet as far as I know.
>  | 
>  | >Fix:
>  | 
>  | Index: printf.3
>  | ===================================================================
>  | RCS file: /cvsroot/src/lib/libc/stdio/printf.3,v
>  | retrieving revision 1.40
>  | diff -u -r1.40 printf.3
>  | --- printf.3	20 Jul 2005 13:31:15 -0000	1.40
>  | +++ printf.3	3 Mar 2006 21:38:40 -0000
>  | @@ -667,7 +667,7 @@
>  |  and
>  |  .Fn vfprintf
>  |  return the number of characters printed.
>  | -Otherwise \-1 is returned and
>  | +Otherwise a negative value is returned and
>  |  .Dv errno
>  |  is set to indicate the error.
>  |  .Pp
>  
>  ...
>  
>  Well -1 is negative (so we fulfill the requirement) and our implementation
>  only returns -1, so our documentation is correct. Perhaps a note saying that
>  conforming implementations are not required to return -1 and portable code
>  should not depend on these functions returning -1, is appropriate instead.

I agree with you that -1 is negative, so your implementation is
certainly correct in this regard.  However, I disagree when you
say that your documentation is correct.  The documentation is
telling something that could *possibly* be told in a comment
in the source code itself, but it does *not* inform you about the
definition of the behaviour of printf so it doesn't belong
in the manual page.

In my opinion, it is a serious bug to even mention that the NetBSD
implementation always returns -1 on errors.  There is simply no
value in that information, and it can only lead to confusion and
programmers writing unportable code.  It is such information
that eventually destroys a standard.

The code

	if (printf("...", ...) == -1)
		err(1, "stdout");

is just plain wrong.  Period.  It depends on an implementation
detail that can change at any time.  It's not even right on
a NetBSD system.

The code should implement what the documentation tells, not
the other way around.

Best regards,
Johan

P.S.
Thanks for the commits.