BIO_PUSH(3) | Library Functions Manual | BIO_PUSH(3)

# NAME

`BIO_push`, `BIO_pop`, `BIO_set_next` — manipulate BIO chains

# SYNOPSIS

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

BIO *
`BIO_push`(BIO *b, BIO *new_tail);

BIO *
`BIO_pop`(BIO *b);

void
`BIO_set_next`(BIO *b, BIO *new_tail);

# DESCRIPTION

BIOs can be joined together to form chains. A chain normally consists of one or more filter BIOs and one source/sink BIO at the end. Data read from or written to the first BIO traverses the chain to the end.

Every BIO is a member of exactly one chain. It is either at the beginning of its chain or there is exactly one preceding BIO. It is either at the end of its chain or there is exactly one following BIO. If there is neither a preceding nor a following BIO, it can be regarded as a chain with one member. Every chain has exactly one beginning and exactly one end.

`BIO_push`() appends the chain starting at new_tail to the end of the chain that contains b. Unless b is `NULL`, it then calls BIO_ctrl(3) on b with an argument of `BIO_CTRL_PUSH`. If b or new_tail is `NULL`, nothing is appended.

In LibreSSL, if new_tail is not at the beginning of its chain, the head of that chain up to but not including new_tail is cut off and becomes a separate chain. For portability, it is best to make sure that new_tail is at the beginning of its chain before calling `BIO_push`().

`BIO_pop`() removes the BIO b from its chain. Despite the word “pop” in the function name, b can be at the beginning, in the middle, or at the end of its chain. Before removal, BIO_ctrl(3) is called on b with an argument of `BIO_CTRL_POP`. The removed BIO b becomes the only member of its own chain and can thus be freed or attached to a different chain. If b is `NULL`, no action occurs.

`BIO_set_next`() appends the chain starting with new_tail to the chain ending with b.

In LibreSSL, if new_tail is not at the beginning of its chain, the head of that chain up to but not including new_tail is cut off and becomes a separate chain, and if b is not at the end of its chain, the tail of that chain starting after b is cut off and becomes a separate chain.

For portability, it is best to make sure that b is at the end of its chain and that new_tail is at the beginning of its chain before calling `BIO_set_next`() and to avoid calling `BIO_pop`() on new_tail afterwards.

In LibreSSL, the only built-in BIO type for which BIO_ctrl(3) calls with an argument of `BIO_CTRL_PUSH` or `BIO_CTRL_POP` have any effect is BIO_f_ssl(3).

# RETURN VALUES

`BIO_push`() returns b if it is not `NULL` or new_tail if it is.

`BIO_pop`() returns the BIO that followed b in its chain, or `NULL` if b is `NULL` or was at the end of its chain.

# EXAMPLES

For these examples suppose md1 and md2 are digest BIOs, b64 is a Base64 BIO and f is a file BIO (see BIO_f_md(3), BIO_f_base64(3), and BIO_s_file(3), respectively).

If the call

`BIO_push(b64, f);`

is made then the new chain will be b64-f. After making the calls

    BIO_push(md2, b64);
    BIO_push(md1, md2);

the new chain is md1-md2-b64-f. Data written to md1 will be digested by md1 and md2, Base64-encoded and written to f.

It should be noted that reading causes data to pass in the reverse direction. That is, data is read from f, Base64-decoded and digested by md1 and md2. If this call is made:

`BIO_pop(md2);`

The call will return b64 and the new chain will be md1-b64-f; data can be written to md1 as before.

# SEE ALSO

BIO_find_type(3), BIO_new(3), BIO_read(3)

# HISTORY

`BIO_push`() first appeared in SSLeay 0.6.0. `BIO_pop`() first appeared in SSLeay 0.6.4. Both functions have been available since OpenBSD 2.4.

`BIO_set_next`() first appeared in OpenSSL 1.1.0 and has been available since OpenBSD 7.1.

# CAVEATS

Creating a cyclic chain results in undefined behavior. For example, infinite recursion or infinite loops may ensue.

If it is unknown whether b and new_tail are already members of the same chain and whether joining them would create a cycle, the calling code can use the following safe idiom:

    BIO *btest;

    for (btest = new_tail; btest != NULL; btest = BIO_next(btest))
    	if (btest == b)
    		/* Bail out because this would create a cycle. */
    BIO_push(b, new_tail);  /* This is now safe. */

The same idiom can be used with `BIO_set_next`() instead of `BIO_push`().

Often, the safe idiom is not needed because it is already known that b and new_tail are not members of the same chain, for example when b or new_tail was created right before.

June 8, 2025 | Debian