Re: misc/39871: printf family manpage has no RETURN VALUES section

["Martin S. Weber" <Ephaeton%gmx.net@localhost>]

The following reply was made to PR misc/39871; it has been noted by GNATS.

From: "Martin S. Weber" <Ephaeton%gmx.net@localhost>
To: gnats-bugs%NetBSD.org@localhost
Cc: 
Subject: Re: misc/39871: printf family manpage has no RETURN VALUES section
Date: Sun, 9 Nov 2008 15:20:05 -0500

 --vGgW1X5XWziG23Ko
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
 
 Maybe attached patch is good enough for you. It's just moving the description
 of the return values already present in the page in its own section. Should
 apply fine to lib/libc/stdio/printf.3.
 
 -Martin
 
 --vGgW1X5XWziG23Ko
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: attachment; filename=printf-return-values
 
 --- /usr/src/lib/libc/stdio/printf.3   2007-06-09 14:51:19.000000000 -0400
 +++ ./printf.3 2008-11-09 15:12:33.000000000 -0500
 @@ -113,38 +113,6 @@
  .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).
 -If an output error was encountered, these functions shall return a
 -negative value.
 -.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 and set
 -.Fa ret
 -to be a
 -.Dv NULL
 -pointer.
 -Please note that these functions are not standardized, and not all
 -implementations can be assumed to set the
 -.Fa ret
 -argument to
 -.Dv NULL
 -on error.
 -It is more portable to check for a return value of \-1 instead.
 -.Pp
  .Fn snprintf
  and
  .Fn vsnprintf
 @@ -821,6 +789,39 @@
  Always use the proper secure idiom:
  .Pp
  .Dl "snprintf(buffer, sizeof(buffer), \*q%s\*q, string);"
 +.Sh RETURN VALUES
 +.Pp
 +These functions return
 +the number of characters printed
 +(not including the trailing
 +.Ql \e0
 +used to end output to strings).
 +If an output error was encountered, these functions shall return a
 +negative value.
 +.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 and set
 +.Fa ret
 +to be a
 +.Dv NULL
 +pointer.
 +Please note that these functions are not standardized, and not all
 +implementations can be assumed to set the
 +.Fa ret
 +argument to
 +.Dv NULL
 +on error.
 +It is more portable to check for a return value of \-1 instead.
  .Sh ERRORS
  In addition to the errors documented for the
  .Xr write 2
 
 --vGgW1X5XWziG23Ko--