NAME
BIO_set_data,
BIO_get_data, BIO_set_flags,
BIO_clear_flags,
BIO_test_flags,
BIO_get_flags,
BIO_set_retry_read,
BIO_set_retry_write,
BIO_set_retry_special,
BIO_clear_retry_flags,
BIO_get_retry_flags,
BIO_copy_next_retry,
BIO_set_init, BIO_get_init,
BIO_set_shutdown,
BIO_get_shutdown —
manage BIO state information
SYNOPSIS
#include
<openssl/bio.h>
void
BIO_set_data(BIO *a,
void *ptr);
void *
BIO_get_data(BIO *a);
void
BIO_set_flags(BIO *a,
int flags);
void
BIO_clear_flags(BIO *a,
int flags);
int
BIO_test_flags(const BIO *a,
int flags);
int
BIO_get_flags(const BIO *a);
void
BIO_set_retry_read(BIO *a);
void
BIO_set_retry_write(BIO *a);
void
BIO_set_retry_special(BIO
*a);
void
BIO_clear_retry_flags(BIO
*a);
int
BIO_get_retry_flags(BIO *a);
void
BIO_copy_next_retry(BIO *a);
void
BIO_set_init(BIO *a,
int init);
int
BIO_get_init(BIO *a);
void
BIO_set_shutdown(BIO *a,
int shutdown);
int
BIO_get_shutdown(BIO *a);
DESCRIPTION
These functions are mainly useful when implementing a custom BIO.
The
BIO_set_data()
function associates the custom data pointed to by ptr
with the BIO a. This data can subsequently be
retrieved via a call to
BIO_get_data().
This can be used by custom BIOs for storing implementation specific
information.
BIO_set_flags()
sets all the bits contained in the flags argument in
the flags stored in a. The value of a flag neither
changes when it is already set in a nor when it is
unset in the flags argument.
BIO_clear_flags()
clears all the bits contained in the flags argument
from the flags stored in a. The value of a flag
neither changes when it is already unset in a nor when
it is unset in the flags argument.
BIO_test_flags()
checks whether any of the bits contained in the flags
argument are set in the flags stored in a. Application
programs usually call macros like those documented in
BIO_should_retry(3) rather than calling
BIO_test_flags() directly. Flag bits correspond to
accessor macros as follows:
BIO_FLAGS_READ- BIO_should_read(3)
BIO_FLAGS_WRITE- BIO_should_write(3)
BIO_FLAGS_IO_SPECIAL- BIO_should_io_special(3)
BIO_FLAGS_RWS- BIO_retry_type(3)
BIO_FLAGS_SHOULD_RETRY- BIO_should_retry(3)
BIO_FLAGS_BASE64_NO_NL- see BIO_f_base64(3)
BIO_FLAGS_MEM_RDONLY- see BIO_s_mem(3)
In particular, BIO_FLAGS_RWS is the
bitwise OR of BIO_FLAGS_READ,
BIO_FLAGS_WRITE, and
BIO_FLAGS_IO_SPECIAL.
BIO_set_retry_read(),
BIO_set_retry_write(),
and
BIO_set_retry_special()
set the BIO_FLAGS_READ,
BIO_FLAGS_WRITE, and
BIO_FLAGS_IO_SPECIAL flag bit in
a, respectively. They all set the
BIO_FLAGS_SHOULD_RETRY flag bit, too.
BIO_clear_retry_flags()
clears the flag bits BIO_FLAGS_READ,
BIO_FLAGS_WRITE,
BIO_FLAGS_IO_SPECIAL, and
BIO_FLAGS_SHOULD_RETRY in
a.
BIO_copy_next_retry()
copies retry-related state data from the BIO that follows
a in its chain to a, that is,
the data accessible with
BIO_get_retry_flags()
and
BIO_get_retry_reason(3). Flags which are already set in
a are not cleared. Before calling
BIO_copy_next_retry(), making sure that
a is not the last BIO in its chain is the
responsibility of the caller, for example by checking that
BIO_next(3) does not return NULL.
The
BIO_set_init()
function sets the init flag in 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.
The
BIO_set_shutdown()
and
BIO_get_shutdown()
functions are low-level interfaces to forcefully set and get the
shutdown flag of a,
circumventing type-dependent sanity checks, exclusively intended for
implementing a new BIO type. The shutdown argument
must be either BIO_CLOSE or
BIO_NOCLOSE. When merely using a
BIO object, call
BIO_set_close(3) and
BIO_get_close(3) instead.
BIO_get_flags(),
BIO_set_retry_read(),
BIO_set_retry_write(),
BIO_set_retry_special(),
BIO_clear_retry_flags(), and
BIO_get_retry_flags() are implemented as macros.
RETURN VALUES
BIO_get_data() returns a pointer to the
implementation specific custom data associated with a,
or NULL if none is set.
BIO_test_flags() returns the bitwise AND
of the flags argument and the flags stored in
a. Consequently, it returns a non-zero value if and
only if at least one of the requested flags is
set.
BIO_get_flags() returns all the flags
currently stored in a.
BIO_get_retry_flags() returns the bitwise
AND of (BIO_FLAGS_RWS |
BIO_FLAGS_SHOULD_RETRY) and the flags stored in
a.
BIO_get_init() returns the value of the
init flag of a.
BIO_get_shutdown() returns the value
previously set with BIO_set_shutdown() or with
BIO_set_close(3).
SEE ALSO
BIO_meth_new(3), BIO_new(3), BIO_set_close(3), BIO_should_retry(3)
HISTORY
BIO_set_flags(),
BIO_clear_flags(),
BIO_set_retry_read(),
BIO_set_retry_write(),
BIO_set_retry_special(),
BIO_clear_retry_flags(), and
BIO_get_retry_flags() first appeared in SSLeay
0.8.0, BIO_copy_next_retry() in SSLeay 0.8.1, and
BIO_get_flags() in SSLeay 0.9.0. These functions
have been available since OpenBSD 2.4.
BIO_test_flags() first appeared in OpenSSL
0.9.8e and has been available since OpenBSD 4.5.
BIO_set_data(),
BIO_get_data(),
BIO_set_init(),
BIO_set_shutdown(), and
BIO_get_shutdown() first appeared in OpenSSL 1.1.0
and have been available since OpenBSD 6.3.
BIO_get_init() first appeared in OpenSSL
1.1.0 and has been available since OpenBSD 7.1.