Skip site navigation (1)Skip section navigation (2)
Date:      Sat, 21 Apr 2012 06:09:10 +0000 (UTC)
From:      David Schultz <das@FreeBSD.org>
To:        src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org
Subject:   svn commit: r234530 - head/lib/libc/stdio
Message-ID:  <201204210609.q3L69AsN074456@svn.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: das
Date: Sat Apr 21 06:09:09 2012
New Revision: 234530
URL: http://svn.freebsd.org/changeset/base/234530

Log:
  - Fix the claim that the output is always null-terminated. This isn't
    true if the size is zero.
  - Fix a claim that sprintf() is the same as snprintf() with an
    infinite size.  It's equivalent to snprintf() with a size of
    INT_MAX + 1.
  - Document the return values in the return values section.
  - Document the possible errno value of EOVERFLOW.
  
  MFC after:	2 weeks

Modified:
  head/lib/libc/stdio/printf.3

Modified: head/lib/libc/stdio/printf.3
==============================================================================
--- head/lib/libc/stdio/printf.3	Sat Apr 21 06:08:29 2012	(r234529)
+++ head/lib/libc/stdio/printf.3	Sat Apr 21 06:09:09 2012	(r234530)
@@ -113,20 +113,6 @@ string that specifies how subsequent arg
 .Xr stdarg 3 )
 are converted for output.
 .Pp
-These functions return the number of characters printed
-(not including the trailing
-.Ql \e0
-used to end output to strings) or a negative value if an output error occurs,
-except for
-.Fn snprintf
-and
-.Fn vsnprintf ,
-which return the number of characters that would have been printed if the
-.Fa size
-were unlimited
-(again, not including the final
-.Ql \e0 ) .
-.Pp
 The
 .Fn asprintf
 and
@@ -164,15 +150,19 @@ if the return value is greater than or e
 .Fa size
 argument, the string was too short
 and some of the printed characters were discarded.
-The output is always null-terminated.
+The output is always null-terminated, unless
+.Fa size
+is 0.
 .Pp
 The
 .Fn sprintf
 and
 .Fn vsprintf
 functions
-effectively assume an infinite
-.Fa size .
+effectively assume a
+.Fa size
+of
+.Dv INT_MAX + 1.
 .Pp
 The format string is composed of zero or more directives:
 ordinary
@@ -670,6 +660,21 @@ In no case does a non-existent or small 
 a numeric field; if the result of a conversion is wider than the field
 width, the
 field is expanded to contain the conversion result.
+.Sh RETURN VALUES
+These functions return the number of characters printed
+(not including the trailing
+.Ql \e0
+used to end output to strings),
+except for
+.Fn snprintf
+and
+.Fn vsnprintf ,
+which return the number of characters that would have been printed if the
+.Fa size
+were unlimited
+(again, not including the final
+.Ql \e0 ) .
+These functions return a negative value if an error occurs.
 .Sh EXAMPLES
 To print a date and time in the form
 .Dq Li "Sunday, July 3, 10:02" ,
@@ -771,6 +776,13 @@ family of functions may fail if:
 An invalid wide character code was encountered.
 .It Bq Er ENOMEM
 Insufficient storage space is available.
+.It Bq Er EOVERFLOW
+The
+.Fa size
+argument exceeds
+.Dv INT_MAX + 1 ,
+or the return value would be too large to be represented by an
+.Vt int .
 .El
 .Sh SEE ALSO
 .Xr printf 1 ,



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201204210609.q3L69AsN074456>