Add SSL_CTX early callback
[openssl.git] / doc / man3 / SSL_get_error.pod
index ddd72f7..e318de8 100644 (file)
@@ -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(), SSL_peek(), 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_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
@@ -38,12 +38,12 @@ if and only if B<ret E<gt> 0>.
 
 =item SSL_ERROR_ZERO_RETURN
 
-The TLS/SSL connection has been closed.  If the protocol version is SSL 3.0
-or TLS 1.0, this result code is returned only if a closure
-alert has occurred in the protocol, i.e. if the connection has been
-closed cleanly. Note that in this case B<SSL_ERROR_ZERO_RETURN>
-does not necessarily indicate that the underlying transport
-has been closed.
+The TLS/SSL connection has been closed.
+If the protocol version is SSL 3.0 or higher, this result code is returned only
+if a closure alert has occurred in the protocol, i.e. if the connection has been
+closed cleanly.
+Note that in this case B<SSL_ERROR_ZERO_RETURN> does not necessarily
+indicate that the underlying transport has been closed.
 
 =item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE
 
@@ -64,10 +64,11 @@ TLS/SSL I/O function should be retried.
 
 Caveat: Any TLS/SSL I/O function can lead to either of
 B<SSL_ERROR_WANT_READ> and B<SSL_ERROR_WANT_WRITE>.  In particular,
-SSL_read() or SSL_peek() may want to write data and SSL_write() may want
-to read data.  This is mainly because TLS/SSL handshakes may occur at any
-time during the protocol (initiated by either the client or the server);
-SSL_read(), SSL_peek(), and SSL_write() will handle any pending handshakes.
+SSL_read_ex(), SSL_read(), SSL_peek_ex(), or SSL_peek() may want to write data
+and SSL_write() or SSL_write_ex() may want to read data.  This is mainly because
+TLS/SSL handshakes may occur at any time during the protocol (initiated by
+either the client or the server); SSL_read_ex(), SSL_read(), SSL_peek_ex(),
+SSL_peek(), SSL_write_ex(), and SSL_write() will handle any pending handshakes.
 
 =item SSL_ERROR_WANT_CONNECT, SSL_ERROR_WANT_ACCEPT
 
@@ -109,14 +110,18 @@ through a call to L<ASYNC_init_thread(3)>. The application should retry the
 operation after a currently executing asynchronous operation for the current
 thread has completed.
 
+=item SSL_ERROR_WANT_EARLY
+
+The operation did not complete because an application callback set by
+SSL_CTX_set_early_cb() has asked to be called again.
+The TLS/SSL I/O function should be called again later.
+Details depend on the application.
+
 =item SSL_ERROR_SYSCALL
 
-Some I/O error occurred.  The OpenSSL error queue may contain more
-information on the error.  If the error queue is empty
-(i.e. ERR_get_error() returns 0), B<ret> can be used to find out more
-about the error: If B<ret == 0>, an EOF was observed that violates
-the protocol.  If B<ret == -1>, the underlying B<BIO> reported an
-I/O error (for socket I/O on Unix systems, consult B<errno> for details).
+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.
 
 =item SSL_ERROR_SSL
 
@@ -127,15 +132,16 @@ OpenSSL error queue contains more information on the error.
 
 =head1 SEE ALSO
 
-L<ssl(3)>, L<err(3)>
+L<ssl(7)>, L<err(7)>
 
 =head1 HISTORY
 
 SSL_ERROR_WANT_ASYNC was added in OpenSSL 1.1.0.
+SSL_ERROR_WANT_EARLY was added in OpenSSL 1.1.1.
 
 =head1 COPYRIGHT
 
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2017 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