SSL_get_error.pod revision 79998
1=pod 2 3=head1 NAME 4 5SSL_get_error - obtain result code for TLS/SSL I/O operation 6 7=head1 SYNOPSIS 8 9 #include <openssl/ssl.h> 10 11 int SSL_get_error(SSL *ssl, int ret); 12 13=head1 DESCRIPTION 14 15SSL_get_error() returns a result code (suitable for the C "switch" 16statement) for a preceding call to SSL_connect(), SSL_accept(), 17SSL_read(), SSL_peek(), or SSL_write() on B<ssl>. The value returned by 18that TLS/SSL I/O function must be passed to SSL_get_error() in parameter 19B<ret>. 20 21In addition to B<ssl> and B<ret>, SSL_get_error() inspects the 22current thread's OpenSSL error queue. Thus, SSL_get_error() must be 23used in the same thread that performed the TLS/SSL I/O operation, and no 24other OpenSSL function calls should appear in between. The current 25thread's error queue must be empty before the TLS/SSL I/O operation is 26attempted, or SSL_get_error() will not work reliably. 27 28=head1 RETURN VALUES 29 30The following return values can currently occur: 31 32=over 4 33 34=item SSL_ERROR_NONE 35 36The TLS/SSL I/O operation completed. This result code is returned 37if and only if B<ret E<gt> 0>. 38 39=item SSL_ERROR_ZERO_RETURN 40 41The TLS/SSL connection has been closed. If the protocol version is SSL 3.0 42or TLS 1.0, this result code is returned only if a closure 43alert has occurred in the protocol, i.e. if the connection has been 44closed cleanly. Note that in this case B<SSL_ERROR_ZERO_RETURN> 45does not necessarily indicate that the underlying transport 46has been closed. 47 48=item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE 49 50The operation did not complete; the same TLS/SSL I/O function should be 51called again later. If, by then, the underlying B<BIO> has data 52available for reading (if the result code is B<SSL_ERROR_WANT_READ>) 53or allows writing data (B<SSL_ERROR_WANT_WRITE>), then some TLS/SSL 54protocol progress will take place, i.e. at least part of an TLS/SSL 55record will be read or written. Note that the retry may again lead to 56a B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE> condition. 57There is no fixed upper limit for the number of iterations that 58may be necessary until progress becomes visible at application 59protocol level. 60 61For socket B<BIO>s (e.g. when SSL_set_fd() was used), select() or 62poll() on the underlying socket can be used to find out when the 63TLS/SSL I/O function should be retried. 64 65Caveat: Any TLS/SSL I/O function can lead to either of 66B<SSL_ERROR_WANT_READ> and B<SSL_ERROR_WANT_WRITE>. In particular, 67SSL_read() or SSL_peek() may want to write data and SSL_write() may want 68to read data. This is mainly because TLS/SSL handshakes may occur at any 69time during the protocol (initiated by either the client or the server); 70SSL_read(), SSL_peek(), and SSL_write() will handle any pending handshakes. 71 72=item SSL_ERROR_WANT_CONNECT 73 74The operation did not complete; the same TLS/SSL I/O function should be 75called again later. The underlying BIO was not connected yet to the peer 76and the call would block in connect(). The SSL function should be 77called again when the connection is established. This messages can only 78appear with a BIO_s_connect() BIO. 79In order to find out, when the connection has been successfully established, 80on many platforms select() or poll() for writing on the socket file descriptor 81can be used. 82 83=item SSL_ERROR_WANT_X509_LOOKUP 84 85The operation did not complete because an application callback set by 86SSL_CTX_set_client_cert_cb() has asked to be called again. 87The TLS/SSL I/O function should be called again later. 88Details depend on the application. 89 90=item SSL_ERROR_SYSCALL 91 92Some I/O error occurred. The OpenSSL error queue may contain more 93information on the error. If the error queue is empty 94(i.e. ERR_get_error() returns 0), B<ret> can be used to find out more 95about the error: If B<ret == 0>, an EOF was observed that violates 96the protocol. If B<ret == -1>, the underlying B<BIO> reported an 97I/O error (for socket I/O on Unix systems, consult B<errno> for details). 98 99=item SSL_ERROR_SSL 100 101A failure in the SSL library occurred, usually a protocol error. The 102OpenSSL error queue contains more information on the error. 103 104=back 105 106=head1 SEE ALSO 107 108L<ssl(3)|ssl(3)>, L<err(3)|err(3)> 109 110=head1 HISTORY 111 112SSL_get_error() was added in SSLeay 0.8. 113 114=cut 115