From fb011e9c430807abab1ae895fe18995f61f6224e Mon Sep 17 00:00:00 2001
From: Ingo Schwarze <schwarze@cvs.openbsd.org>
Date: Sat, 17 Dec 2022 22:21:25 +0000
Subject: Document BIO_set_flags(3), BIO_clear_flags(3), BIO_test_flags(3), and
 BIO_get_flags(3).

---
 lib/libcrypto/man/BIO_get_data.3 | 92 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 88 insertions(+), 4 deletions(-)

(limited to 'lib')

diff --git a/lib/libcrypto/man/BIO_get_data.3 b/lib/libcrypto/man/BIO_get_data.3
index 3f740c1fe68..dd7858b771e 100644
--- a/lib/libcrypto/man/BIO_get_data.3
+++ b/lib/libcrypto/man/BIO_get_data.3
@@ -1,10 +1,10 @@
-.\" $OpenBSD: BIO_get_data.3,v 1.4 2022/11/25 17:44:01 schwarze Exp $
+.\" $OpenBSD: BIO_get_data.3,v 1.5 2022/12/17 22:21:24 schwarze Exp $
 .\" full merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
 .\"
 .\" This file is a derived work.
 .\" The changes are covered by the following Copyright and license:
 .\"
-.\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2018, 2022 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
@@ -65,12 +65,16 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 25 2022 $
+.Dd $Mdocdate: December 17 2022 $
 .Dt BIO_GET_DATA 3
 .Os
 .Sh NAME
 .Nm BIO_set_data ,
 .Nm BIO_get_data ,
+.Nm BIO_set_flags ,
+.Nm BIO_clear_flags ,
+.Nm BIO_test_flags ,
+.Nm BIO_get_flags ,
 .Nm BIO_set_init ,
 .Nm BIO_get_init ,
 .Nm BIO_set_shutdown ,
@@ -88,6 +92,25 @@
 .Fa "BIO *a"
 .Fc
 .Ft void
+.Fo BIO_set_flags
+.Fa "BIO *a"
+.Fa "int flags"
+.Fc
+.Ft void
+.Fo BIO_clear_flags
+.Fa "BIO *a"
+.Fa "int flags"
+.Fc
+.Ft int
+.Fo BIO_test_flags
+.Fa "const BIO *a"
+.Fa "int flags"
+.Fc
+.Ft int
+.Fo BIO_get_flags
+.Fa "const BIO *a"
+.Fc
+.Ft void
 .Fo BIO_set_init
 .Fa "BIO *a"
 .Fa "int init"
@@ -119,6 +142,39 @@ This data can subsequently be retrieved via a call to
 This can be used by custom BIOs for storing implementation specific
 information.
 .Pp
+.Fn BIO_set_flags
+sets all the bits contained in the
+.Fa flags
+argument in the flags stored in
+.Fa a .
+The value of a flag neither changes when it is already set in
+.Fa a
+nor when it is unset in the
+.Fa flags
+argument.
+.Pp
+.Fn BIO_clear_flags
+clears all the bits contained in the
+.Fa flags
+argument from the flags stored in
+.Fa a .
+The value of a flag neither changes when it is already unset in
+.Fa a
+nor when it is unset in the
+.Fa flags
+argument.
+.Pp
+.Fn BIO_test_flags
+checks whether any of the bits contained in the
+.Fa flags
+argument are set in the flags stored in
+.Fa a .
+Application programs usually call macros like those documented in
+.Xr BIO_should_retry 3
+rather than calling
+.Fn BIO_test_flags
+directly.
+.Pp
 The
 .Fn BIO_set_init
 function sets the
@@ -166,6 +222,20 @@ or
 .Dv NULL
 if none is set.
 .Pp
+.Fn BIO_test_flags
+returns the bitwise OR of the
+.Fa flags
+argument and the flags stored in
+.Fa a .
+Consequently, it returns a non-zero value
+if and only if at least one of the requested
+.Fa flags
+is set.
+.Pp
+.Fn BIO_get_flags
+returns all the flags currently stored in
+.Fa a .
+.Pp
 .Fn BIO_get_init
 returns the value of the init flag of
 .Fa a .
@@ -178,8 +248,22 @@ or with
 .Sh SEE ALSO
 .Xr BIO_meth_new 3 ,
 .Xr BIO_new 3 ,
-.Xr BIO_set_close 3
+.Xr BIO_set_close 3 ,
+.Xr BIO_should_retry 3
 .Sh HISTORY
+.Fn BIO_set_flags
+and
+.Fn BIO_clear_flags
+first appeared in SSLeay 0.8.0 and
+.Fn BIO_get_flags
+in SSLeay 0.9.0.
+These functions have been available since
+.Ox 2.4 .
+.Pp
+.Fn BIO_test_flags
+first appeared in OpenSSL 0.9.8e and has been available since
+.Ox 4.5 .
+.Pp
 .Fn BIO_set_data ,
 .Fn BIO_get_data ,
 .Fn BIO_set_init ,
-- 
cgit v1.2.3