BIO_GET_DATA(3)

📦 version 4.1.0, in opensuse-leap 16.0

💅 BIO_GET_DATA(3) — the one where we manage BIO state info

okay so this is a page from the Library Functions Manual and it's literally all about poking at the internal state of a BIO — bestie, this is deep-in-the-weeds custom-BIO territory and honestly? iconic. 🧚

🌸 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 🎀

okay first, like, you gotta let it know you want these:

#include <openssl/bio.h>

then the whole squad, one by one:

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 ✨

so these functions are mainly useful when implementing a custom BIO — like, if you're out here building your own BIO type, this is your toolbox, and if you're not, you can lowkey vibe-check on out of this section. 💅

🦋 the data ones

BIO_set_data() 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(). Custom BIOs can use this for storing implementation specific information — like a little locker for your own stuff. 🔐

🌈 the flag ones

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. (yes bestie, that's the mirror image, and yes, the wording is doing the same dance. 🙈)

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 — so like, you could call it directly, but the macros are the main character here. ✨

Flag bits correspond to accessor macros as follows:

In particular, BIO_FLAGS_RWS is the bitwise OR of BIO_FLAGS_READ, BIO_FLAGS_WRITE, and BIO_FLAGS_IO_SPECIAL. hot girl bitwise math fr fr 🔥

💜 the retry ones

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 — trio behaviour, they all show up with the same accessory. 👑

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.

⚠️ okay so listen: 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. that check is on you, bestie, not on the function. no cap. 😭

🍓 init and shutdown

BIO_set_init() 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. it's giving "not done until it says it's done". ✨

BIO_set_shutdown() and BIO_get_shutdown() 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. these ones skip the sanity checks on purpose — they're for building BIO types, not for day-to-day use. 💀

🧚 macro moment

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. sneakily efficient, we love to see it. 💅

🌟 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)

like, go read those next, they're the supporting cast and they ate. 🫶

📜 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.

and that's the whole page, bestie 💖 this one ships from Debian, dated November 16, 2023, and it's BIO_GET_DATA(3) all the way down. go forth and manage your BIO state, you absolute icon. 🌈✨

📦 where this page comes from