path: root/lib/libcrypto/man/BIO_get_data.3

.\" $OpenBSD: BIO_get_data.3,v 1.7 2022/12/19 14:40:14 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 <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 Matt Caswell <matt@openssl.org>.
.\" 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: December 19 2022 $
.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 functions 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.
.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 .