From 375dfd33222242deee143d79b42bef402432b431 Mon Sep 17 00:00:00 2001
From: schwarze <schwarze@openbsd.org>
Date: Mon, 19 Dec 2022 14:40:14 +0000
Subject: [PATCH] document BIO_copy_next_retry(3)

---
 lib/libcrypto/man/BIO_get_data.3 | 39 ++++++++++++++++++++++++++++----
 1 file changed, 34 insertions(+), 5 deletions(-)

diff --git a/lib/libcrypto/man/BIO_get_data.3 b/lib/libcrypto/man/BIO_get_data.3
index 51b10adbb44..b4b0014d15b 100644
--- a/lib/libcrypto/man/BIO_get_data.3
+++ b/lib/libcrypto/man/BIO_get_data.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BIO_get_data.3,v 1.6 2022/12/18 21:45:47 schwarze Exp $
+.\" $OpenBSD: BIO_get_data.3,v 1.7 2022/12/19 14:40:14 schwarze Exp $
 .\" full merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +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: December 18 2022 $
+.Dd $Mdocdate: December 19 2022 $
 .Dt BIO_GET_DATA 3
 .Os
 .Sh NAME
@@ -80,6 +80,7 @@
 .Nm BIO_set_retry_special ,
 .Nm BIO_clear_retry_flags ,
 .Nm BIO_get_retry_flags ,
+.Nm BIO_copy_next_retry ,
 .Nm BIO_set_init ,
 .Nm BIO_get_init ,
 .Nm BIO_set_shutdown ,
@@ -136,6 +137,10 @@
 .Fa "BIO *a"
 .Fc
 .Ft void
+.Fo BIO_copy_next_retry
+.Fa "BIO *a"
+.Fc
+.Ft void
 .Fo BIO_set_init
 .Fa "BIO *a"
 .Fa "int init"
@@ -238,7 +243,7 @@ set the
 and
 .Dv BIO_FLAGS_IO_SPECIAL
 flag bit in
-.Fa b ,
+.Fa a ,
 respectively.
 They all set the
 .Dv BIO_FLAGS_SHOULD_RETRY
@@ -252,7 +257,29 @@ clears the flag bits
 and
 .Dv BIO_FLAGS_SHOULD_RETRY
 in
-.Fa b .
+.Fa a .
+.Pp
+.Fn BIO_copy_next_retry
+copies retry-related state data from the BIO that follows
+.Fa a
+in its chain to
+.Fa a ,
+that is, the data accessible with
+.Fn BIO_get_retry_flags
+and
+.Xr BIO_get_retry_reason 3 .
+Flags which are already set in
+.Fa a
+are not cleared.
+Before calling
+.Fn BIO_copy_next_retry ,
+making sure that
+.Fa a
+is not the last BIO in its chain is the responsibility of the caller,
+for example by checking that
+.Xr BIO_next 3
+does not return
+.Dv NULL .
 .Pp
 The
 .Fn BIO_set_init
@@ -344,7 +371,9 @@ or with
 .Fn BIO_clear_retry_flags ,
 and
 .Fn BIO_get_retry_flags
-first appeared in SSLeay 0.8.0 and
+first appeared in SSLeay 0.8.0,
+.Fn BIO_copy_next_retry
+in SSLeay 0.8.1, and
 .Fn BIO_get_flags
 in SSLeay 0.9.0.
 These functions have been available since
-- 
2.20.1