Improve BIO_socket_wait(), BIO_wait(), BIO_connect_retry(), and their docs

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

diff --git a/doc/man3/SSL_get_error.pod b/doc/man3/SSL_get_error.pod
index 01446a24a1e1cd40d9e17de9d6dd6df60faf58b9..07466731ebb34e707e48e1972886151fa5b09e9b 100644 (file)
--- a/doc/man3/SSL_get_error.pod
+++ b/doc/man3/SSL_get_error.pod
@@ -14,9 +14,9 @@ SSL_get_error - obtain result code for TLS/SSL I/O operation
 
 SSL_get_error() returns a result code (suitable for the C "switch"
 statement) for a preceding call to SSL_connect(), SSL_accept(), SSL_do_handshake(),
-SSL_read_ex(), SSL_read(), SSL_peek_ex(), SSL_peek(), SSL_write_ex() or
-SSL_write() on B<ssl>.  The value returned by that TLS/SSL I/O function must be
-passed to SSL_get_error() in parameter B<ret>.
+SSL_read_ex(), SSL_read(), SSL_peek_ex(), SSL_peek(), SSL_shutdown(),
+SSL_write_ex() or SSL_write() on B<ssl>.  The value returned by that TLS/SSL I/O
+function must be passed to SSL_get_error() in parameter B<ret>.
 
 In addition to B<ssl> and B<ret>, SSL_get_error() inspects the
 current thread's OpenSSL error queue.  Thus, SSL_get_error() must be
@@ -25,6 +25,15 @@ other OpenSSL function calls should appear in between.  The current
 thread's error queue must be empty before the TLS/SSL I/O operation is
 attempted, or SSL_get_error() will not work reliably.
 
+=head1 NOTES
+
+Some TLS implementations do not send a close_notify alert on shutdown.
+
+On an unexpected EOF, versions before OpenSSL 3.0 returned
+B<SSL_ERROR_SYSCALL>, nothing was added to the error stack, and errno was 0.
+Since OpenSSL 3.0 the returned error is B<SSL_ERROR_SSL> with a meaningful
+error on the error stack.
+
 =head1 RETURN VALUES
 
 The following return values can currently occur:
@@ -39,11 +48,14 @@ if and only if B<ret E<gt> 0>.
 =item SSL_ERROR_ZERO_RETURN
 
 The TLS/SSL peer has closed the connection for writing by sending the
-"close notify" alert.
+close_notify alert.
 No more data can be read.
 Note that B<SSL_ERROR_ZERO_RETURN> does not necessarily
 indicate that the underlying transport has been closed.
 
+This error can also appear when the option B<SSL_OP_IGNORE_UNEXPECTED_EOF>
+is set. See L<SSL_CTX_set_options(3)> for more details.
+
 =item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE
 
 The operation did not complete and can be retried later.
@@ -138,17 +150,20 @@ Details depend on the application.
 
 =item SSL_ERROR_SYSCALL
 
-Some non-recoverable I/O error occurred.
-The OpenSSL error queue may contain more information on the error.
-For socket I/O on Unix systems, consult B<errno> for details.
+Some non-recoverable, fatal I/O error occurred. The OpenSSL error queue may
+contain more information on the error. For socket I/O on Unix systems, consult
+B<errno> for details. If this error occurs then no further I/O operations should
+be performed on the connection and SSL_shutdown() must not be called.
 
 This value can also be returned for other errors, check the error queue for
 details.
 
 =item SSL_ERROR_SSL
 
-A failure in the SSL library occurred, usually a protocol error.  The
-OpenSSL error queue contains more information on the error.
+A non-recoverable, fatal error in the SSL library occurred, usually a protocol
+error.  The OpenSSL error queue contains more information on the error. If this
+error occurs then no further I/O operations should be performed on the
+connection and SSL_shutdown() must not be called.
 
 =back
 
@@ -158,14 +173,14 @@ L<ssl(7)>
 
 =head1 HISTORY
 
-SSL_ERROR_WANT_ASYNC was added in OpenSSL 1.1.0.
-SSL_ERROR_WANT_CLIENT_HELLO_CB was added in OpenSSL 1.1.1.
+The SSL_ERROR_WANT_ASYNC error code was added in OpenSSL 1.1.0.
+The SSL_ERROR_WANT_CLIENT_HELLO_CB error code was added in OpenSSL 1.1.1.
 
 =head1 COPYRIGHT
 
-Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2020 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>.