.\" $OpenBSD: BIO_get_data.3,v 1.8 2023/11/16 20:27:43 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 Matt Caswell . .\" Copyright (c) 2016 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: November 16 2023 $ .Dt BIO_GET_DATA 3 .Os .Sh NAME .Nm BIO_set_data , .Nm BIO_get_data , .Nm BIO_set_flags , .Nm BIO_clear_flags , .Nm BIO_test_flags , .Nm BIO_get_flags , .Nm BIO_set_retry_read , .Nm BIO_set_retry_write , .Nm BIO_set_retry_special , .Nm BIO_clear_retry_flags , .Nm BIO_get_retry_flags , .Nm BIO_copy_next_retry , .Nm BIO_set_init , .Nm BIO_get_init , .Nm BIO_set_shutdown , .Nm BIO_get_shutdown .Nd manage BIO state information .Sh SYNOPSIS .In openssl/bio.h .Ft void .Fo BIO_set_data .Fa "BIO *a" .Fa "void *ptr" .Fc .Ft void * .Fo BIO_get_data .Fa "BIO *a" .Fc .Ft void .Fo BIO_set_flags .Fa "BIO *a" .Fa "int flags" .Fc .Ft void .Fo BIO_clear_flags .Fa "BIO *a" .Fa "int flags" .Fc .Ft int .Fo BIO_test_flags .Fa "const BIO *a" .Fa "int flags" .Fc .Ft int .Fo BIO_get_flags .Fa "const BIO *a" .Fc .Ft void .Fo BIO_set_retry_read .Fa "BIO *a" .Fc .Ft void .Fo BIO_set_retry_write .Fa "BIO *a" .Fc .Ft void .Fo BIO_set_retry_special .Fa "BIO *a" .Fc .Ft void .Fo BIO_clear_retry_flags .Fa "BIO *a" .Fc .Ft int .Fo BIO_get_retry_flags .Fa "BIO *a" .Fc .Ft void .Fo BIO_copy_next_retry .Fa "BIO *a" .Fc .Ft void .Fo BIO_set_init .Fa "BIO *a" .Fa "int init" .Fc .Ft int .Fo BIO_get_init .Fa "BIO *a" .Fc .Ft void .Fo BIO_set_shutdown .Fa "BIO *a" .Fa "int shutdown" .Fc .Ft int .Fo BIO_get_shutdown .Fa "BIO *a" .Fc .Sh DESCRIPTION These functions are mainly useful when implementing a custom BIO. .Pp The .Fn BIO_set_data function associates the custom data pointed to by .Fa ptr with the .Fa "BIO a" . This data can subsequently be retrieved via a call to .Fn BIO_get_data . This can be used by custom BIOs for storing implementation specific information. .Pp .Fn BIO_set_flags sets all the bits contained in the .Fa flags argument in the flags stored in .Fa a . The value of a flag neither changes when it is already set in .Fa a nor when it is unset in the .Fa flags argument. .Pp .Fn BIO_clear_flags clears all the bits contained in the .Fa flags argument from the flags stored in .Fa a . The value of a flag neither changes when it is already unset in .Fa a nor when it is unset in the .Fa flags argument. .Pp .Fn BIO_test_flags checks whether any of the bits contained in the .Fa flags argument are set in the flags stored in .Fa a . Application programs usually call macros like those documented in .Xr BIO_should_retry 3 rather than calling .Fn BIO_test_flags directly. Flag bits correspond to accessor macros as follows: .Pp .Bl -tag -width BIO_FLAGS_SHOULD_RETRY -compact .It Dv BIO_FLAGS_READ .Xr BIO_should_read 3 .It Dv BIO_FLAGS_WRITE .Xr BIO_should_write 3 .It Dv BIO_FLAGS_IO_SPECIAL .Xr BIO_should_io_special 3 .It Dv BIO_FLAGS_RWS .Xr BIO_retry_type 3 .It Dv BIO_FLAGS_SHOULD_RETRY .Xr BIO_should_retry 3 .It Dv BIO_FLAGS_BASE64_NO_NL see .Xr BIO_f_base64 3 .It Dv BIO_FLAGS_MEM_RDONLY see .Xr BIO_s_mem 3 .El .Pp In particular, .Dv BIO_FLAGS_RWS is the bitwise OR of .Dv BIO_FLAGS_READ , .Dv BIO_FLAGS_WRITE , and .Dv BIO_FLAGS_IO_SPECIAL . .Pp .Fn BIO_set_retry_read , .Fn BIO_set_retry_write , and .Fn BIO_set_retry_special set the .Dv BIO_FLAGS_READ , .Dv BIO_FLAGS_WRITE , and .Dv BIO_FLAGS_IO_SPECIAL flag bit in .Fa a , respectively. They all set the .Dv BIO_FLAGS_SHOULD_RETRY flag bit, too. .Pp .Fn BIO_clear_retry_flags clears the flag bits .Dv BIO_FLAGS_READ , .Dv BIO_FLAGS_WRITE , .Dv BIO_FLAGS_IO_SPECIAL , and .Dv BIO_FLAGS_SHOULD_RETRY in .Fa a . .Pp .Fn BIO_copy_next_retry copies retry-related state data from the BIO that follows .Fa a in its chain to .Fa a , that is, the data accessible with .Fn BIO_get_retry_flags and .Xr BIO_get_retry_reason 3 . Flags which are already set in .Fa a are not cleared. Before calling .Fn BIO_copy_next_retry , making sure that .Fa a is not the last BIO in its chain is the responsibility of the caller, for example by checking that .Xr BIO_next 3 does not return .Dv NULL . .Pp The .Fn BIO_set_init function sets the .Fa init flag in .Fa a to the specified value. A non-zero value indicates that initialisation is complete, whilst zero indicates that it is not. Often initialisation will complete during initial construction of the BIO. For some BIOs however, initialisation may not be complete until additional steps have been taken, for example through calling custom ctrls. .Pp The .Fn BIO_set_shutdown and .Fn BIO_get_shutdown functions are low-level interfaces to forcefully set and get the .Fa shutdown flag of .Fa a , circumventing type-dependent sanity checks, exclusively intended for implementing a new BIO type. The .Fa shutdown argument must be either .Dv BIO_CLOSE or .Dv BIO_NOCLOSE . When merely using a .Vt BIO object, call .Xr BIO_set_close 3 and .Xr BIO_get_close 3 instead. .Pp .Fn BIO_get_flags , .Fn BIO_set_retry_read , .Fn BIO_set_retry_write , .Fn BIO_set_retry_special , .Fn BIO_clear_retry_flags , and .Fn BIO_get_retry_flags are implemented as macros. .Sh RETURN VALUES .Fn BIO_get_data returns a pointer to the implementation specific custom data associated with .Fa a , or .Dv NULL if none is set. .Pp .Fn BIO_test_flags returns the bitwise AND of the .Fa flags argument and the flags stored in .Fa a . Consequently, it returns a non-zero value if and only if at least one of the requested .Fa flags is set. .Pp .Fn BIO_get_flags returns all the flags currently stored in .Fa a . .Pp .Fn BIO_get_retry_flags returns the bitwise AND of .Pq Dv BIO_FLAGS_RWS | BIO_FLAGS_SHOULD_RETRY and the flags stored in .Fa a . .Pp .Fn BIO_get_init returns the value of the init flag of .Fa a . .Pp .Fn BIO_get_shutdown returns the value previously set with .Fn BIO_set_shutdown or with .Xr BIO_set_close 3 . .Sh SEE ALSO .Xr BIO_meth_new 3 , .Xr BIO_new 3 , .Xr BIO_set_close 3 , .Xr BIO_should_retry 3 .Sh HISTORY .Fn BIO_set_flags , .Fn BIO_clear_flags , .Fn BIO_set_retry_read , .Fn BIO_set_retry_write , .Fn BIO_set_retry_special , .Fn BIO_clear_retry_flags , and .Fn BIO_get_retry_flags first appeared in SSLeay 0.8.0, .Fn BIO_copy_next_retry in SSLeay 0.8.1, and .Fn BIO_get_flags in SSLeay 0.9.0. These functions have been available since .Ox 2.4 . .Pp .Fn BIO_test_flags first appeared in OpenSSL 0.9.8e and has been available since .Ox 4.5 . .Pp .Fn BIO_set_data , .Fn BIO_get_data , .Fn BIO_set_init , .Fn BIO_set_shutdown , and .Fn BIO_get_shutdown first appeared in OpenSSL 1.1.0 and have been available since .Ox 6.3 . .Pp .Fn BIO_get_init first appeared in OpenSSL 1.1.0 and has been available since .Ox 7.1 .