Provide documentation for i2d_ECPrivateKey and d2i_ECPrivateKey

[openssl.git] / doc / crypto / BIO_s_bio.pod

diff --git a/doc/crypto/BIO_s_bio.pod b/doc/crypto/BIO_s_bio.pod
index 95ae802e4724cd51cc0853108482c2194c61be8e..8d0a55a025c73f49a49d5d29afec0f43056b2793 100644 (file)
--- a/doc/crypto/BIO_s_bio.pod
+++ b/doc/crypto/BIO_s_bio.pod
@@ -76,7 +76,9 @@ BIO_get_write_buf_size() returns the size of the write buffer.
 BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and
 BIO_set_write_buf_size() to create a connected pair of BIOs B<bio1>, B<bio2>
 with write buffer sizes B<writebuf1> and B<writebuf2>. If either size is
-zero then the default size is used.
+zero then the default size is used.  BIO_new_bio_pair() does not check whether
+B<bio1> or B<bio2> do point to some other BIO, the values are overwritten,
+BIO_free() is not called.
 
 BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum
 length of data that can be currently written to the BIO. Writes larger than this
@@ -118,9 +120,59 @@ the application then waits for data to be available on the underlying transport
 before flushing the write buffer it will never succeed because the request was
 never sent!
 
+=head1 RETURN VALUES
+
+BIO_new_bio_pair() returns 1 on success, with the new BIOs available in
+B<bio1> and B<bio2>, or 0 on failure, with NULL pointers stored into the
+locations for B<bio1> and B<bio2>. Check the error stack for more information.
+
+[XXXXX: More return values need to be added here]
+
 =head1 EXAMPLE
 
-TBA
+The BIO pair can be used to have full control over the network access of an
+application. The application can call select() on the socket as required
+without having to go through the SSL-interface.
+
+ 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();
+ ...
+
+ application |   TLS-engine
+    |        |
+    +----------> SSL_operations()
+             |     /\    ||
+             |     ||    \/
+             |   BIO-pair (internal_bio)
+    +----------< BIO-pair (network_bio)
+    |        |
+  socket     |
+
+  ...
+  SSL_free(ssl);               /* implicitly frees internal_bio */
+  BIO_free(network_bio);
+  ...
+
+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.
+
+Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO
+and must be transfered to the network. Use BIO_ctrl_get_read_request() to
+find out, how many bytes must be written into the buffer before the
+SSL_operation() can successfully be continued.
+
+=head1 WARNING
+
+As the data is buffered, SSL_operation() 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 SSL_operation() 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.
 
 =head1 SEE ALSO