Bug#38392: glibc-doc: documentation of snprintf return value is deceptive
>>>>> Ben Pfaff writes:
Ben> Andreas Jaeger <aj@arthur.rhein-neckar.de> writes:
Ben> It does not mention that in glibc 2.0 (and earlier?), if the buffer
Ben> wasn't large enough to hold the format output, it would return -1
Ben> instead of the number of characters that would have been written.
Ben> This is deceptive, because it leads the reader to believe that he can
Ben> depend on the return value for the size of a buffer to allocate, which
Ben> is not true if you want to be glibc 2.0 or earlier compatible.
Ben> This changed between glibc 2.0 and 2.1 because ISO C 9x requires this:
Ben> 1997-03-08 05:30 Ulrich Drepper <drepper@cygnus.com>
Ben> * libio/vsnprintf.c: Change implementation to follow ISO C 9X
Ben> proposal. The return value now is always the number of characters
Ben> which would be written if enough space is available.
Ben> * manual/stdio.texi: Update description for new behaviour.
Ben> It's still a bug in the documentation, even if it's not a bug in the
Ben> code. It should mention that older versions of glibc behave
Ben> differently. There's no excuse for gratuitously causing bugs because
Ben> people believe the documentation and try to use functions in
Ben> accordance with it.
You've convinced me. The appended patch is now in glibc.
Andreas
1999-05-29 Andreas Jaeger <aj@arthur.rhein-neckar.de>
* manual/stdio.texi (Formatted Output Functions): Mention
semantics of snprintf in glibc 2.0.
Reported by Ben Pfaff <pfaffben@msu.edu>.
$ diff -u manual/stdio.texi.~1~ manual/stdio.texi
--- manual/stdio.texi.~1~ Thu Mar 11 07:09:51 1999
+++ manual/stdio.texi Sun May 30 14:27:32 1999
@@ -1616,6 +1616,12 @@
@end smallexample
In practice, it is often easier just to use @code{asprintf}, below.
+
+@strong{Attention:} In the GNU C library version 2.0 the return value
+is the number of characters stored, not including the terminating null.
+If this value equals @code{@var{size} - 1}, then there was not enough
+space in @var{s} for all the output. This change was neccessary with
+the adoption of snprintf by ISO C9x.
@end deftypefun
@node Dynamic Output
--
Andreas Jaeger aj@arthur.rhein-neckar.de jaeger@informatik.uni-kl.de
for pgp-key finger ajaeger@aixd1.rhrk.uni-kl.de
Reply to: