From eac48bba4cc5551ad13c07070a93014c28b6a1cd Mon Sep 17 00:00:00 2001
From: das <das@FreeBSD.org>
Date: Sat, 21 Apr 2012 06:09:09 +0000
Subject: - 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
---
 lib/libc/stdio/printf.3 | 46 +++++++++++++++++++++++++++++-----------------
 1 file changed, 29 insertions(+), 17 deletions(-)

(limited to 'lib/libc/stdio')

diff --git a/lib/libc/stdio/printf.3 b/lib/libc/stdio/printf.3
index 90a8ed8..0d9339e 100644
--- a/lib/libc/stdio/printf.3
+++ b/lib/libc/stdio/printf.3
@@ -113,20 +113,6 @@ string that specifies how subsequent arguments
 .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 equal to the
 .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 field width cause truncation of
 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 ,
-- 
cgit v1.1