Document the effects that BIO_set_info_callback(3), BIO_callback_ctrl(3),

BIO_get_info_callback(3), and BIO_info_cb(3) have on connect BIOs.

1 files changed, 54 insertions, 3 deletions

diff --git a/src/lib/libcrypto/man/BIO_s_connect.3 b/src/lib/libcrypto/man/BIO_s_connect.3
index ee6d4e38e1..2eeee197c5 100644
--- a/src/lib/libcrypto/man/BIO_s_connect.3
+++ b/src/lib/libcrypto/man/BIO_s_connect.3
@@ -1,7 +1,24 @@
-.\" $OpenBSD: BIO_s_connect.3,v 1.14 2022/12/18 19:35:36 schwarze Exp $
+.\" $OpenBSD: BIO_s_connect.3,v 1.15 2023/04/06 19:23:12 schwarze Exp $
 .\" full merge up to: OpenSSL 0e474b8b Nov 1 15:45:49 2015 +0100
 .\"
-.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2023 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
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2000, 2015 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -48,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: April 6 2023 $
 .Dt BIO_S_CONNECT 3
 .Os
 .Sh NAME
@@ -161,6 +178,40 @@ is not
 it should be of type
 .Vt "int *" .
 .Pp
+.Xr BIO_set_info_callback 3
+and
+.Xr BIO_callback_ctrl 3
+with a
+.Fa cmd
+of
+.Dv BIO_CTRL_SET_CALLBACK
+save the pointer to the
+.Fa cb
+function internally in
+.Fa b
+and
+.Xr BIO_get_info_callback 3
+retrieves this function pointer.
+If such an info callback is installed, it is invoked whenever
+a state change or error occurs in the connect BIO state machine.
+The arguments of the callback include the new
+.Fa state
+in case of a state change or the old
+.Fa state
+in case of an error and the value
+.Fa res
+that the state machine would return to whatever operation invoked it
+if no info callback had been installed.
+If an info callback is installed, the state machine
+returns the return value of the info callback instead.
+Consequently, the info callback is supposed to usually return
+.Fa res .
+The precise effect of the return value depends on which operation
+the state machine was invoked from.
+Usually, \-1 is used to indicate failure and return values less than
+or equal to zero abort the operation in question, whereas positive
+values indicate success and allow the operation to proceed.
+.Pp
 .Fn BIO_set_conn_hostname
 uses the string
 .Fa name