New documentation about things related to SSL_CIPHER. Submitted by Lutz Jaenicke...

[openssl.git] / doc / ssl / SSL_get_error.pod

diff --git a/doc/ssl/SSL_get_error.pod b/doc/ssl/SSL_get_error.pod
index d7e2a81a88e6af56582996c2feb70eda850c3687..d85b564258282011faa591f77f55f9daf5117189 100644 (file)
--- a/doc/ssl/SSL_get_error.pod
+++ b/doc/ssl/SSL_get_error.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
 
 =head1 NAME
 

-SSL_get_error - obtain result code for SSL I/O operation
+SSL_get_error - obtain result code for TLS/SSL I/O operation

 
 =head1 SYNOPSIS
 
 
 =head1 SYNOPSIS
 


@@ -15,14 +15,14 @@ SSL_get_error - obtain result code for SSL I/O operation
 SSL_get_error() returns a result code (suitable for the C "switch"
 statement) for a preceding call to SSL_connect(), SSL_accept(),
 SSL_read(), or SSL_write() on B<ssl>.  The value returned by that
 SSL_get_error() returns a result code (suitable for the C "switch"
 statement) for a preceding call to SSL_connect(), SSL_accept(),
 SSL_read(), or SSL_write() on B<ssl>.  The value returned by that

-SSL I/O function must be passed to SSL_get_error() in parameter
+TLS/SSL I/O function must be passed to SSL_get_error() in parameter

 B<ret>.
 
 In addition to B<ssl> and B<ret>, SSL_get_error() inspects the
 current thread's OpenSSL error queue.  Thus, SSL_get_error() must be
 B<ret>.
 
 In addition to B<ssl> and B<ret>, SSL_get_error() inspects the
 current thread's OpenSSL error queue.  Thus, SSL_get_error() must be

-used in the same thread that performed the SSL I/O operation, and no
-other OpenSSL function calls should appear inbetween.  The current
-thread's error queue must be empty before the SSL I/O operation is
+used in the same thread that performed the TLS/SSL I/O operation, and no
+other OpenSSL function calls should appear in between.  The current
+thread's error queue must be empty before the TLS/SSL I/O operation is

 attempted, or SSL_get_error() will not work reliably.
 
 =head1 RETURN VALUES
 attempted, or SSL_get_error() will not work reliably.
 
 =head1 RETURN VALUES


@@ -33,27 +33,29 @@ The following return values can currently occur:
 
 =item SSL_ERROR_NONE
 
 
 =item SSL_ERROR_NONE
 

-The SSL I/O operation completed.  This result code is returned
-if and only if B<ret > 0>.
+The TLS/SSL I/O operation completed.  This result code is returned
+if and only if B<ret E<gt> 0>.

 
 =item SSL_ERROR_ZERO_RETURN
 
 
 =item SSL_ERROR_ZERO_RETURN
 

-The SSL connection has been closed.  If the protocol version is SSL 3.0
+The TLS/SSL connection has been closed.  If the protocol version is SSL 3.0

 or TLS 1.0, this result code is returned only if a closure
 or TLS 1.0, this result code is returned only if a closure

-alerts has occured in the protocol, i.e. if the connection has been
-closed cleanly.
+alert has occurred in the protocol, i.e. if the connection has been
+closed cleanly. Note that in this case B<SSL_ERROR_ZERO_RETURN>
+does not necessarily indicate that the underlying transport
+has been closed.

 
 =item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE
 
 
 =item SSL_ERROR_WANT_READ, SSL_ERROR_WANT_WRITE
 

-The operation did not complete; the same SSL I/O function should be
+The operation did not complete; the same TLS/SSL I/O function should be

 called again later.  There will be protocol progress if, by then, the
 underlying B<BIO> has data available for reading (if the result code is
 B<SSL_ERROR_WANT_READ>) or allows writing data (B<SSL_ERROR_WANT_WRITE>). 
 For socket B<BIO>s (e.g. when SSL_set_fd() was used) this means that
 select() or poll() on the underlying socket can be used to find out
 called again later.  There will be protocol progress if, by then, the
 underlying B<BIO> has data available for reading (if the result code is
 B<SSL_ERROR_WANT_READ>) or allows writing data (B<SSL_ERROR_WANT_WRITE>). 
 For socket B<BIO>s (e.g. when SSL_set_fd() was used) this means that
 select() or poll() on the underlying socket can be used to find out

-when the SSL I/O function should be retried.
+when the TLS/SSL I/O function should be retried.

 
 

-Caveat: Any SSL I/O function can lead to either of
+Caveat: Any TLS/SSL I/O function can lead to either of

 B<SSL_ERROR_WANT_READ> and B<SSL_ERROR_WANT_WRITE>, i.e. SSL_read()
 may want to write data and SSL_write() may want to read data.
 
 B<SSL_ERROR_WANT_READ> and B<SSL_ERROR_WANT_WRITE>, i.e. SSL_read()
 may want to write data and SSL_write() may want to read data.
 


@@ -61,7 +63,7 @@ may want to write data and SSL_write() may want to read data.
 
 The operation did not complete because an application callback set by
 SSL_CTX_set_client_cert_cb() has asked to be called again.
 
 The operation did not complete because an application callback set by
 SSL_CTX_set_client_cert_cb() has asked to be called again.

-The SSL I/O function should be called again later.
+The TLS/SSL I/O function should be called again later.

 Details depend on the application.
 
 =item SSL_ERROR_SYSCALL
 Details depend on the application.
 
 =item SSL_ERROR_SYSCALL


@@ -71,18 +73,18 @@ information on the error.  If the error queue is empty
 (i.e. ERR_get_error() returns 0), B<ret> can be used to find out more
 about the error: If B<ret == 0>, an EOF was observed that violates
 the protocol.  If B<ret == -1>, the underlying B<BIO> reported an
 (i.e. ERR_get_error() returns 0), B<ret> can be used to find out more
 about the error: If B<ret == 0>, an EOF was observed that violates
 the protocol.  If B<ret == -1>, the underlying B<BIO> reported an

-I/O error.  (For socket I/O on Unix systems, consult B<errno>.)
+I/O error (for socket I/O on Unix systems, consult B<errno> for details).

 
 =item SSL_ERROR_SSL
 
 
 =item SSL_ERROR_SSL
 

-A failure in the SSL library occured, usually a protocol error.  The
+A failure in the SSL library occurred, usually a protocol error.  The

 OpenSSL error queue contains more information on the error.
 
 =back
 
 =head1 SEE ALSO
 
 OpenSSL error queue contains more information on the error.
 
 =back
 
 =head1 SEE ALSO
 

-ssl(3), err(3)
+L<ssl(3)|ssl(3)>, L<err(3)|err(3)>

 
 =head1 HISTORY
 
 
 =head1 HISTORY