BIO_SET_CALLBACK(3) | Library Functions Manual | BIO_SET_CALLBACK(3)

# 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

# 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

`BIO_set_callback_ex`() and `BIO_get_callback_ex`() set and retrieve the BIO callback. The callback is called during most high-level BIO operations. It can be used for debugging purposes to trace operations on a BIO or to modify its operation.

`BIO_set_callback`() and `BIO_get_callback`() are deprecated functions that set and retrieve the old-style BIO callback, which is only used if no new-style callback is set with `BIO_set_callback_ex`().

`BIO_set_callback_arg`() stores the pointer internally in b and `BIO_get_callback_arg`() retrieves it from b. The name of these two functions 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 access the pointer, just like any other code can.

`BIO_debug_callback`() is a standard debugging callback which prints out information related to each BIO operation. If `BIO_set_callback_arg`() was called with a non-`NULL` argument, information is sent to the BIO pointed to by the pointer; otherwise, standard error output is used.

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

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. Its source is in the file crypto/bio/bio_cb.c.

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

`BIO_callback_fn`() first appeared in OpenSSL 1.1.0. `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.

June 8, 2025 | Debian