BIO_SET_FLAGS(3ossl)

📦 version 14.5, in freebsd 14.5

💅 BIO_SET_FLAGS — okay so this is from OpenSSL (that's the 3ossl manual, bestie) 🎀

✨ NAME ✨

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 — literally all the little functions that poke at a BIO's flags and then tell you what they mean 🦋

🌸 SYNOPSIS 🌸

#include <openssl/bio.h>

void BIO_set_flags(BIO *b, int flags);
void BIO_clear_flags(BIO *b, int flags);
int  BIO_test_flags(const BIO *b, int flags);
int  BIO_get_flags(const BIO *b);

void BIO_set_retry_read(BIO *b);
void BIO_set_retry_write(BIO *b);
void BIO_set_retry_special(BIO *b);
void BIO_clear_retry_flags(BIO *b);
int  BIO_get_retry_flags(BIO *b);

💖 DESCRIPTION 💖

So a BIO has its own internal little set of bit flags that describe what's going on with it, right? These functions and macros are mostly for people writing BIO implementations, and for the code that stitches BIO chains together, to mess with those flags. 👑

BIO_set_flags() sets the bits you pass in flags on the BIO b. Anything already set in the BIO's flag word stays set — it's additive, no cap. ✨

BIO_clear_flags() clears the bits given in flags from the BIO b. Every other bit in the flag word is left exactly where it was, untouched, main character energy. 🙈

BIO_test_flags() tests the bits given in flags against the BIO b, and returns a nonzero value if any of them are currently set, and zero otherwise. 💅

BIO_get_flags() just hands you the BIO b's current flag word. It's equivalent to testing for all the bits and returning that result — same vibe, different wrapper. 🫶

The next bunch are convenience macros built on top of those primitives, and their whole job is keeping track of a BIO's retry state:

  • BIO_set_retry_read() — marks BIO b as being in a retryable state by setting the BIO_FLAGS_SHOULD_RETRY flag. On top of that it sets BIO_FLAGS_READ so everyone knows the retry condition is tied to a read operation. 📖
  • BIO_set_retry_write() — marks BIO b as retryable by setting BIO_FLAGS_SHOULD_RETRY, plus it sets BIO_FLAGS_WRITE to say the retry condition is tied to a write operation. ✍️
  • BIO_set_retry_special() — marks BIO b as retryable by setting BIO_FLAGS_SHOULD_RETRY, and also sets BIO_FLAGS_IO_SPECIAL to signal that the retry condition is associated with some "special" condition on a read operation. What that condition actually means depends on the BIO type — iykyk. 🧚
  • BIO_clear_retry_flags() — clears all the retry-related bits from b, meaning BIO_FLAGS_READ, BIO_FLAGS_WRITE, BIO_FLAGS_IO_SPECIAL, and BIO_FLAGS_SHOULD_RETRY. All of them. Gone. 💀
  • BIO_get_retry_flags() — returns the retry-related bits currently set in b. The result is a subset of BIO_FLAGS_RWS|BIO_FLAGS_SHOULD_RETRY. 🌈

The retry bits get interpreted by the higher-level macros BIO_should_read(), BIO_should_write(), BIO_should_io_special(), BIO_retry_type() and BIO_should_retry(), all documented over in BIO_should_retry(3). Application code will typically use those macros instead of fiddling with the underlying flags directly — please, bestie, use the nice ones. 🥺

So here are the flag bits that are currently defined for use with BIO_set_flags(), BIO_clear_flags() and BIO_test_flags():

🌟 The flag bits 🌟

  • BIO_FLAGS_READ — the last I/O operation should be retried once the BIO becomes readable. Normally set by the BIO implementation via BIO_set_retry_read() after a read operation failed. 💜
  • BIO_FLAGS_WRITE — the last I/O operation should be retried once the BIO becomes writable. Normally set by the BIO implementation via BIO_set_retry_write() after a write operation failed. 🍓
  • BIO_FLAGS_IO_SPECIAL — the last I/O operation should be retried when some "special" condition becomes true. What exactly that condition is depends on the BIO type, and you usually get it via BIO_get_retry_BIO() and BIO_get_retry_reason() as described in BIO_should_retry(3). Normally set by the BIO implementation via BIO_set_retry_special(). 🔥
  • BIO_FLAGS_RWS — the bitwise OR of BIO_FLAGS_READ, BIO_FLAGS_WRITE and BIO_FLAGS_IO_SPECIAL. This mask is what you use when clearing or extracting the retry-direction bits. 🎀
  • BIO_FLAGS_SHOULD_RETRY — set if the last I/O operation on the BIO should be retried at a later time. If this bit is not set, then the condition is treated as an error. Normally set by the BIO implementation. ⭐
  • BIO_FLAGS_BASE64_NO_NL — when set on a base64 filter BIO, this flag disables the generation of newline characters in the encoded output and causes newlines to be ignored in the input. See also BIO_f_base64(3). The flag has no effect on any other built-in BIO types. 🎁
  • BIO_FLAGS_MEM_RDONLY — when set on a memory BIO, this flag means the underlying buffer is read only. Attempts to write to such a BIO will fail. The flag has no effect on any other built-in BIO types. 🔒
  • BIO_FLAGS_NONCLEAR_RST — on a memory BIO, this flag changes how BIO_reset() behaves. When it's set, resetting the BIO does not clear the underlying buffer — it only resets the current read position. The flag has no effect on any other built-in BIO types. 🔄
  • BIO_FLAGS_IN_EOF — a BIO implementation may use this flag to say the end of the input stream has been reached. But BIO types are not required to use this flag to signal end-of-file conditions; they might rely on other mechanisms, like system calls or by querying the next BIO in a chain. So applications must not test this flag directly to figure out whether EOF has been reached — use BIO_eof() instead. 🙅‍♀️
Also: there's a whole range of extra flag values reserved for internal use by OpenSSL to track kernel TLS (KTLS) state. That range and the matching flag macros are not part of the public API and must not be used by applications. Periodt. 💅

🌈 RETURN VALUES 🌈

  • BIO_get_flags() returns a bit mask of the flags currently set on the BIO.
  • BIO_test_flags() returns a bit mask consisting of those flags from the argument that are currently set in the BIO. So it returns a nonzero value if and only if at least one of the requested flags is set.
  • BIO_get_retry_flags() returns a bit mask consisting of those flags from BIO_FLAGS_READ, BIO_FLAGS_WRITE, BIO_FLAGS_IO_SPECIAL, and BIO_FLAGS_SHOULD_RETRY that are currently set in the BIO.

🦋 NOTES 🦋

Real talk: ordinary application code will rarely need to call BIO_set_flags(), BIO_clear_flags() or BIO_test_flags() directly. They're meant for BIO implementations and for code that forwards retry state from one BIO in a chain to another. After a failed I/O operation, applications should normally use BIO_should_retry() and its related macros as described in BIO_should_retry(3) instead of inspecting the flags yourself. 👑

These functions and macros are not thread-safe. If a single BIO is being accessed from multiple threads, the caller has to provide appropriate external synchronisation. No cap. 😭

👑 SEE ALSO 👑

BIO_should_retry(3), BIO_f_base64(3), bio(7)

💀 HISTORY 💀

The functions and macros described here have been available in OpenSSL since at least 1.1.0 — with BIO_FLAGS_IN_EOF showing up since 1.1.1. ✨

Copyright 2025 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

That's the whole thing, bestie — this page is version 3.0.21 and it's dated 2026-06-09, and yes the manual header really is BIO_SET_FLAGS(3ossl) 💖 slay, go retry that I/O 🫶

📦 where this page comes from