From e3dcf5f3b9fcd5c8e99246eb5361440da7691f5c Mon Sep 17 00:00:00 2001 From: schwarze Date: Wed, 26 Apr 2023 15:03:02 +0000 Subject: [PATCH] Document those BIO_ctrl(3) command constants that correspond to more than one macro each. --- lib/libcrypto/man/BIO_ctrl.3 | 18 +++++++++-- lib/libcrypto/man/BIO_f_buffer.3 | 53 +++++++++++++++++++++++++++---- lib/libcrypto/man/BIO_s_accept.3 | 47 ++++++++++++++++++++------- lib/libcrypto/man/BIO_s_connect.3 | 32 +++++++++++-------- lib/libcrypto/man/BIO_s_file.3 | 49 ++++++++++++++++++++++++++-- 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 . +.\" 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, 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 . +.\" 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, 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 . +.\" 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, 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. -- 2.20.1