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.  If, by then, the underlying B<BIO> has data
  52 available for reading (if the result code is B<SSL_ERROR_WANT_READ>)
  53 or allows writing data (B<SSL_ERROR_WANT_WRITE>), then some TLS/SSL
  54 protocol progress will take place, i.e. at least part of an TLS/SSL
  55 record will be read or written.  Note that the retry may again lead to
  56 a B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE> condition.
  57 There is no fixed upper limit for the number of iterations that
  58 may be necessary until progress becomes visible at application
  59 protocol level.
  60
  61 For socket B<BIO>s (e.g. when SSL_set_fd() was used), select() or
  62 poll() on the underlying socket can be used to find out when the
  63 TLS/SSL I/O function should be retried.
  64
  65 Caveat: Any TLS/SSL I/O function can lead to either of
  66 B<SSL_ERROR_WANT_READ> and B<SSL_ERROR_WANT_WRITE>.  In particular,
  67 SSL_read() may want to write data and SSL_write() may want to read
  68 data.  This is because TLS/SSL handshakes may occur at any time
  69 during the protocol (initiated by either the client or the server);
  70 SSL_read() and SSL_write() will handle any pending handshakes.
  71
  72 =item SSL_ERROR_WANT_X509_LOOKUP
  73
  74 The operation did not complete because an application callback set by
  75 SSL_CTX_set_client_cert_cb() has asked to be called again.
  76 The TLS/SSL I/O function should be called again later.
  77 Details depend on the application.
  78
  79 =item SSL_ERROR_SYSCALL
  80
  81 Some I/O error occurred.  The OpenSSL error queue may contain more
  82 information on the error.  If the error queue is empty
  83 (i.e. ERR_get_error() returns 0), B<ret> can be used to find out more
  84 about the error: If B<ret == 0>, an EOF was observed that violates
  85 the protocol.  If B<ret == -1>, the underlying B<BIO> reported an
  86 I/O error (for socket I/O on Unix systems, consult B<errno> for details).
  87
  88 =item SSL_ERROR_SSL
  89
  90 A failure in the SSL library occurred, usually a protocol error.  The
  91 OpenSSL error queue contains more information on the error.
  92
  93 =back
  94
  95 =head1 SEE ALSO
  96
  97 L<ssl(3)|ssl(3)>, L<err(3)|err(3)>
  98
  99 =head1 HISTORY
 100
 101 SSL_get_error() was added in SSLeay 0.8.
 102
 103 =cut