#use wml::openssl-macros area=docs page=BIO_push

<title>Documents, BIO_push(3)</title>

<h1>BIO_push(3)</h1>

#use wml::imp::generic

{:
## What's this? [[s|(<STRONG>[^<].+?)</A>(</STRONG><DD>)|$1$2|sg]]
[[s|<P>\s+<P>|<P>|sg]]
[[s|<P>\s+</|</|sg]]
[[s|<DD>\s*<DT>|<DD>&nbsp;<DT>|sg]]
[[s|<DD>\s*</DL>|<DD>&nbsp;</DL>|sg]]
[[s|\[|&#91;|sg]]
[[s|\]|&#93;|sg]]

<!-- INDEX BEGIN -->

<UL>

	<LI><A HREF="#NAME">NAME</A>
	<LI><A HREF="#SYNOPSIS">SYNOPSIS</A>
	<LI><A HREF="#DESCRIPTION">DESCRIPTION</A>
	<LI><A HREF="#NOTES">NOTES</A>
	<LI><A HREF="#EXAMPLES">EXAMPLES</A>
	<LI><A HREF="#RETURN_VALUES">RETURN VALUES</A>
	<LI><A HREF="#SEE_ALSO">SEE ALSO</A>
</UL>
<!-- INDEX END -->

<HR>
<P>
<HR>
<H1><A NAME="NAME">NAME</A></H1>
<P>
BIO_push, BIO_pop - add and remove BIOs from a chain.

</P>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/bio.h&gt;
</PRE>
<PRE> BIO *  BIO_push(BIO *b,BIO *append);
 BIO *  BIO_pop(BIO *b);
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
The <CODE>BIO_push()</CODE> function appends the BIO <STRONG>append</STRONG> to <STRONG>b</STRONG>, it returns
<STRONG>b</STRONG>.

</P>
<P>
<CODE>BIO_pop()</CODE> removes the BIO <STRONG>b</STRONG> 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.

</P>
<P>
<HR>
<H1><A NAME="NOTES">NOTES</A></H1>
<P>
The names of these functions are perhaps a little misleading.
<CODE>BIO_push()</CODE> joins two BIO chains whereas <CODE>BIO_pop()</CODE>
deletes a single BIO from a chain, the deleted BIO does not need to be at
the end of a chain.

</P>
<P>
The process of calling <CODE>BIO_push()</CODE> and <CODE>BIO_pop()</CODE>
on a BIO may have additional consequences (a control call is made to the
affected BIOs) any effects will be noted in the descriptions of individual
BIOs.

</P>
<P>
<HR>
<H1><A NAME="EXAMPLES">EXAMPLES</A></H1>
<P>
For these examples suppose <STRONG>md1</STRONG> and <STRONG>md2</STRONG> are digest BIOs, <STRONG>b64</STRONG> is a base64 BIO and <STRONG>f</STRONG> is a file BIO.

</P>
<P>
If the call:

</P>
<PRE> BIO_push(b64, f);
</PRE>
<P>
is made then the new chain will be <STRONG>b64-chain</STRONG>. After making the calls

</P>
<PRE> BIO_push(md2, b64);
 BIO_push(md1, md2);
</PRE>
<P>
the new chain is <STRONG>md1-md2-b64-f</STRONG>. Data written to <STRONG>md1</STRONG> will be digested by <STRONG>md1</STRONG> and <STRONG>md2</STRONG>, <STRONG>base64</STRONG> encoded and written to <STRONG>f</STRONG>.

</P>
<P>
It should be noted that reading causes data to pass in the reverse
direction, that is data is read from <STRONG>f</STRONG>, base64 <STRONG>decoded</STRONG> and digested by <STRONG>md1</STRONG> and <STRONG>md2</STRONG>. If the call:

</P>
<PRE> BIO_pop(md2);
</PRE>
<P>
The call will return <STRONG>b64</STRONG> and the new chain will be <STRONG>md1-b64-f</STRONG> data can be written to <STRONG>md1</STRONG> as before.

</P>
<P>
<HR>
<H1><A NAME="RETURN_VALUES">RETURN VALUES</A></H1>
<P>
<CODE>BIO_push()</CODE> returns the end of the chain, <STRONG>b</STRONG>.

</P>
<P>
<CODE>BIO_pop()</CODE> returns the next BIO in the chain, or NULL if there
is no next BIO.

</P>
<P>
<HR>
<H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
<P>
TBA
</P>
:}