BIO_METH_NEW(3ossl)

📦

version 15.1 · 2 versions

15.1 · freebsd 15.1 (latest)
14.5 · freebsd 14.5

💅 BIO_METH_NEW(3ossl) 💅

okay so this is the OpenSSL manual page for BIO_METHOD-building stuff, and honestly? it's giving "make your own BIO from scratch" energy. the manual is 3ossl, she's iconic, let's get into it 🎀

✨ NAME ✨

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 — literally all of them, and they're all here for one reason: 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));

The following functions have been deprecated since OpenSSL 3.5:

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

🙈 yes bestie, BIO_meth_get_create() really does take a parameter named bion in the synopsis. that's not a typo i made, that's canon. copy it exactly, i'm begging.

💖 DESCRIPTION 💖

so BIO_METHOD is a structure — and it's the whole blueprint for implementing brand-new BIO types. it hands OpenSSL a little set of functions that OpenSSL calls into to make all the different BIO capabilities actually work. if you wanna know more about BIOs themselves, go read the bio(7) page, she's the main character 👑

🦋 makin' one: `BIO_meth_new()`

BIO_meth_new() creates a fresh new BIO_METHOD structure, packed with a type identifier type and a string that represents its name.

type can be set to either BIO_TYPE_NONE, or via BIO_get_new_index() if you need a unique type for searching (see BIO_find_type(3)).

⚠️ important heads-up: BIO_get_new_index() can only be used 127 times before it returns an error. that's it. that's the budget. no cap 😭

🌈 the standard types, and the bit flags

The set of standard OpenSSL-provided BIO types lives in <openssl/bio.h>. some examples include BIO_TYPE_BUFFER and BIO_TYPE_CIPHER. here's the tea on the bit flags:

Filter BIOs should have a type which has 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()`

BIO_meth_free() destroys a BIO_METHOD structure and frees up any memory associated with it. if the argument is NULL, nothing is done — she just shrugs and moves on 🫶

🍓 `BIO_meth_get_write_ex()` / `BIO_meth_set_write_ex()`

these get and set the function used for writing arbitrary length data to the BIO, respectively. this function gets called in response to your application calling BIO_write_ex() or BIO_write(). the parameters for the function have the same meaning as for BIO_write_ex().

older code may call BIO_meth_get_write() and BIO_meth_set_write() instead.

💀 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()` / `BIO_meth_set_read_ex()`

these get and set the function used for reading arbitrary length data from the BIO, respectively. it gets called in response to your application calling BIO_read_ex() or BIO_read(). the parameters for the function have the same meaning as for BIO_read_ex().

older code may call BIO_meth_get_read() and BIO_meth_set_read() instead.

💀 same rule, opposite direction: applications should not call both BIO_meth_set_read_ex() and BIO_meth_set_read(), and should not call BIO_meth_get_read() when the function was set with BIO_meth_set_read_ex().

🌸 `BIO_meth_get_puts()` / `BIO_meth_set_puts()`

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

⭐ `BIO_meth_get_gets()` / `BIO_meth_set_gets()`

these get and set the function typically used for reading a line of data from the BIO, respectively (peep the BIO_gets(3) page for more info). it gets called in response to your application calling BIO_gets(). the parameters for the function have the same meaning as for BIO_gets().

🎀 `BIO_meth_get_ctrl()` / `BIO_meth_set_ctrl()`

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

🦋 `BIO_meth_get_create()` / `BIO_meth_set_create()`

these get and set the function used for creating a new instance of the BIO, respectively. it gets called in response to your application calling BIO_new() and passing in a pointer to the current BIO_METHOD.

here's the important bit 👀 — BIO_new() will allocate the memory for the new BIO, and a pointer to this newly allocated structure will get passed as a parameter to the function. and if a create function is set, BIO_new() will not mark the BIO as initialised on allocation. so 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 uninitialised chaos 😭

🌈 `BIO_meth_get_destroy()` / `BIO_meth_set_destroy()`

these get and set the function used for destroying an instance of a BIO, respectively. it gets called in response to your application calling BIO_free(). a pointer to the BIO to be destroyed gets passed as a parameter.

the destroy function should be used for BIO-specific clean up. and the memory for the BIO itself should not be freed by this function — that's not her job, okay? 💅

💜 `BIO_meth_get_callback_ctrl()` / `BIO_meth_set_callback_ctrl()`

these get and set the function used for processing callback ctrl messages in the BIO, respectively. see the BIO_callback_ctrl(3) page for the details. it gets called in response to your application calling BIO_callback_ctrl(). the parameters for the function have the same meaning as for BIO_callback_ctrl().

🫶 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 info 🔥

👑 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, listen up, this one matters:

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

like, genuinely, don't do it. i'm not being cute about this one 🙈

🎀 HISTORY 🎀

BIO_meth_get_sendmmsg(), BIO_meth_set_sendmmsg(), BIO_meth_get_recvmmsg() and BIO_meth_set_recvmmsg() were added in OpenSSL 3.2. new girls on the block ✨
all the other functions described here were added in OpenSSL 1.1.0. the OGs 🫶
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. they're retired, we still love them, but do not build new stuff on them 💅

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

okay that's the whole page bestie, you ate that 🍓✨ this was OpenSSL 3.5.6, dated 2026-04-07, filed under BIO_METH_NEW(3ossl) — go forth and build your own BIOs, you've got this 💜🦋

📦 where this page comes from

freebsd 15.1: base 15.1
💖 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)

💅 BIO_METH_NEW(3ossl) 💅

✨ NAME ✨

🌸 SYNOPSIS 🌸

💖 DESCRIPTION 💖

🦋 makin' one: BIO_meth_new()

🌈 the standard types, and the bit flags

🎀 BIO_meth_free()

🍓 BIO_meth_get_write_ex() / BIO_meth_set_write_ex()

🧚 BIO_meth_get_read_ex() / BIO_meth_set_read_ex()

🌸 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()