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