OpenSSL documented the public function BIO_printf(3) (and friends)

in commit 2ca2e917.  Document it here, too, but do not use their
text.  Be more concise and more precise at the same time.

3 files changed, 91 insertions, 3 deletions

diff --git a/src/lib/libcrypto/man/BIO_new.3 b/src/lib/libcrypto/man/BIO_new.3
index 991f159886..356986d76d 100644
--- a/src/lib/libcrypto/man/BIO_new.3
+++ b/src/lib/libcrypto/man/BIO_new.3
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: BIO_new.3,v 1.7 2016/12/06 13:43:52 jmc Exp $
+.\"     $OpenBSD: BIO_new.3,v 1.8 2017/03/25 17:15:59 schwarze Exp $
 .\"     OpenSSL doc/man3/BIO_new.pod ca3a82c3 Mar 25 11:31:18 2015 -0400
 .\"     OpenSSL doc/man7/bio.pod a9c85cea Nov 11 09:33:55 2016 +0100
 .\"
@@ -49,7 +49,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 6 2016 $
+.Dd $Mdocdate: March 25 2017 $
 .Dt BIO_NEW 3
 .Os
 .Sh NAME
@@ -192,6 +192,7 @@ Create a memory BIO:
 .Xr BIO_f_ssl 3 ,
 .Xr BIO_find_type 3 ,
 .Xr BIO_get_ex_new_index 3 ,
+.Xr BIO_printf 3 ,
 .Xr BIO_push 3 ,
 .Xr BIO_read 3 ,
 .Xr BIO_s_accept 3 ,
diff --git a/src/lib/libcrypto/man/BIO_printf.3 b/src/lib/libcrypto/man/BIO_printf.3
new file mode 100644
index 0000000000..ebc1cc726e
--- /dev/null
+++ b/src/lib/libcrypto/man/BIO_printf.3
@@ -0,0 +1,86 @@
+.\"     $OpenBSD: BIO_printf.3,v 1.1 2017/03/25 17:15:59 schwarze Exp $
+.\"     OpenSSL 2ca2e917 Mon Mar 20 16:25:22 2017 -0400
+.\"
+.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: March 25 2017 $
+.Dt BIO_PRINTF 3
+.Os
+.Sh NAME
+.Nm BIO_printf ,
+.Nm BIO_vprintf ,
+.Nm BIO_snprintf ,
+.Nm BIO_vsnprintf
+.Nd formatted output to a BIO
+.Sh SYNOPSIS
+.In openssl/bio.h
+.Ft int
+.Fo BIO_printf
+.Fa "BIO *bio"
+.Fa "const char *format"
+.Fa ...
+.Fc
+.Ft int
+.Fo BIO_vprintf
+.Fa "BIO *bio"
+.Fa "const char *format"
+.Fa "va_list args"
+.Fc
+.Ft int
+.Fo BIO_snprintf
+.Fa "char *buf"
+.Fa "size_t n"
+.Fa "const char *format"
+.Fa ...
+.Fc
+.Ft int
+.Fo BIO_vsnprintf
+.Fa "char *buf"
+.Fa "size_t n"
+.Fa "const char *format"
+.Fa "va_list args"
+.Fc
+.Sh DESCRIPTION
+.Fn BIO_vprintf
+is a wrapper around
+.Xr vfprintf 3 ,
+sending the output to the specified
+.Fa bio .
+.Pp
+.Fn BIO_printf
+is a wrapper around
+.Fn BIO_vprintf .
+.Pp
+.Fn BIO_snprintf
+and
+.Fn BIO_vsnprintf
+are wrappers around
+.Xr vsnprintf 3 .
+.Sh RETURN VALUES
+These functions return the number of bytes written,
+or -1 if an error occurs.
+.Pp
+In contrast to
+.Xr snprintf 3
+and
+.Xr vsnprintf 3 ,
+.Fn BIO_snprintf
+and
+.Fn BIO_vsnprintf
+also return -1 if
+.Fa n
+is too small to hold the complete output.
+.Sh SEE ALSO
+.Xr BIO_new 3
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 75239dc387..70a73799c6 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.115 2017/02/20 23:21:19 beck Exp $
+# $OpenBSD: Makefile,v 1.116 2017/03/25 17:15:59 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -26,6 +26,7 @@ MAN=	\
         BIO_find_type.3 \
         BIO_get_ex_new_index.3 \
         BIO_new.3 \
+        BIO_printf.3 \
         BIO_push.3 \
         BIO_read.3 \
         BIO_s_accept.3 \