We don't want section 3 manual pages with names that do not correspond

to functions, so delete the BIO(3) manual page and merge its content
into BIO_new(3) and BIO_push(3).

Sort the content of BIO_new(3) into a logical order
and improve the wording in various ways.
Add the required cross references to BIO_push(3).

4 files changed, 108 insertions, 154 deletions

diff --git a/lib/libcrypto/man/BIO.3 b/lib/libcrypto/man/BIO.3
deleted file mode 100644
index 3c2dd8cbe5d..00000000000
--- a/lib/libcrypto/man/BIO.3
+++ /dev/null
@@ -1,105 +0,0 @@
-.\"	$OpenBSD: BIO.3,v 1.5 2016/11/22 14:55:19 schwarze Exp $
-.\"	OpenSSL a9c85cea Nov 11 09:33:55 2016 +0100
-.\"
-.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
-.\" Copyright (c) 2000 The OpenSSL Project.  All rights reserved.
-.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\"
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice, this list of conditions and the following disclaimer.
-.\"
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\"    notice, this list of conditions and the following disclaimer in
-.\"    the documentation and/or other materials provided with the
-.\"    distribution.
-.\"
-.\" 3. All advertising materials mentioning features or use of this
-.\"    software must display the following acknowledgment:
-.\"    "This product includes software developed by the OpenSSL Project
-.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
-.\"
-.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
-.\"    endorse or promote products derived from this software without
-.\"    prior written permission. For written permission, please contact
-.\"    openssl-core@openssl.org.
-.\"
-.\" 5. Products derived from this software may not be called "OpenSSL"
-.\"    nor may "OpenSSL" appear in their names without prior written
-.\"    permission of the OpenSSL Project.
-.\"
-.\" 6. Redistributions of any form whatsoever must retain the following
-.\"    acknowledgment:
-.\"    "This product includes software developed by the OpenSSL Project
-.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
-.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
-.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
-.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
-.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
-.\" OF THE POSSIBILITY OF SUCH DAMAGE.
-.\"
-.Dd $Mdocdate: November 22 2016 $
-.Dt BIO 3
-.Os
-.Sh NAME
-.Nm BIO
-.Nd OpenSSL basic I/O abstraction
-.Sh SYNOPSIS
-.In openssl/bio.h
-.Sh DESCRIPTION
-A BIO is an I/O abstraction,
-hiding many of the underlying I/O details from an application.
-If an application uses a BIO for its I/O, it can transparently handle
-SSL connections, unencrypted network connections and file I/O.
-.Pp
-There are two types of BIO, a source/sink BIO and a filter BIO.
-.Pp
-As its name implies, a source/sink BIO is a source and/or sink of data.
-Examples include a socket BIO and a file BIO.
-.Pp
-A filter BIO takes data from one BIO and passes it through
-to another, or to the application.
-The data may be left unmodified (for example a message digest BIO)
-or translated (for example an encryption BIO).
-The effect of a filter BIO may change according to the I/O operation
-it is performing: for example an encryption BIO will encrypt data
-if it is being written to and decrypt data if it is being read from.
-.Pp
-BIOs can be joined together to form a chain
-(a single BIO is a chain with one component).
-A chain normally consist of one source/sink BIO
-and one or more filter BIOs.
-Data read from or written to the first BIO then traverses the chain
-to the end (normally a source/sink BIO).
-.Sh SEE ALSO
-.Xr BIO_ctrl 3 ,
-.Xr BIO_f_base64 3 ,
-.Xr BIO_f_buffer 3 ,
-.Xr BIO_f_cipher 3 ,
-.Xr BIO_f_md 3 ,
-.Xr BIO_f_null 3 ,
-.Xr BIO_f_ssl 3 ,
-.Xr BIO_find_type 3 ,
-.Xr BIO_new 3 ,
-.Xr BIO_push 3 ,
-.Xr BIO_read 3 ,
-.Xr BIO_s_accept 3 ,
-.Xr BIO_s_bio 3 ,
-.Xr BIO_s_connect 3 ,
-.Xr BIO_s_fd 3 ,
-.Xr BIO_s_file 3 ,
-.Xr BIO_s_mem 3 ,
-.Xr BIO_s_null 3 ,
-.Xr BIO_s_socket 3 ,
-.Xr BIO_set_callback 3 ,
-.Xr BIO_should_retry 3
diff --git a/lib/libcrypto/man/BIO_new.3 b/lib/libcrypto/man/BIO_new.3
index 59a5b370563..654f4e844a0 100644
--- a/lib/libcrypto/man/BIO_new.3
+++ b/lib/libcrypto/man/BIO_new.3
@@ -1,5 +1,6 @@
-.\"	$OpenBSD: BIO_new.3,v 1.5 2016/11/18 18:43:05 schwarze Exp $
-.\"	OpenSSL ca3a82c3 Mar 25 11:31:18 2015 -0400
+.\"	$OpenBSD: BIO_new.3,v 1.6 2016/12/06 12:54:19 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
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2000, 2015, 2016 The OpenSSL Project.  All rights reserved.
@@ -48,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: November 18 2016 $
+.Dd $Mdocdate: December 6 2016 $
 .Dt BIO_NEW 3
 .Os
 .Sh NAME
@@ -57,7 +58,7 @@
 .Nm BIO_free ,
 .Nm BIO_vfree ,
 .Nm BIO_free_all
-.Nd BIO allocation and freeing functions
+.Nd construct and destruct I/O abstraction objects
 .Sh SYNOPSIS
 .In openssl/bio.h
 .Ft BIO *
@@ -82,78 +83,124 @@
 .Fa "BIO *a"
 .Fc
 .Sh DESCRIPTION
+A
+.Vt BIO
+is an I/O abstraction object, hiding many of the underlying I/O
+details from an application.
+If an application uses BIOs for its I/O, it can transparently handle
+SSL connections, unencrypted network connections, and file I/O.
+.Pp
 The
 .Fn BIO_new
-function returns a new BIO using method
+function constructs a new
+.Vt BIO
+using the method
 .Fa type .
+There are two groups of BIO types, source/sink BIOs and a filter BIOs.
+.Pp 
+Source/sink BIOs provide input or consume output.
+Examples include socket BIOs and file BIOs.
+.Pp
+Filter BIOs take data from one BIO and pass it through to another,
+or to the application, forming a chain of BIOs.
+The data may be left unmodified (for example by a message digest BIO)
+or translated (for example by an encryption BIO).
+The effect of a filter BIO may change according to the I/O operation
+it is performing: for example an encryption BIO will encrypt data
+if it is written to and decrypt data if it is read from.
+.Pp
+Some BIOs (such as memory BIOs) can be used immediately after calling
+.Fn BIO_new .
+Others (such as file BIOs) need some additional initialization, and
+utility functions exists to construct and initialize such BIOs.
+.Pp
+Normally the
+.Fa type
+argument is supplied by a function which returns a pointer to a
+.Vt BIO_METHOD .
+There is a naming convention for such functions:
+the methods for source/sink BIOs are called
+.Fn BIO_s_*
+and those for filter BIOs
+.Fn BIO_f_* .
 .Pp
 .Fn BIO_set
 sets the method of an already existing BIO.
 .Pp
 .Fn BIO_free
-frees up a single BIO;
+and
 .Fn BIO_vfree
-also frees up a single BIO, but it does not return a value.
+destruct a single BIO, which may also have some effect on the
+underlying I/O structure, for example it may close the file being
+referred to under certain circumstances.
 If
 .Fa a
 is a
 .Dv NULL
 pointer, no action occurs.
-Calling
+If
 .Fn BIO_free
-may also have some effect on the underlying I/O structure,
-for example it may close the file being
-referred to under certain circumstances.
-For more details see the individual
-.Vt BIO_METHOD
-descriptions.
+is called on a BIO chain, it will only destruct one BIO,
+resulting in a memory leak.
 .Pp
 .Fn BIO_free_all
-frees up an entire BIO chain.
+destructs an entire BIO chain.
 It does not halt if an error occurs
-freeing up an individual BIO in the chain.
+destructing an individual BIO in the chain.
 If
 .Fa a
 is a
 .Dv NULL
 pointer, no action occurs.
-.Pp
-Some BIOs (such as memory BIOs) can be used immediately after calling
-.Fn BIO_new .
-Others (such as file BIOs) need some additional initialization, and
-frequently a utility function exists to create and initialize such BIOs.
-.Pp
-If
-.Fn BIO_free
-is called on a BIO chain, it will only free one BIO,
-resulting in a memory leak.
-.Pp
 Calling
 .Fn BIO_free_all
-on a single BIO has the same effect as calling
-.Fn BIO_free
-on it other than the discarded return value.
+on a single BIO has the same effect as
+.Fn BIO_vfree .
 .Pp
-Normally the
-.Fa type
-argument is supplied by a function which returns a pointer to a
-.Vt BIO_METHOD .
-There is a naming convention for such functions:
-a source/sink BIO is normally called
-.Fn BIO_s_*
-and a filter BIO
-.Fn BIO_f_* .
+Common I/O functions are documented in
+.Xr BIO_read 3 .
+Forming chains is explained in
+.Xr BIO_push 3 ,
+inspecting them in
+.Xr BIO_find_type 3 .
+For more details about the different kinds of BIOs, see the individual
+.Vt BIO_METHOD
+manual pages.
 .Sh RETURN VALUES
 .Fn BIO_new
-returns a newly created BIO or
+returns a newly constructed
+.Vt BIO
+object or
 .Dv NULL
-if the call fails.
+on failure.
 .Pp
 .Fn BIO_set
 and
 .Fn BIO_free
-return 1 for success and 0 for failure.
+return 1 for success or 0 for failure.
 .Sh EXAMPLES
 Create a memory BIO:
 .Pp
 .Dl BIO *mem = BIO_new(BIO_s_mem());
+.Sh SEE ALSO
+.Xr BIO_ctrl 3 ,
+.Xr BIO_f_base64 3 ,
+.Xr BIO_f_buffer 3 ,
+.Xr BIO_f_cipher 3 ,
+.Xr BIO_f_md 3 ,
+.Xr BIO_f_null 3 ,
+.Xr BIO_f_ssl 3 ,
+.Xr BIO_get_ex_new_index.3 ,
+.Xr BIO_find_type 3 ,
+.Xr BIO_push 3 ,
+.Xr BIO_read 3 ,
+.Xr BIO_s_accept 3 ,
+.Xr BIO_s_bio 3 ,
+.Xr BIO_s_connect 3 ,
+.Xr BIO_s_fd 3 ,
+.Xr BIO_s_file 3 ,
+.Xr BIO_s_mem 3 ,
+.Xr BIO_s_null 3 ,
+.Xr BIO_s_socket 3 ,
+.Xr BIO_set_callback 3 ,
+.Xr BIO_should_retry 3
diff --git a/lib/libcrypto/man/BIO_push.3 b/lib/libcrypto/man/BIO_push.3
index 42afc7659ad..5b9e94123fd 100644
--- a/lib/libcrypto/man/BIO_push.3
+++ b/lib/libcrypto/man/BIO_push.3
@@ -1,5 +1,6 @@
-.\"	$OpenBSD: BIO_push.3,v 1.4 2016/11/18 18:52:11 schwarze Exp $
-.\"	OpenSSL 76ed5a42 Jun 29 13:38:55 2014 +0100
+.\"	$OpenBSD: BIO_push.3,v 1.5 2016/12/06 12:54:19 schwarze Exp $
+.\"	OpenSSL doc/man3/BIO_push.pod 76ed5a42 Jun 29 13:38:55 2014 +0100
+.\"	OpenSSL doc/man7/bio.pod a9c85cea Nov 11 09:33:55 2016 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2000, 2014 The OpenSSL Project.  All rights reserved.
@@ -48,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: November 18 2016 $
+.Dd $Mdocdate: December 6 2016 $
 .Dt BIO_PUSH 3
 .Os
 .Sh NAME
@@ -67,6 +68,13 @@
 .Fa "BIO *b"
 .Fc
 .Sh DESCRIPTION
+BIOs can be joined together to form chains.
+A chain normally consist of one or more filter BIOs
+and one source/sink BIO at the end.
+Data read from or written to the first BIO traverses the chain
+to the end.
+A single BIO can be regarded as a chain with one component.
+.Pp
 The
 .Fn BIO_push
 function appends the BIO
@@ -97,8 +105,9 @@ The process of calling
 .Fn BIO_push
 and
 .Fn BIO_pop
-on a BIO may have additional consequences:
-a control call is made to the affected BIOs.
+on a BIO may have additional consequences: a
+.Xr BIO_ctrl 3
+call is made to the affected BIOs.
 Any effects will be noted in the descriptions of individual BIOs.
 .Sh RETURN VALUES
 .Fn BIO_push
@@ -163,3 +172,7 @@ and the new chain will be
 data can be written to
 .Sy md1
 as before.
+.Sh SEE ALSO
+.Xr BIO_find_type 3 ,
+.Xr BIO_new 3 ,
+.Xr BIO_read 3
diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 29e066614f9..3878d948e16 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.67 2016/12/05 20:30:12 schwarze Exp $
+# $OpenBSD: Makefile,v 1.68 2016/12/06 12:54:19 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -12,7 +12,6 @@ MAN=	\
 	ASN1_generate_nconf.3 \
 	ASN1_time_parse.3 \
 	BF_set_key.3 \
-	BIO.3 \
 	BIO_ctrl.3 \
 	BIO_f_base64.3 \
 	BIO_f_buffer.3 \