#use wml::openssl area=docs page=BIO_new_bio_pair

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

<h1>BIO_new_bio_pair(3)</h1>

#use wml::imp::generic

{:
[[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]]

<!-- INDEX BEGIN -->

<UL>

	<LI><A HREF="#NAME">NAME</A>
	<LI><A HREF="#SYNOPSIS">SYNOPSIS</A>
	<LI><A HREF="#DESCRIPTION">DESCRIPTION</A>
	<LI><A HREF="#EXAMPLE">EXAMPLE</A>
	<LI><A HREF="#WARNING">WARNING</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_new_bio_pair - create a new BIO pair

</P>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/bio.h&gt;
</PRE>
<PRE> int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2);
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
<CODE>BIO_new_bio_pair()</CODE> creates a buffering BIO pair based on the
<A HREF="../ssl/SSL_set_bio.html#">SSL_set_bio(3)</A> method. The BIO pair has two endpoints between which data can be buffered.
Its typical use is to connect one endpoint as underlying input/output BIO
to an SSL and access the other one controlled by the program instead of
accessing the network connection directly.

</P>
<P>
The two new BIOs <STRONG>bio1</STRONG> and <STRONG>bio2</STRONG> are symmetric with respect to their functionality. The size of their
buffers is determined by <STRONG>writebuf1</STRONG> and
<STRONG>writebuf2</STRONG>. If the size give is 0, the default size is used.

</P>
<P>
<CODE>BIO_new_bio_pair()</CODE> does not check whether <STRONG>bio1</STRONG> or <STRONG>bio2</STRONG> do point to some other BIO, the values are overwritten,
<CODE>BIO_free()</CODE> is not called.

</P>
<P>
The two BIOs, even though forming a BIO pair and must be
<CODE>BIO_free()'ed</CODE> separately. This can be of importance, as some
SSL-functions like <CODE>SSL_set_bio()</CODE> or <CODE>SSL_free()</CODE>
call <CODE>BIO_free()</CODE> implicitly, so that the peer-BIO is left
untouched and must also be <CODE>BIO_free()'ed.</CODE>

</P>
<P>
<HR>
<H1><A NAME="EXAMPLE">EXAMPLE</A></H1>
<P>
The BIO pair can be used to have full control over the network access of an
application. The application can call <CODE>select()</CODE> on the socket
as required without having to go through the SSL-interface.

</P>
<PRE> BIO *internal_bio, *network_bio;
 ...
 BIO_new_bio_pair(internal_bio, 0, network_bio, 0);
 SSL_set_bio(ssl, internal_bio, internal_bio);
 SSL_operations();
 ...
</PRE>
<PRE> application |   TLS-engine
    |        |
    +----------&gt; SSL_operations()
             |     /\    ||
             |     ||    \/
             |   BIO-pair (internal_bio)
    +----------&lt; BIO-pair (network_bio)
    |        |
  socket     |
</PRE>
<PRE>  ...
  SSL_free(ssl);                /* implicitly frees internal_bio */
  BIO_free(network_bio);
  ...
</PRE>
<P>
As the BIO pair will only buffer the data and never directly access the
connection, it behaves non-blocking and will return as soon as the write
buffer is full or the read buffer is drained. Then the application has to
flush the write buffer and/or fill the read buffer.

</P>
<P>
Use the <CODE>BIO_ctrl_pending(),</CODE> to find out whether data is
buffered in the BIO and must be transfered to the network. Use
<CODE>BIO_ctrl_get_read_request()</CODE> to find out, how many bytes must
be written into the buffer before the <CODE>SSL_operation()</CODE> can
successfully be continued.

</P>
<P>
<HR>
<H1><A NAME="WARNING">WARNING</A></H1>
<P>
As the data is buffered, <CODE>SSL_operation()</CODE> may return with a
ERROR_SSL_WANT_READ condition, but there is still data in the write buffer.
An application must not rely on the error value of
<CODE>SSL_operation()</CODE> but must assure that the write buffer is
always flushed first. Otherwise a deadlock may occur as the peer might be
waiting for the data before being able to continue.

</P>
<P>
<HR>
<H1><A NAME="RETURN_VALUES">RETURN VALUES</A></H1>
<P>
The following return values can occur:

</P>
<DL>
<DT><STRONG><A NAME="item_1">1</A></STRONG><DD>
<P>
The BIO pair was created successfully. The new BIOs are available in
<STRONG>bio1</STRONG> and <STRONG>bio2</STRONG>.

</P>
<DT><STRONG><A NAME="item_0">0</A></STRONG><DD>
<P>
The operation failed. The NULL pointer is stored into the locations for
<STRONG>bio1</STRONG> and <STRONG>bio2</STRONG>. Check the error stack for more information.

</P>
</DL>
<P>
<HR>
<H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
<P>
<A HREF="../ssl/SSL_set_bio.html#">SSL_set_bio(3)</A>, <A HREF="../ssl/ssl.html#">ssl(3)</A>, <A HREF="../crypto/bio.html#">bio(3)</A>,
<A HREF="../crypto/BIO_ctrl.html#">BIO_ctrl_pending(3)</A>,
<A HREF="../crypto/BIO_s_bio.html#">BIO_ctrl_get_read_request(3)</A>



</P>
:}