Make the ASYNC code default libctx aware

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

diff --git a/doc/man3/BIO_s_bio.pod b/doc/man3/BIO_s_bio.pod
index cb46546e2139fc4bafc5ea1f9313b1b948e63da5..0f4ea77d6db3b7a33102ac8ac0823f309722679a 100644 (file)
--- a/doc/man3/BIO_s_bio.pod
+++ b/doc/man3/BIO_s_bio.pod
@@ -17,7 +17,6 @@ BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO
  int BIO_destroy_bio_pair(BIO *b);
  int BIO_shutdown_wr(BIO *b);
 
-
  int BIO_set_write_buf_size(BIO *b, long size);
  size_t BIO_get_write_buf_size(BIO *b, long size);
 
@@ -44,10 +43,10 @@ One typical use of BIO pairs is to place TLS/SSL I/O under application control,
 can be used when the application wishes to use a non standard transport for
 TLS/SSL or the normal socket routines are inappropriate.
 
-Calls to BIO_read() will read data from the buffer or request a retry if no
+Calls to BIO_read_ex() will read data from the buffer or request a retry if no
 data is available.
 
-Calls to BIO_write() will place data in the buffer or request a retry if the
+Calls to BIO_write_ex() will place data in the buffer or request a retry if the
 buffer is full.
 
 The standard calls BIO_ctrl_pending() and BIO_ctrl_wpending() can be used to
@@ -80,9 +79,9 @@ 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
-value will return a value from BIO_write() less than the amount requested or if the
-buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a function
-whereas BIO_get_write_guarantee() is a macro.
+value will return a value from BIO_write_ex() less than the amount requested or
+if the buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a
+function whereas BIO_get_write_guarantee() is a macro.
 
 BIO_get_read_request() and BIO_ctrl_get_read_request() return the
 amount of data requested, or the buffer size if it is less, if the
@@ -111,12 +110,12 @@ it to the underlying transport. This must be done before any normal processing
 (such as calling select() ) due to a request and BIO_should_read() being true.
 
 To see why this is important consider a case where a request is sent using
-BIO_write() and a response read with BIO_read(), this can occur during an
-TLS/SSL handshake for example. BIO_write() will succeed and place data in the write
-buffer. BIO_read() will initially fail and BIO_should_read() will be true. If
-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!
+BIO_write_ex() and a response read with BIO_read_ex(), this can occur during an
+TLS/SSL handshake for example. BIO_write_ex() will succeed and place data in the
+write buffer. BIO_read_ex() will initially fail and BIO_should_read() will be
+true. If 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!
 
 BIO_eof() is true if no data is in the peer BIO and the peer BIO has been
 shutdown.
@@ -134,17 +133,18 @@ 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
+=head1 EXAMPLES
 
 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(); //e.g SSL_read and SSL_write
+ SSL_operations(); /* e.g SSL_read and SSL_write */
  ...
 
  application |   TLS-engine
@@ -176,7 +176,7 @@ and must be transferred 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
+=head1 WARNINGS
 
 As the data is buffered, SSL_operation() may return with an ERROR_SSL_WANT_READ
 condition, but there is still data in the write buffer. An application must
@@ -186,14 +186,14 @@ the peer might be waiting for the data before being able to continue.
 
 =head1 SEE ALSO
 
-L<SSL_set_bio(3)>, L<ssl(3)>, L<bio(3)>,
-L<BIO_should_retry(3)>, L<BIO_read(3)>
+L<SSL_set_bio(3)>, L<ssl(7)>, L<bio(7)>,
+L<BIO_should_retry(3)>, L<BIO_read_ex(3)>
 
 =head1 COPYRIGHT
 
 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.