BIO_NEW(3ossl)

💖 BIO_NEW(3ossl) 💖

okay bestie, gather round, because today we're talking about the BIO_new_ex, BIO_new, BIO_up_ref, BIO_free, BIO_vfree and BIO_free_all girlies — aka the BIO allocation and freeing functions from OpenSSL. yes this is the 3ossl manual page. no you may not skip it. 🎀

---

✨ SYNOPSIS ✨

#include <openssl/bio.h>

BIO *BIO_new_ex(OSSL_LIB_CTX *libctx, const BIO_METHOD *type);
BIO *BIO_new(const BIO_METHOD *type);
int BIO_up_ref(BIO *a);
int BIO_free(BIO *a);
void BIO_vfree(BIO *a);
void BIO_free_all(BIO *a);

---

🌸 DESCRIPTION 🌸

so. let's go function by function, because they are NOT interchangeable and I need you to internalise that.

• BIO_new_ex() — hands you a brand new BIO that uses the method type, and it's tied to the library context libctx (peep OSSL_LIB_CTX(3) if you wanna know more about that whole situation). that libctx can be NULL and that just means "use the default library context, babe". but type? type MUST NOT be NULL. like, at all. ever. 💀
• BIO_new() — literally the same as BIO_new_ex(), except it always uses the default library context. no options, no choices, just vibes.
• BIO_up_ref() — bumps up the reference count on the BIO object. it's giving "we're keeping this one around a bit longer" energy. 👑
• BIO_free() — frees up a single BIO. one. singular. BIO_vfree() also frees up a single BIO, but it doesn't return a value, so it's the chill, no-receipts version. if a is NULL, nothing happens — no drama, no crash. also important: calling BIO_free() may have some effect on the underlying I/O structure too, like it might close the file being referred to under certain circumstances. for the deets on that, go read the individual BIO_METHOD descriptions, because the specifics live there. 🔍
• BIO_free_all() — this one frees up an entire BIO chain. and here's the thing: it does not halt if an error occurs freeing up an individual BIO in the chain. it just keeps going. if a is NULL, nothing is done. simple as.

---

💫 RETURN VALUES 💫

• BIO_new_ex() and BIO_new() return a newly created BIO, or NULL if the call fails. 😭
• BIO_up_ref() and BIO_free() return 1 for success and 0 for failure.
• BIO_free_all() and BIO_vfree() do not return values. they just do the thing and leave.

---

🦋 NOTES 🦋

⚠️ listen. if you call BIO_free() on a BIO chain, it will only free one BIO. that means you get a memory leak. do not do this. I am begging. 🙈

and fyi: calling BIO_free_all() on a single BIO has the same effect as calling BIO_free() on it, other than the discarded return value. so like, same outcome, just without the receipt.

---

⭐ HISTORY ⭐

• BIO_set() was removed in OpenSSL 1.1.0, because the BIO type is now opaque. she's private now, no peeking. 💅
• BIO_new_ex() was added in OpenSSL 3.0. new girl on the block, and she ate.

---

🌈 EXAMPLES 🌈

create a memory BIO, bestie:

BIO *mem = BIO_new(BIO_s_mem());

that's it. that's the whole example. iconic. ✨

---

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

---

and that's the whole page, bestie!! 🫶 this was BIO_NEW(3ossl) from OpenSSL version 3.5.9, dated 2026-09-29 — screenshot it, memorise it, free your BIOs responsibly. mwah. 💜🧚💖