From eb8dd9dca1228af0cd132f515509051ecfabf6f6 Mon Sep 17 00:00:00 2001 From: cvs2svn Date: Mon, 14 Apr 2025 17:32:06 +0000 Subject: This commit was manufactured by cvs2git to create tag 'tb_20250414'. --- src/lib/libcrypto/man/BIO_set_callback.3 | 396 ------------------------------- 1 file changed, 396 deletions(-) delete mode 100644 src/lib/libcrypto/man/BIO_set_callback.3 (limited to 'src/lib/libcrypto/man/BIO_set_callback.3') diff --git a/src/lib/libcrypto/man/BIO_set_callback.3 b/src/lib/libcrypto/man/BIO_set_callback.3 deleted file mode 100644 index 56a0102be6..0000000000 --- a/src/lib/libcrypto/man/BIO_set_callback.3 +++ /dev/null @@ -1,396 +0,0 @@ -.\" $OpenBSD: BIO_set_callback.3,v 1.12 2023/04/30 13:57:29 schwarze Exp $ -.\" full merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100 -.\" -.\" This file is a derived work. -.\" The changes are covered by the following Copyright and license: -.\" -.\" Copyright (c) 2018, 2022 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, 2016, 2017 The OpenSSL Project. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in -.\" the documentation and/or other materials provided with the -.\" distribution. -.\" -.\" 3. All advertising materials mentioning features or use of this -.\" software must display the following acknowledgment: -.\" "This product includes software developed by the OpenSSL Project -.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" -.\" -.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to -.\" endorse or promote products derived from this software without -.\" prior written permission. For written permission, please contact -.\" openssl-core@openssl.org. -.\" -.\" 5. Products derived from this software may not be called "OpenSSL" -.\" nor may "OpenSSL" appear in their names without prior written -.\" permission of the OpenSSL Project. -.\" -.\" 6. Redistributions of any form whatsoever must retain the following -.\" acknowledgment: -.\" "This product includes software developed by the OpenSSL Project -.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY -.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR -.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT -.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, -.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) -.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED -.\" OF THE POSSIBILITY OF SUCH DAMAGE. -.\" -.Dd $Mdocdate: April 30 2023 $ -.Dt BIO_SET_CALLBACK 3 -.Os -.Sh NAME -.Nm BIO_callback_fn_ex , -.Nm BIO_set_callback_ex , -.Nm BIO_get_callback_ex , -.Nm BIO_callback_fn , -.Nm BIO_set_callback , -.Nm BIO_get_callback , -.Nm BIO_set_callback_arg , -.Nm BIO_get_callback_arg , -.Nm BIO_debug_callback -.\" The following three macros are intentionally undocumented because -.\" they are unused and would only cause obfuscation if they were used. -.\" .Nm BIO_CB_return -.\" .Nm BIO_cb_pre -.\" .Nm BIO_cb_post -.Nd BIO callback functions -.Sh SYNOPSIS -.In openssl/bio.h -.Ft typedef long -.Fo (*BIO_callback_fn_ex) -.Fa "BIO *b" -.Fa "int oper" -.Fa "const char *argp" -.Fa "size_t len" -.Fa "int argi" -.Fa "long argl" -.Fa "int ret" -.Fa "size_t *processed" -.Fc -.Ft void -.Fo BIO_set_callback_ex -.Fa "BIO *b" -.Fa "BIO_callback_fn_ex cb_ex" -.Fc -.Ft BIO_callback_fn_ex -.Fo BIO_get_callback_ex -.Fa "const BIO *b" -.Fc -.Ft typedef long -.Fo (*BIO_callback_fn) -.Fa "BIO *b" -.Fa "int oper" -.Fa "const char *argp" -.Fa "int argi" -.Fa "long argl" -.Fa "long ret" -.Fc -.Ft void -.Fo BIO_set_callback -.Fa "BIO *b" -.Fa "BIO_callback_fn cb" -.Fc -.Ft BIO_callback_fn -.Fo BIO_get_callback -.Fa "BIO *b" -.Fc -.Ft void -.Fo BIO_set_callback_arg -.Fa "BIO *b" -.Fa "char *pointer" -.Fc -.Ft char * -.Fo BIO_get_callback_arg -.Fa "const BIO *b" -.Fc -.Ft long -.Fo BIO_debug_callback -.Fa "BIO *bio" -.Fa "int oper" -.Fa "const char *argp" -.Fa "int argi" -.Fa "long argl" -.Fa "long ret" -.Fc -.Sh DESCRIPTION -.Fn BIO_set_callback_ex -and -.Fn BIO_get_callback_ex -set and retrieve the BIO callback. -The callback is called during most high-level BIO operations. -It can be used for debugging purposes to trace operations on a BIO -or to modify its operation. -.Pp -.Fn BIO_set_callback -and -.Fn BIO_get_callback -are deprecated functions that set and retrieve the old-style BIO callback, -which is only used if no new-style callback is set with -.Fn BIO_set_callback_ex . -.Pp -.Fn BIO_set_callback_arg -stores the -.Fa pointer -internally in -.Fa b -and -.Fn BIO_get_callback_arg -retrieves it from -.Fa b . -The name of these two functions is badly misleading: the -.Fa pointer -is never passed as an argument to any callback function. -But of course, callback functions can call -.Fn BIO_get_callback_arg -and access the pointer, just like any other code can. -.Pp -.Fn BIO_debug_callback -is a standard debugging callback which prints -out information related to each BIO operation. -If -.Fn BIO_set_callback_arg -was called with a -.Pf non- Dv NULL -argument, information is sent to the BIO pointed to by the -.Fa pointer ; -otherwise, standard error output is used. -.Pp -The arguments of the callback functions are as follows: -.Bl -tag -width Ds -.It Fa b -The BIO the callback is attached to. -.It Fa oper -The operation being performed, which is one of -.Dv BIO_CB_CTRL , -.Dv BIO_CB_FREE , -.Dv BIO_CB_GETS , -.Dv BIO_CB_PUTS , -.Dv BIO_CB_READ , -or -.Dv BIO_CB_WRITE . -For some operations, the callback is called twice, -once before and once after the actual operation. -The latter case has -.Fa oper -OR'ed with -.Dv BIO_CB_RETURN . -.It Fa argp , argi , argl -The meaning of these three arguments depends on the value of -.Fa oper , -that is on the operation being performed. -.It Fa len -The length of the data requested to be read or written. -This is only useful if -.Fa oper -is -.Dv BIO_CB_READ , -.Dv BIO_CB_WRITE , -or -.Dv BIO_CB_GETS . -.It Fa ret -When -.Fa oper -does not include -.Dv BIO_CB_RETURN , -i.e. when the callback is invoked before an operation, -the value passed into the callback via -.Fa ret -is always 1. -In this case, if the callback returns a negative value, the library -aborts the requested operation and instead returns the negative -return value from the callback to the application. -If the callback returns a non-negative value, that return value is -ignored by the library, and the operation is performed normally. -.Pp -When -.Fa oper -includes -.Dv BIO_CB_RETURN , -i.e. when the callback is invoked after an operation, -the value passed into the callback via -.Fa ret -is the return value that the operation would return to the application -if no callback were present. -When a callback is present, the operation only passes this value -to the callback and instead of it returns the return value of the -callback to the application. -.It Fa processed -The location pointed to is updated with the number of bytes -actually read or written. -Only used for -.Dv BIO_CB_READ , -.Dv BIO_CB_WRITE , -.Dv BIO_CB_GETS , -and -.Dv BIO_CB_PUTS . -.El -.Pp -The callback should normally simply return -.Fa ret -when it has finished processing, unless it specifically wishes to -abort the operation or to modify the value returned to the application. -.Pp -The callbacks are called as follows: -.Bl -tag -width 1n -.It \&In Fn BIO_free "BIO *b" : -.Bd -literal -before the free operation: -cb_ex(b, BIO_CB_FREE, NULL, 0, 0, 0, 1, NULL) -or cb(b, BIO_CB_FREE, NULL, 0, 0, 1) -.Ed -.It \&In Fn BIO_read "BIO *b" "void *out" "int outl" : -.Bd -literal -before the read operation: -cb_ex(b, BIO_CB_READ, out, outl, 0, 0, 1, NULL) -or cb(b, BIO_CB_READ, out, outl, 0, 1) - -after the read operation: -cb_ex(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0, 0, ret, &bytes) -or cb(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0, ret) -.Ed -.It \&In Fn BIO_write "BIO *b" "const void *in" "int inl" : -.Bd -literal -before the write operation: -cb_ex(b, BIO_CB_WRITE, in, inl, 0, 0, 1, NULL) -or cb(b, BIO_CB_WRITE, in, inl, 0, 1) - -after the write operation: -cb_ex(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0, 0, ret, &bytes) -or cb(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0, ret) -.Ed -.It \&In Fn BIO_gets "BIO *b" "char *out" "int outl" : -.Bd -literal -before the read operation: -cb_ex(b, BIO_CB_GETS, out, outl, 0, 0, 1, NULL) -or cb(b, BIO_CB_GETS, out, outl, 0, 1) - -after the read operation: -cb_ex(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0, 0, ret, &bytes) -or cb(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0, ret) -.Ed -.It \&In Fn BIO_puts "BIO *b" "const char *in" : -.Bd -literal -before the write operation: -cb_ex(b, BIO_CB_PUTS, in, 0, 0, 0, 1, NULL) -or cb(b, BIO_CB_PUTS, in, 0, 0, 1) - -after the write operation: -cb_ex(b, BIO_CB_PUTS|BIO_CB_RETURN, in, 0, 0, 0, ret, &bytes) -or cb(b, BIO_CB_PUTS|BIO_CB_RETURN, in, 0, 0, ret) -.Ed -.It \&In Fn BIO_ctrl "BIO *b" "int cmd" "long larg" "void *parg" : -.Bd -literal -before the control operation: -cb_ex(b, BIO_CB_CTRL, parg, 0, cmd, larg, 1, NULL) -or cb(b, BIO_CB_CTRL, parg, cmd, larg, 1) - -after the control operation: -cb_ex(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, 0, cmd, larg, ret, NULL) -or cb(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, cmd, larg, ret) -.Ed -.It \&In Fn BIO_callback_ctrl "BIO *b" "int cmd" "BIO_info_cb *fp" : -.Bd -literal -before the control operation: -cb_ex(b, BIO_CB_CTRL, fp, 0, cmd, 0, 1, NULL) -or cb(b, BIO_CB_CTRL, fp, cmd, 0, 1) - -after the control operation: -cb_ex(b, BIO_CB_CTRL|BIO_CB_RETURN, fp, 0, cmd, 0, ret, NULL) -or cb(b, BIO_CB_CTRL|BIO_CB_RETURN, fp, cmd, 0, ret) -.Ed -.El -.Sh RETURN VALUES -.Fn BIO_get_callback_ex -returns a pointer to the function -.Fa cb_ex -previously installed with -.Fn BIO_set_callback_cb , -or -.Dv NULL -if no such callback was installed. -.Pp -.Fn BIO_get_callback -returns a pointer to the function -.Fa cb -previously installed with -.Fn BIO_set_callback , -or -.Dv NULL -if no such callback was installed. -.Pp -.Fn BIO_get_callback_arg -returns the -.Fa pointer -previously set with -.Fn BIO_set_callback_arg , -or -.Dv NULL -if no such pointer was set. -.Pp -.Fn BIO_debug_callback -returns -.Fa ret -if the bit -.Dv BIO_CB_RETURN -is set in -.Fa cmd , -or 1 otherwise. -.Sh EXAMPLES -The -.Fn BIO_debug_callback -function is a good example. -Its source is in the file -.Pa crypto/bio/bio_cb.c . -.Sh SEE ALSO -.Xr BIO_new 3 -.Sh HISTORY -.Fn BIO_set_callback , -.Fn BIO_get_callback , -.Fn BIO_set_callback_arg , -and -.Fn BIO_debug_callback -first appeared in SSLeay 0.6.0. -.Fn BIO_get_callback_arg -first appeared in SSLeay 0.8.0. -These functions have been available since -.Ox 2.4 . -.Pp -.Fn BIO_callback_fn -first appeared in OpenSSL 1.1.0. -.Fn BIO_callback_fn_ex , -.Fn BIO_set_callback_ex , -and -.Fn BIO_get_callback_ex -first appeared in OpenSSL 1.1.1. -These functions have been available since -.Ox 7.1 . -- cgit v1.2.3-55-g6feb