In preparation for better documenting BIO info callbacks, improve the

description of BIO_ctrl(3) and its three siblings.  Given the vast range
of effects these functions can have, the text is unavoidably still
vague, but at least some information can be provided.

While here, fix one wrong parameter type and three inconsistent
parameter names in the SYNOPSIS.

1 files changed, 115 insertions, 9 deletions

diff --git a/src/lib/libcrypto/man/BIO_ctrl.3 b/src/lib/libcrypto/man/BIO_ctrl.3
index 762d45a5ed..a5c181307e 100644
--- a/src/lib/libcrypto/man/BIO_ctrl.3
+++ b/src/lib/libcrypto/man/BIO_ctrl.3
@@ -1,7 +1,25 @@
-.\"     $OpenBSD: BIO_ctrl.3,v 1.16 2022/08/18 18:42:13 tb Exp $
-.\"     OpenSSL b055fceb Thu Oct 20 09:56:18 2016 +0100
+.\" $OpenBSD: BIO_ctrl.3,v 1.17 2023/04/04 17:10:37 schwarze Exp $
+.\" full merge up to: OpenSSL 24a535eaf Tue Sep 22 13:14:20 2020 +0100
+.\" selective merge up to: OpenSSL 0c5bc96f Tue Mar 15 13:57:22 2022 +0000
 .\"
-.\" 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, 2016 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -48,7 +66,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: August 18 2022 $
+.Dd $Mdocdate: April 4 2023 $
 .Dt BIO_CTRL 3
 .Os
 .Sh NAME
@@ -75,7 +93,7 @@
 .In openssl/bio.h
 .Ft long
 .Fo BIO_ctrl
-.Fa "BIO *bp"
+.Fa "BIO *b"
 .Fa "int cmd"
 .Fa "long larg"
 .Fa "void *parg"
@@ -84,17 +102,17 @@
 .Fo BIO_callback_ctrl
 .Fa "BIO *b"
 .Fa "int cmd"
-.Fa "BIO_info_cb cb"
+.Fa "BIO_info_cb *cb"
 .Fc
 .Ft char *
 .Fo BIO_ptr_ctrl
-.Fa "BIO *bp"
+.Fa "BIO *b"
 .Fa "int cmd"
 .Fa "long larg"
 .Fc
 .Ft long
 .Fo BIO_int_ctrl
-.Fa "BIO *bp"
+.Fa "BIO *b"
 .Fa "int cmd"
 .Fa "long larg"
 .Fa "int iarg"
@@ -175,6 +193,54 @@ Macros specific to a particular type of BIO
 are described in the specific BIO's manual page
 as well as any special features of the standard calls.
 .Pp
+Depending on the
+.Fa cmd
+and on the type of
+.Fa b ,
+.Fn BIO_ctrl
+may have a read-only effect on
+.Fa b
+or change data in
+.Fa b
+or in its sub-structures.
+It may also have a side effect of changing the memory pointed to by
+.Fa parg .
+.Pp
+.Fn BIO_callback_ctrl
+does not call
+.Fn BIO_ctrl
+but instead requires that the BIO type of
+.Fa b
+provides a dedicated
+.Fa callback_ctrl
+function pointer, which is built into the library for some standard BIO
+types and can be provided with
+.Xr BIO_meth_set_callback_ctrl 3
+for application-defined BIO types.
+.Pp
+.Fn BIO_ptr_ctrl
+calls
+.Fn BIO_ctrl
+with
+.Fa parg
+pointing to the location of a temporary pointer variable initialized to
+.Dv NULL .
+.Pp
+.Fn BIO_int_ctrl
+calls
+.Fn BIO_ctrl
+with
+.Fa parg
+pointing to the location of a temporary
+.Vt int
+variable initialized to
+.Fa iarg .
+If
+.Fn BIO_ctrl
+changes the value stored at
+.Pf * Fa parg ,
+the new value is ignored.
+.Pp
 .Fn BIO_reset
 typically resets a BIO to some initial state.
 In the case of file related BIOs, for example,
@@ -234,6 +300,46 @@ and
 are macros which call
 .Fn BIO_ctrl .
 .Sh RETURN VALUES
+The meaning of the return values of
+.Fn BIO_ctrl ,
+.Fn BIO_callback_ctrl ,
+and
+.Fn BIO_int_ctrl
+depends on both the type of
+.Fa b
+and on the
+.Fa cmd .
+If
+.Fa b
+is a
+.Dv NULL
+pointer, no action occurs and 0 is returned.
+The return value \-2 usually indicates a fatal error.
+In particular, it is returned if the
+.Fa cmd
+is unsupported by the type of
+.Fa b .
+If a callback was installed with
+.Xr BIO_set_callback_ex 3
+or
+.Xr BIO_set_callback 3
+and returns a negative value, that value is returned.
+.Pp
+.Fn BIO_ptr_ctrl
+returns
+.Dv NULL
+if the
+.Fn BIO_ctrl
+call returns a negative value or does not change
+.Pf * Fa parg ,
+or the pointer it puts into
+.Pf * Fa parg
+otherwise.
+.Pp
+.Fn BIO_int_ctrl
+returns the return value of
+.Fn BIO_ctrl .
+.Pp
 .Fn BIO_reset
 normally returns 1 for success and 0 or -1 for failure.
 File BIOs are an exception, returning 0 for success and -1 for failure.
@@ -295,7 +401,7 @@ to the next BIO in the chain.
 This often means there is no need to locate the required BIO for
 a particular operation: it can be called on a chain and it will
 be automatically passed to the relevant BIO.
-However this can cause unexpected results.
+However, this can cause unexpected results.
 For example no current filter BIOs implement
 .Fn BIO_seek ,
 but this may still succeed if the chain ends