move return values to a seperate section, and split them out so that it

is more clear which variants return which values; ok jmc otto

1 files changed, 49 insertions, 37 deletions

diff --git a/lib/libc/stdio/printf.3 b/lib/libc/stdio/printf.3
index 1eaf7375db4..8d02f01809a 100644
--- a/lib/libc/stdio/printf.3
+++ b/lib/libc/stdio/printf.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: printf.3,v 1.46 2005/04/14 18:19:24 otto Exp $
+.\"	$OpenBSD: printf.3,v 1.47 2005/04/14 18:20:51 deraadt Exp $
 .\"
 .\" Copyright (c) 1990, 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -115,42 +115,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),
-except for
-.Fn snprintf
-and
-.Fn vsnprintf ,
-which return the number of characters that would have been printed if the
-.Fa size
-were unlimited
-.Po
-again, not including the final
-.Ql \e0
-.Pc .
-If an output or encoding error occurs, a value of \-1 is returned instead.
-.Pp
-.Fn asprintf
-and
-.Fn vasprintf
-return a pointer to a buffer sufficiently large to hold the string in the
-.Fa ret
-argument.
-This pointer should be passed to
-.Xr free 3
-to release the allocated storage when it is no longer needed.
-If sufficient space cannot be allocated, these functions
-will return \-1.
-The value of
-.Fa ret
-in this situation is implementation-dependent
-(on
-.Ox ,
-.Fa ret
-will be set to the null pointer, but this behavior should not be relied upon).
-.Pp
 .Fn snprintf
 and
 .Fn vsnprintf
@@ -621,6 +585,54 @@ The complete conversion specification is
 In no case does a non-existent or small field width cause truncation of
 a 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
+The
+.Fn printf ,
+.Fn fprintf ,
+.Fn sprintf ,
+.Fn vprintf ,
+.Fn vfprintf ,
+.Fn vsprintf ,
+and
+.Fn vasprintf
+functions
+return the number of characters printed
+(not including the trailing
+.Ql \e0
+used to end output to strings).
+.Pp
+The
+.Fn snprintf
+and
+.Fn vsnprintf
+functions return the number of characters that would have
+been output if the
+.Fa size
+were unlimited
+.Po
+again, not including the final
+.Ql \e0
+.Pc .
+If an output or encoding error occurs, a value of \-1 is returned instead.
+.Pp
+.Fn asprintf
+and
+.Fn vasprintf
+return a pointer to a buffer sufficiently large to hold the string in the
+.Fa ret
+argument.
+This pointer should be passed to
+.Xr free 3
+to release the allocated storage when it is no longer needed.
+If sufficient space cannot be allocated, these functions
+will return \-1.
+The value of
+.Fa ret
+in this situation is implementation-dependent
+(on
+.Ox ,
+.Fa ret
+will be set to the null pointer, but this behavior should not be relied upon).
 .Sh EXAMPLES
 To print a date and time in the form `Sunday, July 3, 10:02',
 where