diff options
Diffstat (limited to 'deps/openssl/openssl/doc/ssl/SSL_read.pod')
| -rw-r--r-- | deps/openssl/openssl/doc/ssl/SSL_read.pod | 51 |
1 files changed, 26 insertions, 25 deletions
diff --git a/deps/openssl/openssl/doc/ssl/SSL_read.pod b/deps/openssl/openssl/doc/ssl/SSL_read.pod index ef983c9d3f..20ccf40dfd 100644 --- a/deps/openssl/openssl/doc/ssl/SSL_read.pod +++ b/deps/openssl/openssl/doc/ssl/SSL_read.pod @@ -2,7 +2,7 @@ =head1 NAME -SSL_read - read bytes from a TLS/SSL connection. +SSL_read - read bytes from a TLS/SSL connection =head1 SYNOPSIS @@ -18,16 +18,16 @@ buffer B<buf>. =head1 NOTES If necessary, SSL_read() will negotiate a TLS/SSL session, if -not already explicitly performed by L<SSL_connect(3)|SSL_connect(3)> or -L<SSL_accept(3)|SSL_accept(3)>. If the +not already explicitly performed by L<SSL_connect(3)> or +L<SSL_accept(3)>. If the peer requests a re-negotiation, it will be performed transparently during the SSL_read() operation. The behaviour of SSL_read() depends on the -underlying BIO. +underlying BIO. For the transparent negotiation to succeed, the B<ssl> must have been initialized to client or server mode. This is being done by calling -L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or SSL_set_accept_state() -before the first call to an SSL_read() or L<SSL_write(3)|SSL_write(3)> +L<SSL_set_connect_state(3)> or SSL_set_accept_state() +before the first call to an SSL_read() or L<SSL_write(3)> function. SSL_read() works based on the SSL/TLS records. The data are received in @@ -47,14 +47,14 @@ record is complete and SSL_read() can succeed. If the underlying BIO is B<blocking>, SSL_read() will only return, once the read operation has been finished or an error occurred, except when a -renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur. +renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur. This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the -L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> call. +L<SSL_CTX_set_mode(3)> call. If the underlying BIO is B<non-blocking>, SSL_read() will also return when the underlying BIO could not satisfy the needs of SSL_read() to continue the operation. In this case a call to -L<SSL_get_error(3)|SSL_get_error(3)> with the +L<SSL_get_error(3)> with the return value of SSL_read() will yield B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a call to SSL_read() can also cause write operations! The calling process @@ -64,7 +64,7 @@ non-blocking socket, nothing is to be done, but select() can be used to check for the required condition. When using a buffering BIO, like a BIO pair, data must be written into or retrieved out of the BIO before being able to continue. -L<SSL_pending(3)|SSL_pending(3)> can be used to find out whether there +L<SSL_pending(3)> can be used to find out whether there are buffered bytes available for immediate retrieval. In this case SSL_read() can be called without blocking or actually receiving new data from the underlying socket. @@ -89,18 +89,10 @@ connection. =item Z<><= 0 - -=item E<lt>0 - The read operation was not successful, because either the connection was closed, an error occurred or action must be taken by the calling process. Call L<SSL_get_error(3)> with the return value B<ret> to find out the reason. -SSLv2 (deprecated) does not support a shutdown alert protocol, so it can -only be detected, whether the underlying connection was closed. It cannot -be checked, whether the closure was initiated by the peer or by something -else. - Old documentation indicated a difference between 0 and -1, and that -1 was retryable. You should instead call SSL_get_error() to find out if it's retryable. @@ -109,12 +101,21 @@ You should instead call SSL_get_error() to find out if it's retryable. =head1 SEE ALSO -L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_write(3)|SSL_write(3)>, -L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>, -L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)> -L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, -L<SSL_pending(3)|SSL_pending(3)>, -L<SSL_shutdown(3)|SSL_shutdown(3)>, L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>, -L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> +L<SSL_get_error(3)>, L<SSL_write(3)>, +L<SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)>, +L<SSL_connect(3)>, L<SSL_accept(3)> +L<SSL_set_connect_state(3)>, +L<SSL_pending(3)>, +L<SSL_shutdown(3)>, L<SSL_set_shutdown(3)>, +L<ssl(3)>, L<bio(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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>. =cut |