SSL_get_error.pod revision 68651
1275970Scy=pod 2275970Scy 3275970Scy=head1 NAME 4275970Scy 5275970ScySSL_get_error - obtain result code for TLS/SSL I/O operation 6275970Scy 7275970Scy=head1 SYNOPSIS 8275970Scy 9275970Scy #include <openssl/ssl.h> 10275970Scy 11275970Scy int SSL_get_error(SSL *ssl, int ret); 12275970Scy 13275970Scy=head1 DESCRIPTION 14275970Scy 15275970ScySSL_get_error() returns a result code (suitable for the C "switch" 16275970Scystatement) for a preceding call to SSL_connect(), SSL_accept(), 17275970ScySSL_read(), or SSL_write() on B<ssl>. The value returned by that 18275970ScyTLS/SSL I/O function must be passed to SSL_get_error() in parameter 19275970ScyB<ret>. 20275970Scy 21275970ScyIn addition to B<ssl> and B<ret>, SSL_get_error() inspects the 22275970Scycurrent thread's OpenSSL error queue. Thus, SSL_get_error() must be 23275970Scyused in the same thread that performed the TLS/SSL I/O operation, and no 24275970Scyother OpenSSL function calls should appear in between. The current 25275970Scythread's error queue must be empty before the TLS/SSL I/O operation is 26275970Scyattempted, or SSL_get_error() will not work reliably. 27275970Scy 28275970Scy=head1 RETURN VALUES 29275970Scy 30275970ScyThe following return values can currently occur: 31275970Scy 32275970Scy=over 4 33275970Scy 34275970Scy=item SSL_ERROR_NONE 35275970Scy 36275970ScyThe TLS/SSL I/O operation completed. This result code is returned 37275970Scyif and only if B<ret E<gt> 0>. 38275970Scy 39275970Scy=item SSL_ERROR_ZERO_RETURN 40275970Scy 41275970ScyThe TLS/SSL connection has been closed. If the protocol version is SSL 3.0 42275970Scyor TLS 1.0, this result code is returned only if a closure 43275970Scyalert has occurred in the protocol, i.e. if the connection has been 44275970Scyclosed cleanly. Note that in this case B<SSL_ERROR_ZERO_RETURN> 45275970Scydoes not necessarily indicate that the underlying transport 46275970Scyhas been closed. 47275970Scy 48275970Scy=item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE 49275970Scy 50275970ScyThe operation did not complete; the same TLS/SSL I/O function should be 51275970Scycalled again later. There will be protocol progress if, by then, the 52275970Scyunderlying B<BIO> has data available for reading (if the result code is 53275970ScyB<SSL_ERROR_WANT_READ>) or allows writing data (B<SSL_ERROR_WANT_WRITE>). 54275970ScyFor socket B<BIO>s (e.g. when SSL_set_fd() was used) this means that 55275970Scyselect() or poll() on the underlying socket can be used to find out 56275970Scywhen the TLS/SSL I/O function should be retried. 57275970Scy 58275970ScyCaveat: Any TLS/SSL I/O function can lead to either of 59275970ScyB<SSL_ERROR_WANT_READ> and B<SSL_ERROR_WANT_WRITE>, i.e. SSL_read() 60275970Scymay want to write data and SSL_write() may want to read data. 61275970Scy 62275970Scy=item SSL_ERROR_WANT_X509_LOOKUP 63275970Scy 64275970ScyThe operation did not complete because an application callback set by 65275970ScySSL_CTX_set_client_cert_cb() has asked to be called again. 66275970ScyThe TLS/SSL I/O function should be called again later. 67275970ScyDetails depend on the application. 68275970Scy 69275970Scy=item SSL_ERROR_SYSCALL 70275970Scy 71275970ScySome I/O error occurred. The OpenSSL error queue may contain more 72275970Scyinformation on the error. If the error queue is empty 73275970Scy(i.e. ERR_get_error() returns 0), B<ret> can be used to find out more 74275970Scyabout the error: If B<ret == 0>, an EOF was observed that violates 75275970Scythe protocol. If B<ret == -1>, the underlying B<BIO> reported an 76275970ScyI/O error (for socket I/O on Unix systems, consult B<errno> for details). 77275970Scy 78275970Scy=item SSL_ERROR_SSL 79275970Scy 80275970ScyA failure in the SSL library occurred, usually a protocol error. The 81275970ScyOpenSSL error queue contains more information on the error. 82275970Scy 83275970Scy=back 84275970Scy 85275970Scy=head1 SEE ALSO 86275970Scy 87275970ScyL<ssl(3)|ssl(3)>, L<err(3)|err(3)> 88275970Scy 89275970Scy=head1 HISTORY 90275970Scy 91275970ScySSL_get_error() was added in SSLeay 0.8. 92275970Scy 93275970Scy=cut 94275970Scy