Document those BIO_ctrl(3) command constants

that correspond to more than one macro each.

5 files changed, 162 insertions, 37 deletions

diff --git a/lib/libcrypto/man/BIO_ctrl.3 b/lib/libcrypto/man/BIO_ctrl.3
index 845e2fa1476..08aae941ad2 100644
--- a/lib/libcrypto/man/BIO_ctrl.3
+++ b/lib/libcrypto/man/BIO_ctrl.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BIO_ctrl.3,v 1.19 2023/04/25 15:59:45 schwarze Exp $
+.\" $OpenBSD: BIO_ctrl.3,v 1.20 2023/04/26 15:03:02 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
 .\"
@@ -66,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: April 25 2023 $
+.Dd $Mdocdate: April 26 2023 $
 .Dt BIO_CTRL 3
 .Os
 .Sh NAME
@@ -354,6 +354,7 @@ The following
 .Fa cmd
 constants correspond to macros:
 .Bl -column BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT BIO_set_ssl_renegotiate_timeout(3)
+.It Fa cmd No constant                   Ta corresponding macro
 .It Dv BIO_C_DESTROY_BIO_PAIR            Ta Xr BIO_destroy_bio_pair 3
 .It Dv BIO_C_DO_STATE_MACHINE            Ta Xr BIO_do_handshake 3
 .It Dv BIO_C_FILE_SEEK                   Ta Fn BIO_seek
@@ -407,6 +408,19 @@ constants correspond to macros:
 .It Dv BIO_CTRL_SET_CLOSE                Ta Fn BIO_set_close
 .It Dv BIO_CTRL_WPENDING                 Ta Fn BIO_wpending
 .El
+.Pp
+Some
+.Fa cmd
+constants serve more than one macro each
+and are documented in the following manual pages:
+.Bl -column BIO_C_SET_BUFF_SIZE BIO_s_connect(3) -offset 3n
+.It Fa cmd No constant     Ta manual page
+.It Dv BIO_C_GET_CONNECT   Ta Xr BIO_s_connect 3
+.It Dv BIO_C_SET_ACCEPT    Ta Xr BIO_s_accept 3
+.It Dv BIO_C_SET_BUFF_SIZE Ta Xr BIO_f_buffer 3
+.It Dv BIO_C_SET_CONNECT   Ta Xr BIO_s_connect 3
+.It Dv BIO_C_SET_FILENAME  Ta Xr BIO_s_file 3
+.El
 .Sh RETURN VALUES
 The meaning of the return values of
 .Fn BIO_ctrl ,
diff --git a/lib/libcrypto/man/BIO_f_buffer.3 b/lib/libcrypto/man/BIO_f_buffer.3
index 9ac2f4de347..412ec52d74f 100644
--- a/lib/libcrypto/man/BIO_f_buffer.3
+++ b/lib/libcrypto/man/BIO_f_buffer.3
@@ -1,7 +1,24 @@
-.\" $OpenBSD: BIO_f_buffer.3,v 1.14 2023/04/11 16:58:43 schwarze Exp $
+.\" $OpenBSD: BIO_f_buffer.3,v 1.15 2023/04/26 15:03:02 schwarze Exp $
 .\" full merge up to OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
-.\" 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, 2010, 2015, 2016 The OpenSSL Project.
 .\" All rights reserved.
 .\"
@@ -49,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: April 11 2023 $
+.Dd $Mdocdate: April 26 2023 $
 .Dt BIO_F_BUFFER 3
 .Os
 .Sh NAME
@@ -137,10 +154,6 @@ If
 .Fa num
 is larger than the current buffer size, the buffer is expanded.
 .Pp
-Except
-.Fn BIO_f_buffer ,
-these functions are implemented as macros.
-.Pp
 Buffering BIOs implement
 .Xr BIO_gets 3
 by using
@@ -170,6 +183,32 @@ and
 .Fn BIO_set_write_buffer_size
 are called internally to automatically copy both buffer sizes from the
 original BIO object to the new one.
+.Pp
+.Xr BIO_ctrl 3
+.Fa cmd
+arguments correspond to macros as follows:
+.Bl -column BIO_C_GET_BUFF_NUM_LINES BIO_get_buffer_num_lines() -offset 3n
+.It Fa cmd No constant          Ta corresponding macro
+.It Dv BIO_C_GET_BUFF_NUM_LINES Ta Fn BIO_get_buffer_num_lines
+.It Dv BIO_C_SET_BUFF_READ_DATA Ta Fn BIO_set_buffer_read_data
+.It Dv BIO_C_SET_BUFF_SIZE      Ta Fn BIO_set_buffer_size
+.El
+.Pp
+The
+.Fa cmd
+constant
+.Dv BIO_C_SET_BUFF_SIZE
+is special.
+It is also used for
+.Xr BIO_int_ctrl 3
+with the following
+.Fa iarg
+arguments:
+.Bl -column BIO_C_SET_BUFF_SIZE iarg BIO_set_write_buffer_size() -offset 3n
+.It Fa cmd No constant     Ta Fa iarg Ta corresponding macro
+.It Dv BIO_C_SET_BUFF_SIZE Ta 0       Ta Fn BIO_set_read_buffer_size
+.It                        Ta 1       Ta Fn BIO_set_write_buffer_size
+.El
 .Sh RETURN VALUES
 .Fn BIO_f_buffer
 returns the buffering BIO method.
diff --git a/lib/libcrypto/man/BIO_s_accept.3 b/lib/libcrypto/man/BIO_s_accept.3
index ffbcccc7965..8a60eeda0a0 100644
--- a/lib/libcrypto/man/BIO_s_accept.3
+++ b/lib/libcrypto/man/BIO_s_accept.3
@@ -1,7 +1,24 @@
-.\"	$OpenBSD: BIO_s_accept.3,v 1.14 2023/04/11 16:58:43 schwarze Exp $
-.\"	OpenSSL c03726ca Thu Aug 27 12:28:08 2015 -0400
+.\" $OpenBSD: BIO_s_accept.3,v 1.15 2023/04/26 15:03:02 schwarze Exp $
+.\" full merge up to: OpenSSL c03726ca Thu Aug 27 12:28:08 2015 -0400
 .\"
-.\" 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, 2014, 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: April 11 2023 $
+.Dd $Mdocdate: April 26 2023 $
 .Dt BIO_S_ACCEPT 3
 .Os
 .Sh NAME
@@ -271,15 +288,21 @@ would block: the application should take appropriate action
 to wait until the underlying socket has accepted a connection
 and retry the call.
 .Pp
-.Fn BIO_set_accept_port ,
-.Fn BIO_get_accept_port ,
-.Fn BIO_set_nbio_accept ,
-.Fn BIO_set_accept_bios ,
-.Fn BIO_set_bind_mode ,
-.Fn BIO_get_bind_mode ,
+.Xr BIO_ctrl 3
+.Fa cmd
 and
-.Fn BIO_do_accept
-are macros.
+.Fa larg
+arguments correspond to macros as follows:
+.Bl -column BIO_C_DO_STATE_MACHINE larg BIO_get_accept_port(3) -offset 3n
+.It Fa cmd No constant        Ta Fa larg Ta corresponding macro
+.It Dv BIO_C_DO_STATE_MACHINE Ta 0       Ta Fn BIO_do_accept
+.It Dv BIO_C_GET_ACCEPT       Ta 0       Ta Fn BIO_get_accept_port
+.It Dv BIO_C_GET_BIND_MODE    Ta 0       Ta Fn BIO_get_bind_mode
+.It Dv BIO_C_SET_ACCEPT       Ta 0       Ta Fn BIO_set_accept_port
+.It                           Ta 1       Ta Fn BIO_set_nbio_accept
+.It                           Ta 2       Ta Fn BIO_set_accept_bios
+.It Dv BIO_C_SET_BIND_MODE    Ta Fa mode Ta Fn BIO_set_bind_mode
+.El
 .Sh RETURN VALUES
 When called on an accept BIO object,
 .Xr BIO_method_type 3
diff --git a/lib/libcrypto/man/BIO_s_connect.3 b/lib/libcrypto/man/BIO_s_connect.3
index 2b2783fc5ca..54fb1fe09fc 100644
--- a/lib/libcrypto/man/BIO_s_connect.3
+++ b/lib/libcrypto/man/BIO_s_connect.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BIO_s_connect.3,v 1.16 2023/04/11 16:58:43 schwarze Exp $
+.\" $OpenBSD: BIO_s_connect.3,v 1.17 2023/04/26 15:03:02 schwarze Exp $
 .\" full merge up to: OpenSSL 0e474b8b Nov 1 15:45:49 2015 +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: April 11 2023 $
+.Dd $Mdocdate: April 26 2023 $
 .Dt BIO_S_CONNECT 3
 .Os
 .Sh NAME
@@ -352,18 +352,24 @@ are called internally to automatically copy the hostname, port,
 non-blocking I/O flag, and info callback from the original BIO object
 to the new one.
 .Pp
-.Fn BIO_set_conn_hostname ,
-.Fn BIO_set_conn_port ,
-.Fn BIO_set_conn_ip ,
-.Fn BIO_set_conn_int_port ,
-.Fn BIO_get_conn_hostname ,
-.Fn BIO_get_conn_port ,
-.Fn BIO_get_conn_ip ,
-.Fn BIO_get_conn_int_port ,
-.Fn BIO_set_nbio ,
+.Xr BIO_ctrl 3
+.Fa cmd
 and
-.Fn BIO_do_connect
-are macros.
+.Fa larg
+arguments correspond to macros as follows:
+.Bl -column BIO_C_DO_STATE_MACHINE larg BIO_get_conn_hostname(3) -offset 3n
+.It Fa cmd No constant        Ta Fa larg Ta corresponding macro
+.It Dv BIO_C_DO_STATE_MACHINE Ta 0       Ta Fn BIO_do_connect
+.It Dv BIO_C_GET_CONNECT      Ta 0       Ta Fn BIO_get_conn_hostname
+.It                           Ta 1       Ta Fn BIO_get_conn_port
+.It                           Ta 2       Ta Fn BIO_get_conn_ip
+.It                           Ta 3       Ta Fn BIO_get_conn_int_port
+.It Dv BIO_C_SET_CONNECT      Ta 0       Ta Fn BIO_set_conn_hostname
+.It                           Ta 1       Ta Fn BIO_set_conn_port
+.It                           Ta 2       Ta Fn BIO_set_conn_ip
+.It                           Ta 3       Ta Fn BIO_set_conn_int_port
+.It Dv BIO_C_SET_NBIO         Ta Fa n    Ta Fn BIO_set_nbio
+.El
 .Sh RETURN VALUES
 .Fn BIO_s_connect
 returns the connect BIO method.
diff --git a/lib/libcrypto/man/BIO_s_file.3 b/lib/libcrypto/man/BIO_s_file.3
index 9f82ba5b803..884412cb024 100644
--- a/lib/libcrypto/man/BIO_s_file.3
+++ b/lib/libcrypto/man/BIO_s_file.3
@@ -1,8 +1,25 @@
-.\"	$OpenBSD: BIO_s_file.3,v 1.12 2023/04/11 16:58:43 schwarze Exp $
+.\"	$OpenBSD: BIO_s_file.3,v 1.13 2023/04/26 15:03:02 schwarze Exp $
 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\" selective merge up to: OpenSSL 1212818e Sep 11 13:22:14 2018 +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, 2010 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -49,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: April 11 2023 $
+.Dd $Mdocdate: April 26 2023 $
 .Dt BIO_S_FILE 3
 .Os
 .Sh NAME
@@ -216,6 +233,32 @@ On Windows,
 reserves for the filename argument to be UTF-8 encoded.
 In other words, if you have to make it work in a multi-lingual
 environment, encode file names in UTF-8.
+.Pp
+The following
+.Xr BIO_ctrl 3
+.Fa cmd
+constants correspond to macros:
+.Bl -column BIO_C_GET_FILE_PTR "corresponding macro" -offset 3n
+.It Fa cmd No constant    Ta corresponding macro
+.It Dv BIO_C_GET_FILE_PTR Ta Fn BIO_get_fp
+.It Dv BIO_C_SET_FILE_PTR Ta Fn BIO_set_fp
+.It Dv BIO_C_SET_FILENAME Ta various, see below
+.El
+.Pp
+The meaning of
+.Dv BIO_C_SET_FILENAME
+depends on the flags passed in the
+.Xr BIO_ctrl 3
+.Fa larg
+argument:
+.Bl -column "BIO_CLOSE | BIO_FP_READ | BIO_FP_WRITE" "BIO_append_filename()"\
+ -offset 3n
+.It Fa larg No argument                        Ta corresponding macro
+.It Dv BIO_CLOSE | BIO_FP_READ                 Ta Fn BIO_read_filename
+.It Dv BIO_CLOSE | BIO_FP_WRITE                Ta Fn BIO_write_filename
+.It Dv BIO_CLOSE | BIO_FP_APPEND               Ta Fn BIO_append_filename
+.It Dv BIO_CLOSE | BIO_FP_READ  | BIO_FP_WRITE Ta Fn BIO_rw_filename
+.El
 .Sh RETURN VALUES
 .Fn BIO_s_file
 returns the file BIO method.