doc/ssl/SSL_get_error.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_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
  15 SSL_get_error() returns a result code (suitable for the C "switch"
  16 statement) for a preceding call to SSL_connect(), SSL_accept(),
  17 SSL_read(), or SSL_write() on B<ssl>.  The value returned by that
  18 TLS/SSL I/O function must be passed to SSL_get_error() in parameter
  19 B<ret>.
  20
  21 In addition to B<ssl> and B<ret>, SSL_get_error() inspects the
  22 current thread's OpenSSL error queue.  Thus, SSL_get_error() must be
  23 used in the same thread that performed the TLS/SSL I/O operation, and no
  24 other OpenSSL function calls should appear in between.  The current
  25 thread's error queue must be empty before the TLS/SSL I/O operation is
  26 attempted, or SSL_get_error() will not work reliably.
  27
  28 =head1 RETURN VALUES
  29
  30 The following return values can currently occur:
  31
  32 =over 4
  33
  34 =item SSL_ERROR_NONE
  35
  36 The TLS/SSL I/O operation completed.  This result code is returned
  37 if and only if B<ret E<gt> 0>.
  38
  39 =item SSL_ERROR_ZERO_RETURN
  40
  41 The TLS/SSL connection has been closed.  If the protocol version is SSL 3.0
  42 or TLS 1.0, this result code is returned only if a closure
  43 alert has occurred in the protocol, i.e. if the connection has been
  44 closed cleanly. Note that in this case B<SSL_ERROR_ZERO_RETURN>
  45 does not necessarily indicate that the underlying transport
  46 has been closed.
  47
  48 =item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE
  49
  50 The operation did not complete; the same TLS/SSL I/O function should be
  51 called again later.  There will be protocol progress if, by then, the
  52 underlying B<BIO> has data available for reading (if the result code is
  53 B<SSL_ERROR_WANT_READ>) or allows writing data (B<SSL_ERROR_WANT_WRITE>).
  54 For socket B<BIO>s (e.g. when SSL_set_fd() was used) this means that
  55 select() or poll() on the underlying socket can be used to find out
  56 when the TLS/SSL I/O function should be retried.
  57
  58 Caveat: Any TLS/SSL I/O function can lead to either of
  59 B<SSL_ERROR_WANT_READ> and B<SSL_ERROR_WANT_WRITE>, i.e. SSL_read()
  60 may want to write data and SSL_write() may want to read data.
  61
  62 =item SSL_ERROR_WANT_X509_LOOKUP
  63
  64 The operation did not complete because an application callback set by
  65 SSL_CTX_set_client_cert_cb() has asked to be called again.
  66 The TLS/SSL I/O function should be called again later.
  67 Details depend on the application.
  68
  69 =item SSL_ERROR_SYSCALL
  70
  71 Some I/O error occurred.  The OpenSSL error queue may contain more
  72 information on the error.  If the error queue is empty
  73 (i.e. ERR_get_error() returns 0), B<ret> can be used to find out more
  74 about the error: If B<ret == 0>, an EOF was observed that violates
  75 the protocol.  If B<ret == -1>, the underlying B<BIO> reported an
  76 I/O error (for socket I/O on Unix systems, consult B<errno> for details).
  77
  78 =item SSL_ERROR_SSL
  79
  80 A failure in the SSL library occurred, usually a protocol error.  The
  81 OpenSSL error queue contains more information on the error.
  82
  83 =back
  84
  85 =head1 SEE ALSO
  86
  87 L<ssl(3)|ssl(3)>, L<err(3)|err(3)>
  88
  89 =head1 HISTORY
  90
  91 SSL_get_error() was added in SSLeay 0.8.
  92
  93 =cut