---
name: "libressl-BIO_set_callback"
section: "3"
platform: "linux"
package: "libressl"
version: "4.4.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/libressl-BIO_set_callback"
---

# libressl-BIO\_set\_callback(3)

BIO callback functions

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

Crypto Library (libcrypto, -lcrypto)

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