[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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.


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: