BIO_PUSH(3ossl)

💅 BIO_PUSH(3ossl) — the OpenSSL queen of chain-building

Okay bestie, so this one's from the OpenSSL manual, and it's literally all about linking BIOs into a chain and un-linking them again. BIO_push, BIO_pop, BIO_set_next — the holy trinity of "who's next in line" 🎀

---

✨ NAME ✨

BIO_push, BIO_pop, BIO_set_next — add and remove BIOs from a chain. That's it, that's the whole vibe 🦋

---

🌸 SYNOPSIS 🌸

#include <openssl/bio.h>

BIO *BIO_push(BIO *b, BIO *next);
BIO *BIO_pop(BIO *b);
void BIO_set_next(BIO *b, BIO *next);

---

💖 DESCRIPTION 💖

BIO_push() — the "you're coming with me" move 👑

BIO_push() pushes b on next. Real talk: if b is NULL, the function does nothing and just returns next (iconic low-effort behaviour, honestly). Otherwise it prepends b — which can be a single BIO or a whole chain of BIOs — to next (unless next is NULL, in which case, you know, nothing to prepend to). Then it makes a control call on b and returns b.

BIO_pop() — the "we need to talk" move 💔

BIO_pop() removes the BIO b from any chain it's part of. If b is NULL, it does nothing and returns NULL. Otherwise it makes a control call on b and returns the next BIO in the chain, or NULL if there is no next BIO. The removed BIO becomes a single BIO with zero association to the original chain — so it's free to be freed or to go be part of a different chain. Glow-up era ✨

BIO_set_next() — the "plot twist" move 🌀

BIO_set_next() replaces the existing next BIO in a chain with the BIO pointed to by next. And ngl, the new chain can include some of the same BIOs from the old chain, or it can be completely different. No rules, we love that for her 💅

---

🫶 NOTES 🫶

The names of these functions are, perhaps, a little misleading — okay they're kind of a lot misleading. BIO_push() joins two BIO chains, whereas BIO_pop() deletes a single BIO from a chain, and the deleted BIO doesn't need to be at the end of a chain. The way that "pop" sounds like a stack thing? Yeah no, that's not what's happening here 😭

Also, the process of calling BIO_push() and BIO_pop() on a BIO may have additional consequences — a control call is made to the affected BIOs. Any effects will be noted in the descriptions of individual BIOs. So, like, check those before you get surprised, bestie 🙈

---

🔥 RETURN VALUES 🔥

• BIO_push() — returns the head of the chain, which usually is b, or next if b is NULL.
• BIO_pop() — returns the next BIO in the chain, or NULL if there is no next BIO.

---

🍓 EXAMPLES 🍓

For these examples, suppose md1 and md2 are digest BIOs, b64 is a base64 BIO, and f is a file BIO.

If the call:

BIO_push(b64, f);

is made, then the new chain will be b64-f. Slay.

After making the calls:

BIO_push(md2, b64);
BIO_push(md1, md2);

the new chain is md1-md2-b64-f. Data written to md1 will be digested by md1 and md2, base64 encoded, and finally written to f. Look at her go, a whole pipeline 💜

It should be noted that reading causes data to pass in the reverse direction — that is, data is read from f, base64 decoded, and digested by md2 and then md1. Yes, it goes both ways, main character energy 🌈

The call:

BIO_pop(md2);

will return b64, and the new chain will be md1-b64-f. Data can be written to and read from md1 as before, except that md2 will no more be applied. She said "not me participating anymore" 💀

---

🌟 SEE ALSO 🌟

• bio(7)

---

👑 HISTORY 👑

The BIO_set_next() function was added in OpenSSL 1.1.0. A whole era 🎀

---

💜 COPYRIGHT 💜

Copyright 2000-2021 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>.

---

Fr fr, this is version 3.5.0 and it's dated 2026-09-25 — so bestie, that's the BIO_PUSH(3ossl) page, OpenSSL edition, fully documented and looking expensive 💅✨