BIO_SET_CALLBACK(3)

🌸 BIO_SET_CALLBACK(3) — BIO callback functions 💅

okay so this is a page from the Library Functions Manual, and it's all about libcrypto's BIO callback situation. bestie, it's giving "trace everything, log everything, live your truth." let's get into it ✨

---

🎀 NAME 🎀

BIO_callback_fn_ex, BIO_set_callback_ex, BIO_get_callback_ex, BIO_callback_fn, BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg, BIO_debug_callback — BIO callback functions, periodt 💖

---

✨ SYNOPSIS ✨

library “libcrypto” #include <openssl/bio.h>

typedef long
(*BIO_callback_fn_ex)(BIO *b, int oper, const char *argp, size_t len,
    int argi, long argl, int ret, size_t *processed);

void
BIO_set_callback_ex(BIO *b, BIO_callback_fn_ex cb_ex);

BIO_callback_fn_ex
BIO_get_callback_ex(const BIO *b);

typedef long
(*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi,
    long argl, long ret);

void
BIO_set_callback(BIO *b, BIO_callback_fn cb);

BIO_callback_fn
BIO_get_callback(BIO *b);

void
BIO_set_callback_arg(BIO *b, char *pointer);

char *
BIO_get_callback_arg(const BIO *b);

long
BIO_debug_callback(BIO *bio, int oper, const char *argp, int argi,
    long argl, long ret);

---

🦋 DESCRIPTION 🦋

so. BIO_set_callback_ex() and BIO_get_callback_ex() are the main characters here — they set and retrieve the BIO callback. and the callback? it gets called during most high-level BIO operations. iconic. you can use it for debugging (tracing what a BIO is up to) or to actually modify its operation. main character energy fr fr 💅

BIO_set_callback() and BIO_get_callback() are deprecated functions — they set and retrieve the old-style BIO callback, which only gets used if no new-style callback was set with BIO_set_callback_ex(). legacy vibes only, ngl 🙈

BIO_set_callback_arg() stores the pointer internally in b, and BIO_get_callback_arg() retrieves it from b. okay so here's the tea: the name of these two is badly misleading — the pointer is never passed as an argument to any callback function. but of course, callback functions can call BIO_get_callback_arg() and get at the pointer, just like any other code can. iykyk 🫶

BIO_debug_callback() is a standard debugging callback that prints out information related to each BIO operation. and if BIO_set_callback_arg() was called with a non-NULL argument, the info gets sent to the BIO pointed to by the pointer; otherwise, standard error output is used. cute little default 💖

---

💜 the callback arguments 💜

the arguments of the callback functions are as follows:

• b — the BIO the callback is attached to.
• oper — the operation being performed, which is one of BIO_CB_CTRL, BIO_CB_FREE, BIO_CB_GETS, BIO_CB_PUTS, BIO_CB_READ, or BIO_CB_WRITE. for some operations, the callback is called twice — once before and once after the actual operation. that latter case has oper OR'ed with BIO_CB_RETURN.
• argp, argi, argl — the meaning of these three arguments depends on the value of oper, that is on the operation being performed.
• len — the length of the data requested to be read or written. this is only useful if oper is BIO_CB_READ, BIO_CB_WRITE, or BIO_CB_GETS.
• ret — okay this one has layers, stay with me:
  • when oper does not include BIO_CB_RETURN, i.e. when the callback is invoked before an operation, the value passed into the callback via ret is always 1. in this case, if the callback returns a negative value, the library aborts the requested operation and instead returns the negative return value from the callback to the application. if the callback returns a non-negative value, that return value is ignored by the library, and the operation is performed normally.
  • when oper includes BIO_CB_RETURN, i.e. when the callback is invoked after an operation, the value passed into the callback via ret is the return value that the operation would return to the application if no callback were present. when a callback is present, the operation only passes this value to the callback and instead of it returns the return value of the callback to the application. lowkey wild but slay 🔥
• processed — the location pointed to is updated with the number of bytes actually read or written. only used for BIO_CB_READ, BIO_CB_WRITE, BIO_CB_GETS, and BIO_CB_PUTS.

the callback should normally simply return ret when it has finished processing, unless it specifically wishes to abort the operation or to modify the value returned to the application. 👑

---

🌈 the callbacks are called as follows 🌈

In BIO_free(BIO *b):

before the free operation:
cb_ex(b, BIO_CB_FREE, NULL, 0, 0, 0, 1, NULL)
or cb(b, BIO_CB_FREE, NULL,    0, 0, 1)

In BIO_read(BIO *b, void *out, int outl):

before the read operation:
cb_ex(b, BIO_CB_READ, out, outl, 0, 0, 1, NULL)
or cb(b, BIO_CB_READ, out, outl,    0, 1)

after the read operation:
cb_ex(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0, 0, ret, &bytes)
or cb(b, BIO_CB_READ|BIO_CB_RETURN, out, outl,    0, ret)

In BIO_write(BIO *b, const void *in, int inl):

before the write operation:
cb_ex(b, BIO_CB_WRITE, in, inl, 0, 0, 1, NULL)
or cb(b, BIO_CB_WRITE, in, inl,    0, 1)

after the write operation:
cb_ex(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0, 0, ret, &bytes)
or cb(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl,    0, ret)

In BIO_gets(BIO *b, char *out, int outl):

before the read operation:
cb_ex(b, BIO_CB_GETS, out, outl, 0, 0, 1, NULL)
or cb(b, BIO_CB_GETS, out, outl,    0, 1)

after the read operation:
cb_ex(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0, 0, ret, &bytes)
or cb(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl,    0, ret)

In BIO_puts(BIO *b, const char *in):

before the write operation:
cb_ex(b, BIO_CB_PUTS, in, 0, 0, 0, 1, NULL)
or cb(b, BIO_CB_PUTS, in,    0, 0, 1)

after the write operation:
cb_ex(b, BIO_CB_PUTS|BIO_CB_RETURN, in, 0, 0, 0, ret, &bytes)
or cb(b, BIO_CB_PUTS|BIO_CB_RETURN, in,    0, 0, ret)

In BIO_ctrl(BIO *b, int cmd, long larg, void *parg):

before the control operation:
cb_ex(b, BIO_CB_CTRL, parg, 0, cmd, larg, 1, NULL)
or cb(b, BIO_CB_CTRL, parg,    cmd, larg, 1)

after the control operation:
cb_ex(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, 0, cmd, larg, ret, NULL)
or cb(b, BIO_CB_CTRL|BIO_CB_RETURN, parg,    cmd, larg, ret)

In BIO_callback_ctrl(BIO *b, int cmd, BIO_info_cb *fp):

before the control operation:
cb_ex(b, BIO_CB_CTRL, fp, 0, cmd, 0, 1, NULL)
or cb(b, BIO_CB_CTRL, fp,    cmd, 0, 1)

after the control operation:
cb_ex(b, BIO_CB_CTRL|BIO_CB_RETURN, fp, 0, cmd, 0, ret, NULL)
or cb(b, BIO_CB_CTRL|BIO_CB_RETURN, fp,    cmd, 0, ret)

---

⭐ RETURN VALUES ⭐

• BIO_get_callback_ex() returns a pointer to the function cb_ex previously installed with BIO_set_callback_cb(), or NULL if no such callback was installed.
• BIO_get_callback() returns a pointer to the function cb previously installed with BIO_set_callback(), or NULL if no such callback was installed.
• BIO_get_callback_arg() returns the pointer previously set with BIO_set_callback_arg(), or NULL if no such pointer was set.
• BIO_debug_callback() returns ret if the bit BIO_CB_RETURN is set in cmd, or 1 otherwise.

---

🍓 EXAMPLES 🍓

the BIO_debug_callback() function is a good example — go look at it, it's literally right there. its source is in the file crypto/bio/bio_cb.c. go bestie, read the source 💖

---

🧚 SEE ALSO 🧚

BIO_new(3)

---

👑 HISTORY 👑

BIO_set_callback(), BIO_get_callback(), BIO_set_callback_arg(), and BIO_debug_callback() first appeared in SSLeay 0.6.0. BIO_get_callback_arg() first appeared in SSLeay 0.8.0. these functions have been available since OpenBSD 2.4. ancient. vintage. historical icon behavior 🏛️

BIO_callback_fn() first appeared in OpenSSL 1.1.0. then BIO_callback_fn_ex(), BIO_set_callback_ex(), and BIO_get_callback_ex() first appeared in OpenSSL 1.1.1. these functions have been available since OpenBSD 7.1. glow-up complete ✨

---

and that's the whole page, bestie!! 🫶 this one's from Debian, dated June 8, 2025, filed under BIO_SET_CALLBACK(3) — go forth and trace your BIOs 💅💖