Subject: Re: standards/32981: man page is wrong on return values of
To: None <firstname.lastname@example.org>
From: Johan Veenhuizen <email@example.com>
Date: 03/04/2006 00:52:21
firstname.lastname@example.org (Christos Zoulas) wrote:
> On Mar 3, 10:05pm, email@example.com (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.
if (printf("...", ...) == -1)
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.
Thanks for the commits.