BIO_GET_DATA(3) | Library Functions Manual | BIO_GET_DATA(3)

# 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

library “libcrypto”
`#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.

June 8, 2025 | Debian