doc/ssl/SSL_get_error.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_get_error - obtain result code for 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 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 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 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 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 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.
  45
  46 =item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE
  47
  48 The operation did not complete; the same SSL I/O function should be
  49 called again later.  There will be protocol progress if, by then, the
  50 underlying B<BIO> has data available for reading (if the result code is
  51 B<SSL_ERROR_WANT_READ>) or allows writing data (B<SSL_ERROR_WANT_WRITE>).
  52 For socket B<BIO>s (e.g. when SSL_set_fd() was used) this means that
  53 select() or poll() on the underlying socket can be used to find out
  54 when the SSL I/O function should be retried.
  55
  56 Caveat: Any SSL I/O function can lead to either of
  57 B<SSL_ERROR_WANT_READ> and B<SSL_ERROR_WANT_WRITE>, i.e. SSL_read()
  58 may want to write data and SSL_write() may want to read data.
  59
  60 =item SSL_ERROR_WANT_X509_LOOKUP
  61
  62 The operation did not complete because an application callback set by
  63 SSL_CTX_set_client_cert_cb() has asked to be called again.
  64 The SSL I/O function should be called again later.
  65 Details depend on the application.
  66
  67 =item SSL_ERROR_SYSCALL
  68
  69 Some I/O error occurred.  The OpenSSL error queue may contain more
  70 information on the error.  If the error queue is empty
  71 (i.e. ERR_get_error() returns 0), B<ret> can be used to find out more
  72 about the error: If B<ret == 0>, an EOF was observed that violates
  73 the protocol.  If B<ret == -1>, the underlying B<BIO> reported an
  74 I/O error (for socket I/O on Unix systems, consult B<errno> for details).
  75
  76 =item SSL_ERROR_SSL
  77
  78 A failure in the SSL library occurred, usually a protocol error.  The
  79 OpenSSL error queue contains more information on the error.
  80
  81 =back
  82
  83 =head1 SEE ALSO
  84
  85 L<ssl(3)|ssl(3)>, L<err(3)|err(3)>
  86
  87 =head1 HISTORY
  88
  89 SSL_get_error() was added in SSLeay 0.8.
  90
  91 =cut