From 2061f013137d6e15f96cb1765d45eece60a6bfbe Mon Sep 17 00:00:00 2001 From: schwarze Date: Thu, 6 Apr 2023 19:23:12 +0000 Subject: [PATCH] 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. --- lib/libcrypto/man/BIO_s_connect.3 | 57 +++++++++++++++++++++++++++++-- 1 file changed, 54 insertions(+), 3 deletions(-) diff --git a/lib/libcrypto/man/BIO_s_connect.3 b/lib/libcrypto/man/BIO_s_connect.3 index ee6d4e38e1e..2eeee197c52 100644 --- a/lib/libcrypto/man/BIO_s_connect.3 +++ b/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 . +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023 Ingo Schwarze +.\" +.\" 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 . .\" 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 -- 2.20.1