svn commit: r234530 - head/lib/libc/stdio
David Schultz
das at FreeBSD.org
Sat Apr 21 06:09:10 UTC 2012
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 ,
More information about the svn-src-all
mailing list