BIO_NEW(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💅 BIO_NEW — the one where we make and destroy BIOs (3ossl, bestie)

okay so this is the OpenSSL page for BIO_new_ex, BIO_new, BIO_up_ref, BIO_free, BIO_vfree, and BIO_free_all — literally the whole "allocate it and then free it" saga. it's giving birth-and-death cycle but for BIO objects 🎀

✨ 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);

bestie look at that signature block, it's so clean 😭🫶

🌸 DESCRIPTION 🌸

the new ones 👑

BIO_new_ex() hands you a shiny new BIO built with method type, and it's tied to the library context libctx (peep OSSL_LIB_CTX(3) for that whole situation). libctx can be NULL and that just means "default library context, babe, no worries". but type — and I cannot stress this enough — MUST NOT be NULL. no cap. 🚫

BIO_new() is literally the same thing as BIO_new_ex(), except the default library context is always used. always always. that's the entire diff, iconic behaviour honestly ✨

the refcount one 🧚

BIO_up_ref() bumps up the reference count hanging out with the BIO object. one more friend in the group chat 👯‍♀️

the free ones 💀

BIO_free() frees up a single BIO. BIO_vfree() also frees up a single BIO but it doesn't give you a return value back — it's the silent type 🙈. if a is NULL, nothing happens at all, we just move on with our lives.

⚠️ heads up: calling BIO_free() can also do stuff to the underlying I/O structure — like, under certain circumstances it may close the file being referred to 😳. for the full tea, check out the individual BIO_METHOD descriptions.

BIO_free_all() frees up a whole entire BIO chain, and it does not halt if an error happens while freeing up an individual BIO in the chain. it keeps going, main character energy, nothing stops her 💅. if a is NULL, nothing is done.

⭐ 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() — don't return values, they simply do not participate in the return-value economy 🙅‍♀️

🦋 NOTES 🦋

  • if you call BIO_free() on a BIO chain, it will only free one BIO, which results in a memory leak 😬 bestie don't do it, that's the leaky behaviour.
  • calling BIO_free_all() on a single BIO has the same effect as calling BIO_free() on it — except the return value gets yeeted into the void.

🎀 HISTORY 🎀

  • BIO_set() was removed in OpenSSL 1.1.0, because the BIO type is opaque now. gone, girl, gone.
  • BIO_new_ex() was added in OpenSSL 3.0 — the new kid on the block, and we love her 🌈

🔥 EXAMPLES 🔥

so like, if you wanna create a memory BIO, it's literally this:

BIO *mem = BIO_new(BIO_s_mem());

that's it. that's the whole vibe. go off ✨

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 3.5.0, dated 2026-09-25. mwah, go free your BIOs responsibly 💖💅

📦 where this page comes from