various cleanup;

21 files changed, 193 insertions, 200 deletions

diff --git a/lib/libcrypto/man/BIO.3 b/lib/libcrypto/man/BIO.3
index f3a419721fa..89b51720a63 100644
--- a/lib/libcrypto/man/BIO.3
+++ b/lib/libcrypto/man/BIO.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: BIO.3,v 1.3 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: BIO.3,v 1.4 2016/11/07 15:52:47 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 7 2016 $
 .Dt BIO 3
 .Os
 .Sh NAME
@@ -10,14 +10,14 @@
 .In openssl/bio.h
 .Sh DESCRIPTION
 A BIO is an I/O abstraction,
-it hides many of the underlying I/O details from an application.
+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.
+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.
@@ -43,7 +43,6 @@ to the end (normally a source/sink BIO).
 .Xr BIO_f_ssl 3 ,
 .Xr BIO_find_type 3 ,
 .Xr BIO_new 3 ,
-.Xr BIO_new_bio_pair 3 ,
 .Xr BIO_push 3 ,
 .Xr BIO_read 3 ,
 .Xr BIO_s_accept 3 ,
diff --git a/lib/libcrypto/man/BIO_ctrl.3 b/lib/libcrypto/man/BIO_ctrl.3
index 391158bd42e..6557d10730d 100644
--- a/lib/libcrypto/man/BIO_ctrl.3
+++ b/lib/libcrypto/man/BIO_ctrl.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: BIO_ctrl.3,v 1.3 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: BIO_ctrl.3,v 1.4 2016/11/07 15:52:47 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 7 2016 $
 .Dt BIO_CTRL 3
 .Os
 .Sh NAME
@@ -122,16 +122,17 @@
 and
 .Fn BIO_int_ctrl
 are BIO "control" operations taking arguments of various types.
-These functions are not normally called directly,
+These functions are not normally called directly -
 various macros are used instead.
-The standard macros are described below, macros specific to a
-particular type of BIO are described in the specific BIO's manual
-page as well as any special features of the standard calls.
+The standard macros are described below.
+Macros specific to a particular type of BIO
+are described in the specific BIO's manual page
+as well as any special features of the standard calls.
 .Pp
 .Fn BIO_reset
-typically resets a BIO to some initial state, in the case
-of file related BIOs for example it rewinds the file pointer
-to the start of the file.
+typically resets a BIO to some initial state.
+In the case of file related BIOs, for example,
+it rewinds the file pointer to the start of the file.
 .Pp
 .Fn BIO_seek
 resets a file related BIO's (that is file descriptor and
@@ -143,12 +144,12 @@ bytes from start of file.
 returns the current file position of a file related BIO.
 .Pp
 .Fn BIO_flush
-normally writes out any internally buffered data, in some cases
-it is used to signal EOF and that no more data will be written.
+normally writes out any internally buffered data.
+In some cases it is used to signal EOF and that no more data will be written.
 .Pp
 .Fn BIO_eof
-returns 1 if the BIO has read EOF, the precise meaning of
-"EOF" varies according to the BIO type.
+returns 1 if the BIO has read EOF.
+The precise meaning of "EOF" varies according to the BIO type.
 .Pp
 .Fn BIO_set_close
 sets the BIO
@@ -180,7 +181,7 @@ and
 .Fn BIO_ctrl_wpending
 return a
 .Vt size_t
-type and are functions,
+type and are functions.
 .Fn BIO_pending
 and
 .Fn BIO_wpending
@@ -189,7 +190,7 @@ are macros which call
 .Sh RETURN VALUES
 .Fn BIO_reset
 normally returns 1 for success and 0 or -1 for failure.
-File BIOs are an exception, they return 0 for success and -1 for failure.
+File BIOs are an exception, returning 0 for success and -1 for failure.
 .Pp
 .Fn BIO_seek
 and
@@ -203,7 +204,7 @@ always return 0 for success and -1 for failure.
 returns 1 for success and 0 or -1 for failure.
 .Pp
 .Fn BIO_eof
-returns 1 if EOF has been reached 0 otherwise.
+returns 1 if EOF has been reached or 0 otherwise.
 .Pp
 .Fn BIO_set_close
 always returns 1.
@@ -228,7 +229,7 @@ in a similar manner to
 .Fn BIO_write .
 The
 .Fn BIO_should_retry
-call should be used and appropriate action taken is the call fails.
+call should be used and appropriate action taken if the call fails.
 .Pp
 The return values of
 .Fn BIO_pending
@@ -238,7 +239,7 @@ may not reliably determine the amount of pending data in all cases.
 For example in the case of a file BIO some data may be available in the
 .Vt FILE
 structure's internal buffers but it is not possible
-to determine this in a portably way.
+to determine this in a portable way.
 For other types of BIO they may not be supported.
 .Pp
 If they do not internally handle a particular
@@ -246,10 +247,10 @@ If they do not internally handle a particular
 operation, filter BIOs usually pass the operation
 to the next BIO in the chain.
 This often means there is no need to locate the required BIO for
-a particular operation, it can be called on a chain and it will
+a particular operation: it can be called on a chain and it will
 be automatically passed to the relevant BIO.
-However this can cause unexpected results:
-for example no current filter BIOs implement
+However this can cause unexpected results.
+For example no current filter BIOs implement
 .Fn BIO_seek ,
 but this may still succeed if the chain ends
 in a FILE or file descriptor BIO.
diff --git a/lib/libcrypto/man/BIO_f_base64.3 b/lib/libcrypto/man/BIO_f_base64.3
index d86a2e0daa3..5051ad14b89 100644
--- a/lib/libcrypto/man/BIO_f_base64.3
+++ b/lib/libcrypto/man/BIO_f_base64.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: BIO_f_base64.3,v 1.3 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: BIO_f_base64.3,v 1.4 2016/11/07 15:52:47 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 7 2016 $
 .Dt BIO_F_BASE64 3
 .Os
 .Sh NAME
@@ -32,10 +32,10 @@ this is used to flush the final block through the BIO.
 The flag
 .Dv BIO_FLAGS_BASE64_NO_NL
 can be set with
-.Xr BIO_set_flags 3
+.Fn BIO_set_flags
 to encode the data all on one line
 or expect the data to be all on one line.
-.Sh NOTES
+.Pp
 Because of the format of base64 encoding the end of the encoded
 block cannot always be reliably determined.
 .Sh RETURN VALUES
@@ -57,7 +57,7 @@ BIO_flush(b64);
 BIO_free_all(b64);
 .Ed
 .Pp
-Read Base64 encoded data from standard input
+Read Base64-encoded data from standard input
 and write the decoded data to standard output:
 .Bd -literal -offset indent
 BIO *bio, *b64, *bio_out;
@@ -75,8 +75,8 @@ BIO_flush(bio_out);
 BIO_free_all(b64);
 .Ed
 .Sh BUGS
-The ambiguity of EOF in base64 encoded data can cause additional
-data following the base64 encoded block to be misinterpreted.
+The ambiguity of EOF in base64-encoded data can cause additional
+data following the base64-encoded block to be misinterpreted.
 .Pp
 There should be some way of specifying a test that the BIO can perform
 to reliably determine EOF (for example a MIME boundary).
diff --git a/lib/libcrypto/man/BIO_f_buffer.3 b/lib/libcrypto/man/BIO_f_buffer.3
index 785934d5533..c673fe535ed 100644
--- a/lib/libcrypto/man/BIO_f_buffer.3
+++ b/lib/libcrypto/man/BIO_f_buffer.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: BIO_f_buffer.3,v 1.3 2015/11/11 22:14:39 jmc Exp $
+.\"	$OpenBSD: BIO_f_buffer.3,v 1.4 2016/11/07 15:52:47 jmc Exp $
 .\"
-.Dd $Mdocdate: November 11 2015 $
+.Dd $Mdocdate: November 7 2016 $
 .Dt BIO_F_BUFFER 3
 .Os
 .Sh NAME
@@ -72,16 +72,16 @@ bytes of
 If
 .Fa num
 is larger than the current buffer size the buffer is expanded.
-.Sh NOTES
+.Pp
 Buffering BIOs implement
 .Xr BIO_gets 3
 by using
 .Xr BIO_read 3
 operations on the next BIO in the chain.
 By prepending a buffering BIO to a chain
-it is therefore possible to provide
+it is therefore possible to provide the functionality of
 .Xr BIO_gets 3
-functionality if the following BIOs do not support it (for example SSL BIOs).
+if the following BIOs do not support it (for example SSL BIOs).
 .Pp
 Data is only written to the next BIO in the chain
 when the write buffer fills or when
@@ -93,7 +93,7 @@ whenever any pending data should be written
 such as when removing a buffering BIO using
 .Xr BIO_pop 3 .
 .Xr BIO_flush 3
-may need to be retried if the ultimate source/sink BIO is non blocking.
+may need to be retried if the ultimate source/sink BIO is non-blocking.
 .Sh RETURN VALUES
 .Fn BIO_f_buffer
 returns the buffering BIO method.
diff --git a/lib/libcrypto/man/BIO_f_cipher.3 b/lib/libcrypto/man/BIO_f_cipher.3
index 4ecde4f69d9..b6a7cb1ab93 100644
--- a/lib/libcrypto/man/BIO_f_cipher.3
+++ b/lib/libcrypto/man/BIO_f_cipher.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: BIO_f_cipher.3,v 1.3 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: BIO_f_cipher.3,v 1.4 2016/11/07 15:52:47 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 7 2016 $
 .Dt BIO_F_CIPHER 3
 .Os
 .Sh NAME
@@ -83,7 +83,7 @@ with the standard cipher routines to set it up.
 This is useful when
 .Fn BIO_set_cipher
 is not flexible enough for the applications needs.
-.Sh NOTES
+.Pp
 When encrypting,
 .Xr BIO_flush 3
 must be called to flush the final block through the BIO.
diff --git a/lib/libcrypto/man/BIO_f_md.3 b/lib/libcrypto/man/BIO_f_md.3
index 3b3f1de329f..8514883943b 100644
--- a/lib/libcrypto/man/BIO_f_md.3
+++ b/lib/libcrypto/man/BIO_f_md.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: BIO_f_md.3,v 1.3 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: BIO_f_md.3,v 1.4 2016/11/07 15:52:47 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 7 2016 $
 .Dt BIO_F_MD 3
 .Os
 .Sh NAME
@@ -80,7 +80,7 @@ macro.
 .Fn BIO_get_md_ctx
 returns the digest BIOs context in
 .Fa mdcp .
-.Sh NOTES
+.Pp
 The context returned by
 .Fn BIO_get_md_ctx
 can be used in calls to
@@ -112,10 +112,10 @@ then this can be done by prepending a buffering BIO.
 .Pp
 Before OpenSSL 1.0.0 the call to
 .Fn BIO_get_md_ctx
-would only work if the BIO had been initialized for example by calling
+would only work if the BIO had been initialized, for example by calling
 .Fn BIO_set_md .
 In OpenSSL 1.0.0 and later the context is always returned
-and the BIO is state is set to initialized.
+and the state of the BIO is set to initialized.
 This allows applications to initialize the context externally
 if the standard calls such as
 .Fn BIO_set_md
@@ -130,7 +130,7 @@ and
 .Fn BIO_get_md_ctx
 return 1 for success and 0 for failure.
 .Sh EXAMPLES
-The following example creates a BIO chain containing an SHA1 and MD5
+The following example creates a BIO chain containing an SHA-1 and MD5
 digest BIO and passes the string "Hello World" through it.
 Error checking has been omitted for clarity.
 .Bd -literal -offset 2n
@@ -198,7 +198,7 @@ BIO_free_all(bio);
 .Sh BUGS
 The lack of support for
 .Xr BIO_puts 3
-and the non standard behaviour of
+and the non-standard behaviour of
 .Xr BIO_gets 3
 could be regarded as anomalous.
 It could be argued that
diff --git a/lib/libcrypto/man/BIO_f_null.3 b/lib/libcrypto/man/BIO_f_null.3
index 236d233e57e..8e1e58f159e 100644
--- a/lib/libcrypto/man/BIO_f_null.3
+++ b/lib/libcrypto/man/BIO_f_null.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: BIO_f_null.3,v 1.3 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: BIO_f_null.3,v 1.4 2016/11/07 15:52:47 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 7 2016 $
 .Dt BIO_F_NULL 3
 .Os
 .Sh NAME
@@ -16,12 +16,11 @@
 .Fn BIO_f_null
 returns the null filter BIO method.
 This is a filter BIO that does nothing.
+As may be apparent, a null filter BIO is not particularly useful.
 .Pp
 All requests to a null filter BIO are passed through to the next BIO
 in the chain: this means that a BIO chain containing a null filter BIO
 behaves just as though the BIO was not there.
-.Sh NOTES
-As may be apparent, a null filter BIO is not particularly useful.
 .Sh RETURN VALUES
 .Fn BIO_f_null
 returns the null filter BIO method.
diff --git a/lib/libcrypto/man/BIO_find_type.3 b/lib/libcrypto/man/BIO_find_type.3
index 1db2fe85c69..be0e0d0b3d2 100644
--- a/lib/libcrypto/man/BIO_find_type.3
+++ b/lib/libcrypto/man/BIO_find_type.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: BIO_find_type.3,v 1.3 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: BIO_find_type.3,v 1.4 2016/11/07 15:52:47 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 7 2016 $
 .Dt BIO_FIND_TYPE 3
 .Os
 .Sh NAME
@@ -86,14 +86,6 @@ returns the next BIO in a chain.
 .Fn BIO_method_type
 returns the type of the BIO
 .Fa b .
-.Sh NOTES
-.Fn BIO_next
-was added to OpenSSL 0.9.6 to provide a 'clean' way to traverse a BIO
-chain or find multiple matches using
-.Fn BIO_find_type .
-Previous versions had to use:
-.Pp
-.Dl next = bio->next_bio;
 .Sh EXAMPLES
 Traverse a chain looking for digest BIOs:
 .Bd -literal -offset 2n
diff --git a/lib/libcrypto/man/BIO_new.3 b/lib/libcrypto/man/BIO_new.3
index b08de9c6504..71385986747 100644
--- a/lib/libcrypto/man/BIO_new.3
+++ b/lib/libcrypto/man/BIO_new.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: BIO_new.3,v 1.3 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: BIO_new.3,v 1.4 2016/11/07 15:52:47 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 7 2016 $
 .Dt BIO_NEW 3
 .Os
 .Sh NAME
@@ -43,7 +43,7 @@ function returns a new BIO using method
 sets the method of an already existing BIO.
 .Pp
 .Fn BIO_free
-frees up a single BIO,
+frees up a single BIO;
 .Fn BIO_vfree
 also frees up a single BIO, but it does not return a value.
 Calling
@@ -59,22 +59,7 @@ descriptions.
 frees up an entire BIO chain.
 It does not halt if an error occurs
 freeing up an individual BIO in the chain.
-.Sh RETURN VALUES
-.Fn BIO_new
-returns a newly created BIO or
-.Dv NULL
-if the call fails.
 .Pp
-.Fn BIO_set
-and
-.Fn BIO_free
-return 1 for success and 0 for failure.
-.Pp
-.Fn BIO_free_all
-and
-.Fn BIO_vfree
-do not return values.
-.Sh NOTES
 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
@@ -100,6 +85,21 @@ a source/sink BIO is normally called
 .Fn BIO_s_*
 and a filter BIO
 .Fn BIO_f_* .
+.Sh RETURN VALUES
+.Fn BIO_new
+returns a newly created BIO or
+.Dv NULL
+if the call fails.
+.Pp
+.Fn BIO_set
+and
+.Fn BIO_free
+return 1 for success and 0 for failure.
+.Pp
+.Fn BIO_free_all
+and
+.Fn BIO_vfree
+do not return values.
 .Sh EXAMPLES
 Create a memory BIO:
 .Pp
diff --git a/lib/libcrypto/man/BIO_push.3 b/lib/libcrypto/man/BIO_push.3
index 0357a8446cf..eff3619fb3c 100644
--- a/lib/libcrypto/man/BIO_push.3
+++ b/lib/libcrypto/man/BIO_push.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: BIO_push.3,v 1.2 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: BIO_push.3,v 1.3 2016/11/07 15:52:47 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 7 2016 $
 .Dt BIO_PUSH 3
 .Os
 .Sh NAME
@@ -35,22 +35,14 @@ from a chain and returns the next BIO in the chain, or
 .Dv NULL
 if there is no next BIO.
 The removed BIO then becomes a single BIO with no association with the
-original chain, it can thus be freed or attached to a different chain.
-.Sh RETURN VALUES
-.Fn BIO_push
-returns the beginning of the chain,
-.Fa b .
+original chain.
+it can thus be freed or attached to a different chain.
 .Pp
-.Fn BIO_pop
-returns the next BIO in the chain, or
-.Dv NULL
-if there is no next BIO.
-.Sh NOTES
 The names of these functions are perhaps a little misleading.
 .Fn BIO_push
 joins two BIO chains whereas
 .Fn BIO_pop
-deletes a single BIO from a chain,
+deletes a single BIO from a chain;
 the deleted BIO does not need to be at the end of a chain.
 .Pp
 The process of calling
@@ -60,6 +52,15 @@ and
 on a BIO may have additional consequences:
 a control call is made to the affected BIOs.
 Any effects will be noted in the descriptions of individual BIOs.
+.Sh RETURN VALUES
+.Fn BIO_push
+returns the beginning of the chain,
+.Fa b .
+.Pp
+.Fn BIO_pop
+returns the next BIO in the chain, or
+.Dv NULL
+if there is no next BIO.
 .Sh EXAMPLES
 For these examples suppose
 .Sy md1
@@ -67,7 +68,7 @@ and
 .Sy md2
 are digest BIOs,
 .Sy b64
-is a base64 BIO and
+is a Base64 BIO and
 .Sy f
 is a file BIO.
 .Pp
@@ -92,17 +93,14 @@ by
 .Sy md1
 and
 .Sy md2 ,
-.Sy base64
-encoded and written to
+Base64-encoded and written to
 .Sy f .
 .Pp
 It should be noted that reading causes data to pass
-in the reverse direction, that is data is read from
+in the reverse direction.
+That is, data is read from
 .Sy f ,
-base64
-.Sy decoded
-and digested
-by
+Base64-decoded and digested by
 .Sy md1
 and
 .Sy md2 .
@@ -113,7 +111,7 @@ If this call is made:
 The call will return
 .Sy b64
 and the new chain will be
-.Sy md1-b64-f Ns ;
+.Sy md1-b64-f ;
 data can be written to
 .Sy md1
 as before.
diff --git a/lib/libcrypto/man/BIO_read.3 b/lib/libcrypto/man/BIO_read.3
index 94a4fb14615..f19c31ecab6 100644
--- a/lib/libcrypto/man/BIO_read.3
+++ b/lib/libcrypto/man/BIO_read.3
@@ -1,12 +1,12 @@
-.\"	$OpenBSD: BIO_read.3,v 1.2 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: BIO_read.3,v 1.3 2016/11/07 15:52:47 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 7 2016 $
 .Dt BIO_READ 3
 .Os
 .Sh NAME
 .Nm BIO_read ,
-.Nm BIO_write ,
 .Nm BIO_gets ,
+.Nm BIO_write ,
 .Nm BIO_puts
 .Nd BIO I/O functions
 .Sh SYNOPSIS
@@ -69,17 +69,6 @@ attempts to write a null terminated string
 .Fa buf
 to BIO
 .Fa b .
-.Sh RETURN VALUES
-All these functions return either the amount of data successfully
-read or written (if the return value is positive) or that no data
-was successfully read or written if the result is 0 or -1.
-If the return value is -2, then the operation is not implemented
-in the specific BIO type.
-.Sh NOTES
-A 0 or -1 return is not necessarily an indication of an error.
-In particular when the source/sink is non-blocking or of a certain type
-it may merely be an indication that no data is currently available and that
-the application should retry the operation later.
 .Pp
 One technique sometimes used with blocking sockets
 is to use a system call (such as
@@ -100,7 +89,7 @@ can cause several reads (and writes in the case of SSL BIOs)
 on the underlying I/O structure and may block as a result.
 Instead
 .Xr select 2
-(or equivalent) should be combined with non blocking I/O
+(or equivalent) should be combined with non-blocking I/O
 so successive reads will request a retry instead of blocking.
 .Pp
 See
@@ -113,5 +102,16 @@ function is not supported by a BIO then it is possible to
 work around this by adding a buffering BIO
 .Xr BIO_f_buffer 3
 to the chain.
+.Sh RETURN VALUES
+All these functions return either the amount of data successfully
+read or written (if the return value is positive) or that no data
+was successfully read or written if the result is 0 or -1.
+If the return value is -2, then the operation is not implemented
+in the specific BIO type.
+.Pp
+A 0 or -1 return is not necessarily an indication of an error.
+In particular when the source/sink is non-blocking or of a certain type
+it may merely be an indication that no data is currently available and that
+the application should retry the operation later.
 .Sh SEE ALSO
 .Xr BIO_should_retry 3
diff --git a/lib/libcrypto/man/BIO_s_accept.3 b/lib/libcrypto/man/BIO_s_accept.3
index 766d86e2a43..3cfb574977a 100644
--- a/lib/libcrypto/man/BIO_s_accept.3
+++ b/lib/libcrypto/man/BIO_s_accept.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: BIO_s_accept.3,v 1.2 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: BIO_s_accept.3,v 1.3 2016/11/07 15:52:47 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 7 2016 $
 .Dt BIO_S_ACCEPT 3
 .Os
 .Sh NAME
@@ -63,7 +63,9 @@
 .Sh DESCRIPTION
 .Fn BIO_s_accept
 returns the accept BIO method.
-This is a wrapper round the platform's TCP/IP socket accept routines.
+This is a wrapper round the platform's TCP/IP socket
+.Xr accept 2
+routines.
 .Pp
 Using accept BIOs, TCP/IP connections can be accepted
 and data transferred using only BIO routines.
@@ -81,12 +83,12 @@ but not
 .Xr BIO_gets 3 .
 .Pp
 If the close flag is set on an accept BIO, then any active
-connection on that chain is shutdown and the socket closed when
+connection on that chain is shut down and the socket closed when
 the BIO is freed.
 .Pp
 Calling
 .Xr BIO_reset 3
-on a accept BIO will close any active connection and reset the BIO
+on an accept BIO will close any active connection and reset the BIO
 into a state where it awaits another incoming connection.
 .Pp
 .Xr BIO_get_fd 3
@@ -108,13 +110,13 @@ is the interface to use and
 .Ar port
 is the port.
 Either or both values can be
-.Qq *
+.Qq * ,
 which is interpreted as meaning any interface or port respectively.
 .Ar port
 has the same syntax as the port specified in
 .Xr BIO_set_conn_port 3
 for connect BIOs.
-It can be a numerical port string or a string to lookup using
+It can be a numerical port string or a string to look up using
 .Xr getservbyname 3
 and a string table.
 .Pp
@@ -130,7 +132,7 @@ It creates a new accept BIO with port
 .Fn BIO_set_nbio_accept
 sets the accept socket to blocking mode (the default) if
 .Fa n
-is 0 or non blocking mode if
+is 0 or non-blocking mode if
 .Fa n
 is 1.
 .Pp
@@ -139,7 +141,7 @@ can be used to set a chain of BIOs which will be duplicated
 and prepended to the chain when an incoming connection is received.
 This is useful if, for example, a buffering or SSL BIO
 is required for each connection.
-The chain of BIOs must not be freed after this call,
+The chain of BIOs must not be freed after this call -
 they will be automatically freed when the accept BIO is freed.
 .Pp
 .Fn BIO_set_bind_mode
@@ -162,11 +164,11 @@ then a second attempt is made using
 .Pp
 .Fn BIO_do_accept
 serves two purposes.
-When it is first called, after the accept BIO has been setup,
+When it is first called, after the accept BIO has been set up,
 it will attempt to create the accept socket and bind an address to it.
 Second and subsequent calls to
 .Fn BIO_do_accept
-will await an incoming connection, or request a retry in non blocking mode.
+will await an incoming connection, or request a retry in non-blocking mode.
 .Sh NOTES
 When an accept BIO is at the end of a chain, it will await an
 incoming connection before processing I/O calls.
@@ -181,8 +183,8 @@ socket will await an incoming connection then perform I/O on it.
 .Pp
 If any additional BIOs have been set using
 .Fn BIO_set_accept_bios ,
-then they are placed between the socket and the accept BIO,
-that is the chain will be accept->otherbios->socket.
+then they are placed between the socket and the accept BIO;
+that is, the chain will be accept->otherbios->socket.
 .Pp
 If a server wishes to process multiple connections (as is normally
 the case), then the accept BIO must be made available for further
diff --git a/lib/libcrypto/man/BIO_s_bio.3 b/lib/libcrypto/man/BIO_s_bio.3
index c7d602990e1..ccd3bf8ef9b 100644
--- a/lib/libcrypto/man/BIO_s_bio.3
+++ b/lib/libcrypto/man/BIO_s_bio.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: BIO_s_bio.3,v 1.4 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: BIO_s_bio.3,v 1.5 2016/11/07 15:52:47 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 7 2016 $
 .Dt BIO_S_BIO 3
 .Os
 .Sh NAME
@@ -79,7 +79,7 @@ have all the data processed by the chain under application control.
 .Pp
 One typical use of BIO pairs is
 to place TLS/SSL I/O under application control.
-This can be used when the application wishes to use a non standard
+This can be used when the application wishes to use a non-standard
 transport for TLS/SSL or the normal socket routines are inappropriate.
 .Pp
 Calls to
@@ -147,7 +147,7 @@ does not check whether
 .Fa bio1
 or
 .Fa bio2
-do point to some other BIO, the values are overwritten,
+point to some other BIO; the values are overwritten and
 .Xr BIO_free 3
 is not called.
 .Pp
@@ -186,19 +186,7 @@ never returns an amount larger than that returned by
 can also be used to reset the value returned by
 .Fn BIO_get_read_request
 to zero.
-.Sh RETURN VALUES
-.Fn BIO_new_bio_pair
-returns 1 on success, with the new BIOs available in
-.Fa bio1
-and
-.Fa bio2 ,
-or 0 on failure, with NULL pointers stored into the locations for
-.Fa bio1
-and
-.Fa bio2 .
-Check the error stack for more information.
-.\" XXX More return values need to be added here.
-.Sh NOTES
+.Pp
 Both halves of a BIO pair should be freed.
 Even if one half is implicitly freed due to a
 .Xr BIO_free_all 3
@@ -233,12 +221,24 @@ will be true.
 If the application then waits for data to become available
 on the underlying transport before flushing the write buffer,
 it will never succeed because the request was never sent.
+.Sh RETURN VALUES
+.Fn BIO_new_bio_pair
+returns 1 on success, with the new BIOs available in
+.Fa bio1
+and
+.Fa bio2 ,
+or 0 on failure, with NULL pointers stored into the locations for
+.Fa bio1
+and
+.Fa bio2 .
+Check the error stack for more information.
+.\" XXX More return values need to be added here.
 .Sh EXAMPLES
 The BIO pair can be used to have full control
 over the network access of an application.
 The application can call
 .Xr select 2
-on the socket as required without having to go through the SSL-interface.
+on the socket as required without having to go through the SSL interface.
 .Bd -literal -offset 2n
 BIO *internal_bio, *network_bio;
 \&...
diff --git a/lib/libcrypto/man/BIO_s_connect.3 b/lib/libcrypto/man/BIO_s_connect.3
index e0da157e125..cc2790fca61 100644
--- a/lib/libcrypto/man/BIO_s_connect.3
+++ b/lib/libcrypto/man/BIO_s_connect.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: BIO_s_connect.3,v 1.2 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: BIO_s_connect.3,v 1.3 2016/11/07 15:52:47 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 7 2016 $
 .Dt BIO_S_CONNECT 3
 .Os
 .Sh NAME
@@ -106,8 +106,8 @@ into a state where it can connect to the same host again.
 places the underlying socket in
 .Fa c
 if it is not
-.Dv NULL ,
-it also returns the socket.
+.Dv NULL
+and also returns the socket.
 If
 .Fa c
 is not
@@ -151,7 +151,7 @@ and
 .Fn BIO_set_conn_ip
 sets the IP address to
 .Fa ip
-using binary form, that is four bytes specifying the IP address
+using binary form i.e. four bytes specifying the IP address
 in big-endian form.
 .Pp
 .Fn BIO_set_conn_int_port
@@ -179,19 +179,19 @@ returns the port as an
 .Vt int .
 .Pp
 .Fn BIO_set_nbio
-sets the non blocking I/O flag to
+sets the non-blocking I/O flag to
 .Fa n .
 If
 .Fa n
 is zero then blocking I/O is set.
 If
 .Fa n
-is 1 then non blocking I/O is set.
+is 1 then non-blocking I/O is set.
 Blocking I/O is the default.
 The call to
 .Fn BIO_set_nbio
 should be made before the connection is established
-because non blocking I/O is set during the connect process.
+because non-blocking I/O is set during the connect process.
 .Pp
 .Fn BIO_new_connect
 combines
@@ -209,10 +209,10 @@ A zero or negative value is returned if the connection
 could not be established.
 The call
 .Xr BIO_should_retry 3
-should be used for non blocking connect BIOs
+should be used for non-blocking connect BIOs
 to determine if the call should be retried.
-.Sh NOTES
-If blocking I/O is set then a non positive return value from any
+.Pp
+If blocking I/O is set then a non-positive return value from any
 I/O call is caused by an error condition, although a zero return
 will normally mean that the connection was closed.
 .Pp
@@ -244,7 +244,7 @@ from other I/O processing.
 If non-blocking I/O is set,
 then retries will be requested as appropriate.
 .Pp
-It addition to
+In addition to
 .Xr BIO_should_read 3
 and
 .Xr BIO_should_write 3
diff --git a/lib/libcrypto/man/BIO_s_fd.3 b/lib/libcrypto/man/BIO_s_fd.3
index 591b25d2f27..9365eaf973e 100644
--- a/lib/libcrypto/man/BIO_s_fd.3
+++ b/lib/libcrypto/man/BIO_s_fd.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: BIO_s_fd.3,v 1.3 2016/11/06 16:43:53 schwarze Exp $
+.\"	$OpenBSD: BIO_s_fd.3,v 1.4 2016/11/07 15:52:47 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 7 2016 $
 .Dt BIO_S_FD 3
 .Os
 .Sh NAME
@@ -91,7 +91,7 @@ returns a file descriptor BIO using
 .Fa fd
 and
 .Fa close_flag .
-.Sh NOTES
+.Pp
 The behaviour of
 .Xr BIO_read 3
 and
@@ -101,7 +101,7 @@ depends on the behavior of the platform's
 and
 .Xr write 2
 calls on the descriptor.
-If the underlying file descriptor is in a non blocking mode,
+If the underlying file descriptor is in a non-blocking mode,
 then the BIO will behave in the manner described in the
 .Xr BIO_read 3
 and
diff --git a/lib/libcrypto/man/BIO_s_file.3 b/lib/libcrypto/man/BIO_s_file.3
index 9676e4f0a50..47d5806d7e9 100644
--- a/lib/libcrypto/man/BIO_s_file.3
+++ b/lib/libcrypto/man/BIO_s_file.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: BIO_s_file.3,v 1.2 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: BIO_s_file.3,v 1.3 2016/11/07 15:52:47 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 7 2016 $
 .Dt BIO_S_FILE 3
 .Os
 .Sh NAME
@@ -13,7 +13,7 @@
 .Nm BIO_write_filename ,
 .Nm BIO_append_filename ,
 .Nm BIO_rw_filename
-.Nd FILE bio
+.Nd FILE BIO
 .Sh SYNOPSIS
 .In openssl/bio.h
 .Ft BIO_METHOD *
@@ -153,7 +153,7 @@ set the file BIO
 to use file
 .Fa name
 for reading, writing, append or read write respectively.
-.Sh NOTES
+.Pp
 When wrapping stdout, stdin, or stderr, the underlying stream
 should not normally be closed, so the
 .Dv BIO_NOCLOSE
@@ -247,4 +247,4 @@ The return value for
 .Xr fseek 3
 is 0 for success or -1 if an error occurred.
 This differs from other types of BIO which will typically return
-1 for success and a non positive value if an error occurred.
+1 for success and a non-positive value if an error occurred.
diff --git a/lib/libcrypto/man/BIO_s_mem.3 b/lib/libcrypto/man/BIO_s_mem.3
index 1512ebbb777..1fff26442c6 100644
--- a/lib/libcrypto/man/BIO_s_mem.3
+++ b/lib/libcrypto/man/BIO_s_mem.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: BIO_s_mem.3,v 1.2 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: BIO_s_mem.3,v 1.3 2016/11/07 15:52:47 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 7 2016 $
 .Dt BIO_S_MEM 3
 .Os
 .Sh NAME
@@ -86,7 +86,7 @@ when it is empty.
 If
 .Fa v
 is zero, then an empty memory BIO will return EOF:
-It will return zero and
+it will return zero and
 .Fn BIO_should_retry
 will be false.
 If
@@ -111,8 +111,8 @@ It is implemented as a macro.
 sets the internal BUF_MEM structure to
 .Fa bm
 and sets the close flag to
-.Fa c ,
-that is
+.Fa c .
+That is,
 .Fa c
 should be either
 .Dv BIO_CLOSE
@@ -147,7 +147,7 @@ it is
 .Em not
 copied first, so the supplied area of memory must be unchanged
 until the BIO is freed.
-.Sh NOTES
+.Pp
 Writes to memory BIOs will always succeed if memory is available:
 their size can grow indefinitely.
 .Pp
diff --git a/lib/libcrypto/man/BIO_s_null.3 b/lib/libcrypto/man/BIO_s_null.3
index 5910bd5ce17..c98d2affd36 100644
--- a/lib/libcrypto/man/BIO_s_null.3
+++ b/lib/libcrypto/man/BIO_s_null.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: BIO_s_null.3,v 1.2 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: BIO_s_null.3,v 1.3 2016/11/07 15:52:47 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 7 2016 $
 .Dt BIO_S_NULL 3
 .Os
 .Sh NAME
@@ -16,12 +16,12 @@
 .Fn BIO_s_null
 returns the null sink BIO method.
 Data written to the null sink is discarded, reads return EOF.
-.Sh NOTES
+.Pp
 A null sink BIO behaves in a similar manner to the
 .Xr null 4
 device.
 .Pp
-A null bio can be placed on the end of a chain to discard any data
+A null BIO can be placed on the end of a chain to discard any data
 passed through it.
 .Pp
 A null sink is useful if, for example, an application wishes
diff --git a/lib/libcrypto/man/BIO_s_socket.3 b/lib/libcrypto/man/BIO_s_socket.3
index 8cc0243066c..29d3cf83b02 100644
--- a/lib/libcrypto/man/BIO_s_socket.3
+++ b/lib/libcrypto/man/BIO_s_socket.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: BIO_s_socket.3,v 1.3 2016/11/06 16:43:53 schwarze Exp $
+.\"	$OpenBSD: BIO_s_socket.3,v 1.4 2016/11/07 15:52:47 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 7 2016 $
 .Dt BIO_S_SOCKET 3
 .Os
 .Sh NAME
@@ -40,7 +40,7 @@ returns a socket BIO using
 .Fa sock
 and
 .Fa close_flag .
-.Sh NOTES
+.Pp
 Socket BIOs also support any relevant functionality of file descriptor BIOs.
 .Pp
 The reason for having separate file descriptor and socket BIOs
diff --git a/lib/libcrypto/man/BIO_set_callback.3 b/lib/libcrypto/man/BIO_set_callback.3
index 68ca2780f86..62b7b3773bd 100644
--- a/lib/libcrypto/man/BIO_set_callback.3
+++ b/lib/libcrypto/man/BIO_set_callback.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: BIO_set_callback.3,v 1.2 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: BIO_set_callback.3,v 1.3 2016/11/07 15:52:47 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 7 2016 $
 .Dt BIO_SET_CALLBACK 3
 .Os
 .Sh NAME
@@ -38,7 +38,7 @@
 .Fn BIO_set_callback
 and
 .Fn BIO_get_callback
-set and retrieve the BIO callback, they are both macros.
+set and retrieve the BIO callback; they are both macros.
 The callback is called during most high level BIO operations.
 It can be used for debugging purposes to trace operations on a BIO
 or to modify its operation.
@@ -77,8 +77,8 @@ The meaning of the arguments
 and
 .Fa argl
 depends on the value of
-.Fa oper ,
-that is the operation being performed.
+.Fa oper
+(i.e. the operation being performed).
 .Pp
 .Fa retvalue
 is the return value that would be returned to the application
@@ -127,5 +127,6 @@ after.
 .Sh EXAMPLES
 The
 .Fn BIO_debug_callback
-function is a good example, its source is in the file
+function is a good example.
+Its source is in the file
 .Pa crypto/bio/bio_cb.c .
diff --git a/lib/libcrypto/man/BIO_should_retry.3 b/lib/libcrypto/man/BIO_should_retry.3
index c06e907235a..f512e08b891 100644
--- a/lib/libcrypto/man/BIO_should_retry.3
+++ b/lib/libcrypto/man/BIO_should_retry.3
@@ -1,6 +1,6 @@
-.\"	$OpenBSD: BIO_should_retry.3,v 1.2 2016/11/06 15:52:50 jmc Exp $
+.\"	$OpenBSD: BIO_should_retry.3,v 1.3 2016/11/07 15:52:47 jmc Exp $
 .\"
-.Dd $Mdocdate: November 6 2016 $
+.Dd $Mdocdate: November 7 2016 $
 .Dt BIO_SHOULD_RETRY 3
 .Os
 .Sh NAME
@@ -9,6 +9,7 @@
 .Nm BIO_should_write ,
 .Nm BIO_should_io_special ,
 .Nm BIO_retry_type ,
+.Nm BIO_should_retry ,
 .Nm BIO_get_retry_BIO ,
 .Nm BIO_get_retry_reason
 .Nd BIO retry functions
@@ -58,8 +59,8 @@ is true if the cause of the condition is that a BIO needs to read data.
 is true if the cause of the condition is that a BIO needs to write data.
 .Pp
 .Fn BIO_should_io_special
-is true if some "special" condition, that is a reason other than
-reading or writing, is the cause of the condition.
+is true if some "special" condition
+(i.e. a reason other than reading or writing) is the cause of the condition.
 .Pp
 .Fn BIO_retry_type
 returns a mask of the cause of a retry condition consisting of the values
@@ -82,7 +83,7 @@ depends on the type of BIO that resulted in this condition.
 returns the reason for a special condition
 if passed the relevant BIO, for example as returned by
 .Fn BIO_get_retry_BIO .
-.Sh NOTES
+.Pp
 If
 .Fn BIO_should_retry
 returns false, then the precise "error condition" depends on
@@ -114,7 +115,7 @@ or avoid this situation by setting
 .Dv SSL_MODE_AUTO_RETRY
 on the underlying SSL structure.
 .Pp
-While an application may retry a failed non blocking call immediately,
+While an application may retry a failed non-blocking call immediately,
 this is likely to be very inefficient because the call will fail
 repeatedly until data can be processed or is available.
 An application will normally wait until the necessary condition
@@ -127,7 +128,7 @@ is true then a call to
 .Xr select 2
 may be made to wait until data is available
 and then retry the BIO operation.
-By combining the retry conditions of several non blocking BIOs in a single
+By combining the retry conditions of several non-blocking BIOs in a single
 .Xr select 2
 call it is possible to service several BIOs in a single thread,
 though the performance may be poor if SSL BIOs are present because
@@ -136,12 +137,12 @@ long delays can occur during the initial handshake process.
 It is possible for a BIO to block indefinitely if the underlying I/O
 structure cannot process or return any data.
 This depends on the behaviour of the platforms I/O functions.
-This is often not desirable: one solution is to use non blocking I/O
+This is often not desirable: one solution is to use non-blocking I/O
 and use a timeout on the
 .Xr select 2
 (or equivalent) call.
 .Sh BUGS
-The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O:
+The OpenSSL ASN.1 functions cannot gracefully deal with non-blocking I/O:
 they cannot retry after a partial read or write.
-This is usually worked around by only passing the relevant data to ASN1
+This is usually worked around by only passing the relevant data to ASN.1
 functions when the entire structure can be read or written.