BIO_PUSH(3)

NAME
BIO_push, BIO_pop - add and remove BIOs from a chain

SYNOPSIS
#include <openssl/bio.h>
BIO *
BIO_push(BIO *b, BIO *append);
BIO *
BIO_pop(BIO *b);

DESCRIPTION
BIOs can be joined together to form chains. A chain normally consist 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. A single BIO can be regarded as a chain with one component.

The BIO_push() function appends the BIO append to b and returns b.

BIO_pop() removes the BIO b from a chain and returns the next BIO in the chain, or NULL if there is no next BIO. The removed BIO then becomes a single BIO with no association with the original chain. it can thus be freed or attached to a different chain.

The names of these functions are perhaps a little misleading. BIO_push() joins two BIO chains whereas BIO_pop() deletes a single BIO from a chain; the deleted BIO does not need to be at the end of a chain.

The process of calling BIO_push() and BIO_pop() on a BIO may have additional consequences: a BIO_ctrl(3) call is made to the affected BIOs. Any effects will be noted in the descriptions of individual BIOs.

RETURN VALUES
BIO_push() returns the beginning of the chain, b.

BIO_pop() returns the next BIO in the chain, or NULL if there is no next BIO.

EXAMPLES
For these examples suppose md1 and md2 are digest BIOs, b64 is a Base64 BIO and f is a file BIO.

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.