BIO_METH_NEW(3ossl)

💅 BIO_METH_NEW(3ossl) — the OpenSSL manual, but make it make sense

okay bestie, welcome to the BIO_METHOD page from OpenSSL ✨ this is the "build your own BIO type" toolkit and honestly it's giving backstage-pass energy 🎀

✨ NAME ✨

So basically this whole page is about the routines that build up BIO methods, and here's the full cast — no one's getting cut, I promise 🫶

BIO_get_new_index, BIO_meth_new, BIO_meth_free, BIO_meth_get_read_ex, BIO_meth_set_read_ex, BIO_meth_get_write_ex, BIO_meth_set_write_ex, BIO_meth_get_write, BIO_meth_set_write, BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts, BIO_meth_set_puts, BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl, BIO_meth_set_ctrl, BIO_meth_get_create, BIO_meth_set_create, BIO_meth_get_destroy, BIO_meth_set_destroy, BIO_meth_get_callback_ctrl, BIO_meth_set_callback_ctrl, BIO_meth_set_sendmmsg, BIO_meth_get_sendmmsg, BIO_meth_set_recvmmsg, BIO_meth_get_recvmmsg

…and what do they do? They're the routines to build up BIO methods. that's the whole vibe 💖

🌸 SYNOPSIS 🌸

#include <openssl/bio.h>

int BIO_get_new_index(void);

BIO_METHOD *BIO_meth_new(int type, const char *name);

void BIO_meth_free(BIO_METHOD *biom);

int BIO_meth_set_write_ex(BIO_METHOD *biom,
                          int (*bwrite)(BIO *, const char *, size_t, size_t *));
int BIO_meth_set_write(BIO_METHOD *biom,
                       int (*write)(BIO *, const char *, int));

int BIO_meth_set_read_ex(BIO_METHOD *biom,
                         int (*bread)(BIO *, char *, size_t, size_t *));
int BIO_meth_set_read(BIO_METHOD *biom, int (*read)(BIO *, char *, int));

int BIO_meth_set_puts(BIO_METHOD *biom, int (*puts)(BIO *, const char *));
int BIO_meth_set_gets(BIO_METHOD *biom,
                      int (*gets)(BIO *, char *, int));

int BIO_meth_set_ctrl(BIO_METHOD *biom,
                      long (*ctrl)(BIO *, int, long, void *));

int BIO_meth_set_create(BIO_METHOD *biom, int (*create)(BIO *));
int BIO_meth_set_destroy(BIO_METHOD *biom, int (*destroy)(BIO *));

int BIO_meth_set_callback_ctrl(BIO_METHOD *biom,
                               long (*callback_ctrl)(BIO *, int, BIO_info_cb *));

int BIO_meth_set_sendmmsg(BIO_METHOD *biom,
                          ossl_ssize_t (*f) (BIO *, BIO_MSG *, size_t,
                                             size_t, uint64_t));
int BIO_meth_set_recvmmsg(BIO_METHOD *biom,
                          ossl_ssize_t (*f) (BIO *, BIO_MSG *, size_t,
                                             size_t, uint64_t));

and here are the deprecated girlies — the following functions have been deprecated since OpenSSL 3.5 👑 (still in the synopsis, still documented, but yeah, they're on the way out):

int (*BIO_meth_get_write_ex(const BIO_METHOD *biom))(BIO *, const char *, size_t,
                                               size_t *);
int (*BIO_meth_get_write(const BIO_METHOD *biom))(BIO *, const char *, int);

int (*BIO_meth_get_read_ex(const BIO_METHOD *biom))(BIO *, char *, size_t, size_t *);
int (*BIO_meth_get_read(const BIO_METHOD *biom))(BIO *, char *, int);

int (*BIO_meth_get_puts(const BIO_METHOD *biom))(BIO *, const char *);
int (*BIO_meth_get_gets(const BIO_METHOD *biom))(BIO *, char *, int);

long (*BIO_meth_get_ctrl(const BIO_METHOD *biom))(BIO *, int, long, void *);

int (*BIO_meth_get_create(const BIO_METHOD *bion))(BIO *);
int (*BIO_meth_get_destroy(const BIO_METHOD *biom))(BIO *);

long (*BIO_meth_get_callback_ctrl(const BIO_METHOD *biom))(BIO *, int, BIO_info_cb *);

ossl_ssize_t (*BIO_meth_get_sendmmsg(const BIO_METHOD *biom))(BIO *,
                                                              BIO_MSG *,
                                                              size_t,
                                                              size_t,
                                                              uint64_t);
ossl_ssize_t (*BIO_meth_get_recvmmsg(const BIO_METHOD *biom))(BIO *,
                                                              BIO_MSG *,
                                                              size_t,
                                                              size_t,
                                                              uint64_t);

🦋 DESCRIPTION 🦋

okay so, the <italic>BIO_METHOD</italic> type is a structure used for the implementation of new BIO types 🔥 it hands OpenSSL a whole set of functions it uses to implement all the various BIO capabilities. want more context? go read the bio(7) page, iykyk 💜

BIO_meth_new() creates a new BIO_METHOD structure holding a type identifier <italic>type</italic> and a string that represents its name (that's the <italic>name</italic>). and <italic>type</italic>? you can set it to either BIO_TYPE_NONE or via BIO_get_new_index() if you need a unique type for searching (peep BIO_find_type(3)) 🔍

🚨 heads up bestie: BIO_get_new_index() can only be used 127 times before it returns an error. that's the whole budget. no cap.

The set of standard OpenSSL provided BIO types lives in <openssl/bio.h>. some examples include BIO_TYPE_BUFFER and BIO_TYPE_CIPHER ✨

Filter BIOs should have a type with the "filter" bit set (BIO_TYPE_FILTER).
Source/sink BIOs should have the "source/sink" bit set (BIO_TYPE_SOURCE_SINK).
File descriptor based BIOs (e.g. socket, fd, connect, accept etc) should additionally have the "descriptor" bit set (BIO_TYPE_DESCRIPTOR).

see the BIO_find_type(3) page for more info 🫶

BIO_meth_free() destroys a BIO_METHOD structure and frees up any memory associated with it. if the argument is NULL, nothing is done. literally nothing. vibes only 💀

💖 the write/read duo (the "ex" girlies and their legacy versions) 💖

BIO_meth_get_write_ex() and BIO_meth_set_write_ex() get and set the function used for writing arbitrary length data to the BIO, respectively. this function gets called in response to the application calling BIO_write_ex() or BIO_write(), and its parameters have the same meaning as for BIO_write_ex(). older code may call BIO_meth_get_write() and BIO_meth_set_write() instead.

⚠️ gamely warning fr fr: applications should not call both BIO_meth_set_write_ex() and BIO_meth_set_write(), and should not call BIO_meth_get_write() when the function was set with BIO_meth_set_write_ex(). pick a lane bestie 😭

BIO_meth_get_read_ex() and BIO_meth_set_read_ex() get and set the function used for reading arbitrary length data from the BIO, respectively. this one gets called in response to the application calling BIO_read_ex() or BIO_read(), and the parameters have the same meaning as for BIO_read_ex(). older code may call BIO_meth_get_read() and BIO_meth_set_read() instead.

⚠️ same deal: applications should not call both BIO_meth_set_read_ex() and BIO_meth_set_read(), or call BIO_meth_get_read() when the function was set with BIO_meth_set_read_ex(). 🔥 don't do it.

🎀 puts & gets 🎀

BIO_meth_get_puts() and BIO_meth_set_puts() get and set the function used for writing a NULL terminated string to the BIO, respectively. called in response to the application calling BIO_puts(), and the parameters have the same meaning as for BIO_puts() 💅

BIO_meth_get_gets() and BIO_meth_set_gets() get and set the function typically used for reading a line of data from the BIO, respectively (see the BIO_gets(3) page for more). called in response to the application calling BIO_gets(), and the parameters have the same meaning as for BIO_gets() 🍓

🌈 ctrl stuff 🌈

BIO_meth_get_ctrl() and BIO_meth_set_ctrl() get and set the function used for processing ctrl messages in the BIO, respectively. see the BIO_ctrl(3) page for more. called in response to the application calling BIO_ctrl(), and the parameters have the same meaning as for BIO_ctrl() ⭐

BIO_meth_get_callback_ctrl() and BIO_meth_set_callback_ctrl() get and set the function used for processing callback ctrl messages in the BIO, respectively. see the BIO_callback_ctrl(3) page for more. called in response to the application calling BIO_callback_ctrl(), and the parameters have the same meaning as for BIO_callback_ctrl() 🧚

👑 create & destroy (birth and farewell) 👑

BIO_meth_get_create() and BIO_meth_set_create() get and set the function used for creating a new instance of the BIO, respectively. this gets called in response to the application calling BIO_new() and passing in a pointer to the current BIO_METHOD. BIO_new() will allocate the memory for the new BIO, and a pointer to this newly allocated structure gets passed as a parameter to the function.

👀 important: if a create function is set, BIO_new() will not mark the BIO as initialised on allocation. BIO_set_init(3) must then be called either by the create function, or later, by a BIO ctrl function, once BIO initialisation is complete. don't forget or it's giving chaos 😭

BIO_meth_get_destroy() and BIO_meth_set_destroy() get and set the function used for destroying an instance of a BIO, respectively. called in response to the application calling BIO_free(), with a pointer to the BIO to be destroyed passed as a parameter. the destroy function should be used for BIO specific clean up — the memory for the BIO itself should not be freed by this function 🫶 (that's not its job, respect the role)

🔥 the mmsg girlies 🔥

BIO_meth_get_sendmmsg(), BIO_meth_set_sendmmsg(), BIO_meth_get_recvmmsg() and BIO_meth_set_recvmmsg() get and set the functions used for handling BIO_sendmmsg() and BIO_recvmmsg() calls, respectively. see BIO_sendmmsg(3) for more information 💜

⭐ RETURN VALUES ⭐

BIO_get_new_index() returns the new BIO type value, or -1 if an error occurred 😬
BIO_meth_new(int type, const char *name) returns a valid BIO_METHOD, or NULL if an error occurred.
the BIO_meth_set functions return 1 on success or 0 on error.
the BIO_meth_get functions return the corresponding function pointers 🎀

💀 BUGS 💀

okay so this is the important one, listen up:

it is not safe to use "BIO_meth_get_" functions to reuse the BIO implementation of BIOs implemented by OpenSSL itself with application-implemented BIOs. instead, either the applications ought to implement these functions themselves, or they should implement a filter BIO. 🚩

for more details please see <https://github.com/openssl/openssl/issues/26047> 👀

🦋 HISTORY 🦋

the functions BIO_meth_get_sendmmsg(), BIO_meth_set_sendmmsg(), BIO_meth_get_recvmmsg() and BIO_meth_set_recvmmsg() were added in OpenSSL 3.2 ✨
all the other functions described here were added in OpenSSL 1.1.0 👑
the functions BIO_meth_get_read_ex(), BIO_meth_get_write_ex(), BIO_meth_get_write(), BIO_meth_get_read(), BIO_meth_get_puts(), BIO_meth_get_gets(), BIO_meth_get_ctrl(), BIO_meth_get_create(), BIO_meth_get_destroy(), BIO_meth_get_callback_ctrl(), BIO_meth_get_sendmmsg() and BIO_meth_get_recvmmsg() are deprecated since OpenSSL 3.5 💀

💖 COPYRIGHT 💖

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 3.5.0, dated 2026-09-25, filed under BIO_METH_NEW(3ossl) — slay, go build yourself a BIO method, periodt 💅✨

📦 where this page comes from

opensuse-leap 16.0: openssl-3-doc 3.5.0-160000.11.1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

BIO_METH_NEW(3ossl)