From: schwarze <schwarze@openbsd.org>
Date: Tue, 11 Apr 2023 16:58:43 +0000 (+0000)
Subject: Document the RETURN VALUES of BIO_method_type(3) and BIO_method_name(3)
X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=eae3c81d70fa5e5d80517463d64c419bce6b3d36;p=openbsd

Document the RETURN VALUES of BIO_method_type(3) and BIO_method_name(3)
for the various BIO types.
---

diff --git a/lib/libcrypto/man/BIO_f_base64.3 b/lib/libcrypto/man/BIO_f_base64.3
index 5e0d4b8aea7..6054c7c7388 100644
--- a/lib/libcrypto/man/BIO_f_base64.3
+++ b/lib/libcrypto/man/BIO_f_base64.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: BIO_f_base64.3,v 1.12 2022/12/07 17:17:29 tb Exp $
+.\"	$OpenBSD: BIO_f_base64.3,v 1.13 2023/04/11 16:58:43 schwarze Exp $
 .\"	OpenSSL fc1d88f0 Wed Jul 2 22:42:40 2014 -0400
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -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 7 2022 $
+.Dd $Mdocdate: April 11 2023 $
 .Dt BIO_F_BASE64 3
 .Os
 .Sh NAME
@@ -87,6 +87,15 @@ BIO_set_flags(b64, BIO_FLAGS_BASE64_NO_NL);
 .Sh RETURN VALUES
 .Fn BIO_f_base64
 returns the base64 BIO method.
+.Pp
+When called on a base64 BIO object,
+.Xr BIO_method_type 3
+returns the constant
+.Dv BIO_TYPE_BASE64
+and
+.Xr BIO_method_name 3
+returns a pointer to the static string
+.Qq base64 encoding .
 .Sh EXAMPLES
 Base64 encode the string "hello, world\en"
 and write the result to standard output:
diff --git a/lib/libcrypto/man/BIO_f_buffer.3 b/lib/libcrypto/man/BIO_f_buffer.3
index b84bb944525..9ac2f4de347 100644
--- a/lib/libcrypto/man/BIO_f_buffer.3
+++ b/lib/libcrypto/man/BIO_f_buffer.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BIO_f_buffer.3,v 1.13 2022/12/23 17:27:53 schwarze Exp $
+.\" $OpenBSD: BIO_f_buffer.3,v 1.14 2023/04/11 16:58:43 schwarze Exp $
 .\" full merge up to OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -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 23 2022 $
+.Dd $Mdocdate: April 11 2023 $
 .Dt BIO_F_BUFFER 3
 .Os
 .Sh NAME
@@ -174,6 +174,15 @@ original BIO object to the new one.
 .Fn BIO_f_buffer
 returns the buffering BIO method.
 .Pp
+When called on a buffering BIO object,
+.Xr BIO_method_type 3
+returns the constant
+.Dv BIO_TYPE_BUFFER
+and
+.Xr BIO_method_name 3
+returns a pointer to the static string
+.Qq buffer .
+.Pp
 .Fn BIO_get_buffer_num_lines
 returns the number of lines buffered (may be 0).
 .Pp
diff --git a/lib/libcrypto/man/BIO_f_cipher.3 b/lib/libcrypto/man/BIO_f_cipher.3
index 794166687a3..56bd27c0d92 100644
--- a/lib/libcrypto/man/BIO_f_cipher.3
+++ b/lib/libcrypto/man/BIO_f_cipher.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BIO_f_cipher.3,v 1.13 2022/12/18 19:35:36 schwarze Exp $
+.\" $OpenBSD: BIO_f_cipher.3,v 1.14 2023/04/11 16:58:43 schwarze Exp $
 .\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -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 18 2022 $
+.Dd $Mdocdate: April 11 2023 $
 .Dt BIO_F_CIPHER 3
 .Os
 .Sh NAME
@@ -161,6 +161,16 @@ by preceding the cipher BIO with a buffering BIO.
 .Sh RETURN VALUES
 .Fn BIO_f_cipher
 returns the cipher BIO method.
+.Pp
+When called on a cipher BIO object,
+.Xr BIO_method_type 3
+returns the constant
+.Dv BIO_TYPE_CIPHER
+and
+.Xr BIO_method_name 3
+returns a pointer to the static string
+.Qq cipher .
+.Pp
 .Fn BIO_set_cipher
 returns 1 on success and 0 on error.
 .Pp
diff --git a/lib/libcrypto/man/BIO_f_md.3 b/lib/libcrypto/man/BIO_f_md.3
index d98111f459c..091995dc1b7 100644
--- a/lib/libcrypto/man/BIO_f_md.3
+++ b/lib/libcrypto/man/BIO_f_md.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BIO_f_md.3,v 1.12 2022/12/18 19:35:36 schwarze Exp $
+.\" $OpenBSD: BIO_f_md.3,v 1.13 2023/04/11 16:58:43 schwarze Exp $
 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -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 18 2022 $
+.Dd $Mdocdate: April 11 2023 $
 .Dt BIO_F_MD 3
 .Os
 .Sh NAME
@@ -181,6 +181,15 @@ are not sufficiently flexible.
 .Fn BIO_f_md
 returns the digest BIO method.
 .Pp
+When called on a message digest BIO object,
+.Xr BIO_method_type 3
+returns the constant
+.Dv BIO_TYPE_MD
+and
+.Xr BIO_method_name 3
+returns a pointer to the static string
+.Qq message digest .
+.Pp
 .Fn BIO_set_md ,
 .Fn BIO_get_md ,
 and
diff --git a/lib/libcrypto/man/BIO_f_null.3 b/lib/libcrypto/man/BIO_f_null.3
index 4944ced3a40..687d991b525 100644
--- a/lib/libcrypto/man/BIO_f_null.3
+++ b/lib/libcrypto/man/BIO_f_null.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BIO_f_null.3,v 1.11 2022/12/23 16:59:39 schwarze Exp $
+.\" $OpenBSD: BIO_f_null.3,v 1.12 2023/04/11 16:58:43 schwarze Exp $
 .\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -48,7 +48,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 23 2022 $
+.Dd $Mdocdate: April 11 2023 $
 .Dt BIO_F_NULL 3
 .Os
 .Sh NAME
@@ -80,6 +80,17 @@ and any attempt to do so fails and returns
 .Sh RETURN VALUES
 .Fn BIO_f_null
 returns the null filter BIO method.
+.Pp
+When called on a null filter BIO object,
+.Xr BIO_method_type 3
+returns the constant
+.Dv BIO_TYPE_NULL_FILTER
+and
+.Xr BIO_method_name 3
+returns a pointer to the static string
+.Qq NULL filter ,
+not to be confused with a NUL string nor with a
+.Dv NULL pointer .
 .Sh SEE ALSO
 .Xr BIO_new 3
 .Sh HISTORY
diff --git a/lib/libcrypto/man/BIO_s_accept.3 b/lib/libcrypto/man/BIO_s_accept.3
index 810d4e2df17..ffbcccc7965 100644
--- a/lib/libcrypto/man/BIO_s_accept.3
+++ b/lib/libcrypto/man/BIO_s_accept.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: BIO_s_accept.3,v 1.13 2022/03/31 17:30:05 naddy Exp $
+.\"	$OpenBSD: BIO_s_accept.3,v 1.14 2023/04/11 16:58:43 schwarze Exp $
 .\"	OpenSSL c03726ca Thu Aug 27 12:28:08 2015 -0400
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -48,7 +48,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: March 31 2022 $
+.Dd $Mdocdate: April 11 2023 $
 .Dt BIO_S_ACCEPT 3
 .Os
 .Sh NAME
@@ -281,6 +281,15 @@ and
 .Fn BIO_do_accept
 are macros.
 .Sh RETURN VALUES
+When called on an accept BIO object,
+.Xr BIO_method_type 3
+returns the constant
+.Dv BIO_TYPE_ACCEPT
+and
+.Xr BIO_method_name 3
+returns a pointer to the static string
+.Qq socket accept .
+.Pp
 .Fn BIO_do_accept ,
 .Fn BIO_set_accept_port ,
 .Fn BIO_set_nbio_accept ,
diff --git a/lib/libcrypto/man/BIO_s_bio.3 b/lib/libcrypto/man/BIO_s_bio.3
index 227828e2f99..d009b3d3744 100644
--- a/lib/libcrypto/man/BIO_s_bio.3
+++ b/lib/libcrypto/man/BIO_s_bio.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BIO_s_bio.3,v 1.16 2022/12/21 15:08:37 schwarze Exp $
+.\" $OpenBSD: BIO_s_bio.3,v 1.17 2023/04/11 16:58:43 schwarze Exp $
 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
 .\" This file was written by
@@ -53,7 +53,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 21 2022 $
+.Dd $Mdocdate: April 11 2023 $
 .Dt BIO_S_BIO 3
 .Os
 .Sh NAME
@@ -316,6 +316,15 @@ or 0 on failure, with NULL pointers stored into the locations for
 and
 .Fa bio2 .
 Check the error stack for more information.
+.Pp
+When called on a BIO pair BIO object,
+.Xr BIO_method_type 3
+returns the constant
+.Dv BIO_TYPE_BIO
+and
+.Xr BIO_method_name 3
+returns a pointer to the static string
+.Qq BIO pair .
 .\" XXX More return values need to be added here.
 .Sh EXAMPLES
 The BIO pair can be used to have full control
diff --git a/lib/libcrypto/man/BIO_s_connect.3 b/lib/libcrypto/man/BIO_s_connect.3
index 2eeee197c52..2b2783fc5ca 100644
--- a/lib/libcrypto/man/BIO_s_connect.3
+++ b/lib/libcrypto/man/BIO_s_connect.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BIO_s_connect.3,v 1.15 2023/04/06 19:23:12 schwarze Exp $
+.\" $OpenBSD: BIO_s_connect.3,v 1.16 2023/04/11 16:58:43 schwarze Exp $
 .\" full merge up to: OpenSSL 0e474b8b Nov 1 15:45:49 2015 +0100
 .\"
 .\" This file is a derived work.
@@ -65,7 +65,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: April 6 2023 $
+.Dd $Mdocdate: April 11 2023 $
 .Dt BIO_S_CONNECT 3
 .Os
 .Sh NAME
@@ -368,6 +368,15 @@ are macros.
 .Fn BIO_s_connect
 returns the connect BIO method.
 .Pp
+When called on a connect BIO object,
+.Xr BIO_method_type 3
+returns the constant
+.Dv BIO_TYPE_CONNECT
+and
+.Xr BIO_method_name 3
+returns a pointer to the static string
+.Qq socket connect .
+.Pp
 .Xr BIO_get_fd 3
 returns the socket or -1 if the BIO has not been initialized.
 .Pp
diff --git a/lib/libcrypto/man/BIO_s_fd.3 b/lib/libcrypto/man/BIO_s_fd.3
index a22ba5d6039..ee70c56a028 100644
--- a/lib/libcrypto/man/BIO_s_fd.3
+++ b/lib/libcrypto/man/BIO_s_fd.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BIO_s_fd.3,v 1.10 2022/12/20 14:55:45 schwarze Exp $
+.\" $OpenBSD: BIO_s_fd.3,v 1.11 2023/04/11 16:58:43 schwarze Exp $
 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
 .\" This file is a derived work.
@@ -65,7 +65,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 20 2022 $
+.Dd $Mdocdate: April 11 2023 $
 .Dt BIO_S_FD 3
 .Os
 .Sh NAME
@@ -209,6 +209,15 @@ are implemented as macros.
 .Fn BIO_s_fd
 returns the file descriptor BIO method.
 .Pp
+When called on a file descriptor BIO object,
+.Xr BIO_method_type 3
+returns the constant
+.Dv BIO_TYPE_FD
+and
+.Xr BIO_method_name 3
+returns a pointer to the static string
+.Qq file descriptor .
+.Pp
 .Fn BIO_set_fd
 always returns 1.
 .Pp
diff --git a/lib/libcrypto/man/BIO_s_file.3 b/lib/libcrypto/man/BIO_s_file.3
index 3b256dbcf79..9f82ba5b803 100644
--- a/lib/libcrypto/man/BIO_s_file.3
+++ b/lib/libcrypto/man/BIO_s_file.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: BIO_s_file.3,v 1.11 2018/12/19 20:30:09 schwarze Exp $
+.\"	$OpenBSD: BIO_s_file.3,v 1.12 2023/04/11 16:58:43 schwarze Exp $
 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\" selective merge up to: OpenSSL 1212818e Sep 11 13:22:14 2018 +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 19 2018 $
+.Dd $Mdocdate: April 11 2023 $
 .Dt BIO_S_FILE 3
 .Os
 .Sh NAME
@@ -227,6 +227,15 @@ return a file BIO or
 .Dv NULL
 if an error occurred.
 .Pp
+When called on a file BIO object,
+.Xr BIO_method_type 3
+returns the constant
+.Dv BIO_TYPE_FILE
+and
+.Xr BIO_method_name 3
+returns a pointer to the static string
+.Qq FILE pointer .
+.Pp
 .Fn BIO_set_fp
 and
 .Fn BIO_get_fp
diff --git a/lib/libcrypto/man/BIO_s_mem.3 b/lib/libcrypto/man/BIO_s_mem.3
index 437632134bb..4592922444d 100644
--- a/lib/libcrypto/man/BIO_s_mem.3
+++ b/lib/libcrypto/man/BIO_s_mem.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BIO_s_mem.3,v 1.16 2022/12/18 22:27:10 schwarze Exp $
+.\" $OpenBSD: BIO_s_mem.3,v 1.17 2023/04/11 16:58:43 schwarze Exp $
 .\" full merge up to: OpenSSL 8711efb4 Mon Apr 20 11:33:12 2009 +0000
 .\" selective merge up to: OpenSSL 36359cec Mar 7 14:37:23 2018 +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 18 2022 $
+.Dd $Mdocdate: April 11 2023 $
 .Dt BIO_S_MEM 3
 .Os
 .Sh NAME
@@ -207,6 +207,15 @@ their size can grow indefinitely.
 .Fn BIO_s_mem
 returns a pointer to a static object.
 .Pp
+When called on a memory BIO object,
+.Xr BIO_method_type 3
+returns the constant
+.Dv BIO_TYPE_MEM
+and
+.Xr BIO_method_name 3
+returns a pointer to the static string
+.Qq memory buffer .
+.Pp
 .Fn BIO_set_mem_eof_return ,
 .Fn BIO_get_mem_data ,
 .Fn BIO_set_mem_buf ,
diff --git a/lib/libcrypto/man/BIO_s_null.3 b/lib/libcrypto/man/BIO_s_null.3
index 260d2799a76..6e7cad6d377 100644
--- a/lib/libcrypto/man/BIO_s_null.3
+++ b/lib/libcrypto/man/BIO_s_null.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BIO_s_null.3,v 1.9 2022/12/22 16:38:45 schwarze Exp $
+.\" $OpenBSD: BIO_s_null.3,v 1.10 2023/04/11 16:58:43 schwarze Exp $
 .\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -48,7 +48,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 22 2022 $
+.Dd $Mdocdate: April 11 2023 $
 .Dt BIO_S_NULL 3
 .Os
 .Sh NAME
@@ -81,6 +81,18 @@ this can be achieved by adding a null sink BIO to the end of the chain.
 .Sh RETURN VALUES
 .Fn BIO_s_null
 returns the null sink BIO method.
+.Pp
+When called on a null sink BIO object,
+.Xr BIO_method_type 3
+returns the constant
+.Dv BIO_TYPE_NULL
+and
+.Xr BIO_method_name 3
+returns a pointer to the static string
+.Qq NULL ,
+not to be confused with a NUL string nor with a
+.Dv NULL
+pointer.
 .Sh SEE ALSO
 .Xr BIO_new 3
 .Sh HISTORY
diff --git a/lib/libcrypto/man/BIO_s_socket.3 b/lib/libcrypto/man/BIO_s_socket.3
index 63ab1deb4b7..402622b3bd0 100644
--- a/lib/libcrypto/man/BIO_s_socket.3
+++ b/lib/libcrypto/man/BIO_s_socket.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: BIO_s_socket.3,v 1.9 2018/05/01 17:05:05 schwarze Exp $
+.\"	$OpenBSD: BIO_s_socket.3,v 1.10 2023/04/11 16:58:43 schwarze Exp $
 .\"	OpenSSL bbdc9c98 Oct 19 22:02:21 2000 +0000
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -48,7 +48,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: May 1 2018 $
+.Dd $Mdocdate: April 11 2023 $
 .Dt BIO_S_SOCKET 3
 .Os
 .Sh NAME
@@ -104,6 +104,15 @@ returns the socket BIO method.
 returns the newly allocated BIO or
 .Dv NULL
 if an error occurred.
+.Pp
+When called on a socket BIO object,
+.Xr BIO_method_type 3
+returns the constant
+.Dv BIO_TYPE_SOCKET
+and
+.Xr BIO_method_name 3
+returns a pointer to the static string
+.Qq socket .
 .Sh SEE ALSO
 .Xr BIO_get_fd 3 ,
 .Xr BIO_new 3
diff --git a/lib/libssl/man/BIO_f_ssl.3 b/lib/libssl/man/BIO_f_ssl.3
index 7292e63f518..ed268167794 100644
--- a/lib/libssl/man/BIO_f_ssl.3
+++ b/lib/libssl/man/BIO_f_ssl.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BIO_f_ssl.3,v 1.13 2022/12/18 20:24:52 schwarze Exp $
+.\" $OpenBSD: BIO_f_ssl.3,v 1.14 2023/04/11 16:58:43 schwarze Exp $
 .\" full merge up to: OpenSSL f672aee4 Feb 9 11:52:40 2016 -0500
 .\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800
 .\"
@@ -50,7 +50,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 18 2022 $
+.Dd $Mdocdate: April 11 2023 $
 .Dt BIO_F_SSL 3
 .Os
 .Sh NAME
@@ -370,6 +370,15 @@ returns a pointer to a static
 .Vt BIO_METHOD
 structure.
 .Pp
+When called on an SSL BIO object,
+.Xr BIO_method_type 3
+returns the constant
+.Dv BIO_TYPE_SSL
+and
+.Xr BIO_method_name 3
+returns a pointer to the static string
+.Qq ssl .
+.Pp
 .Fn BIO_set_ssl ,
 .Fn BIO_get_ssl ,
 .Fn BIO_set_ssl_mode ,