Make SSL_read and SSL_write return the old behaviour and document it.

[openssl.git] / doc / man3 / SSL_read.pod

diff --git a/doc/man3/SSL_read.pod b/doc/man3/SSL_read.pod
index e2490d4f47527206db6b779aed8b9e3ffc1a1155..215d4c52923ec749de3efd291c9c2df75376755d 100644 (file)
--- a/doc/man3/SSL_read.pod
+++ b/doc/man3/SSL_read.pod
@@ -9,17 +9,17 @@ SSL_read_ex, SSL_read, SSL_peek_ex, SSL_peek
 
  #include <openssl/ssl.h>
 
- int SSL_read_ex(SSL *ssl, void *buf, size_t num, size_t *read);
+ int SSL_read_ex(SSL *ssl, void *buf, size_t num, size_t *readbytes);
  int SSL_read(SSL *ssl, void *buf, int num);
 
- int SSL_peek_ex(SSL *ssl, void *buf, size_t num, size_t *read);
+ int SSL_peek_ex(SSL *ssl, void *buf, size_t num, size_t *readbytes);
  int SSL_peek(SSL *ssl, void *buf, int num);
 
 =head1 DESCRIPTION
 
 SSL_read_ex() and SSL_read() try to read B<num> bytes from the specified B<ssl>
 into the buffer B<buf>. On success SSL_read_ex() will store the number of bytes
-actually read in B<*read>.
+actually read in B<*readbytes>.
 
 SSL_peek_ex() and SSL_peek() are identical to SSL_read_ex() and SSL_read()
 respectively except no bytes are actually removed from the underlying BIO during
@@ -90,38 +90,32 @@ with the same arguments.
 
 SSL_read_ex() and SSL_peek_ex() will return 1 for success or 0 for failure.
 Success means that 1 or more application data bytes have been read from the SSL
-connection. Failure means that no bytes could be read from the SSL connection.
+connection.
+Failure means that no bytes could be read from the SSL connection.
 Failures can be retryable (e.g. we are waiting for more bytes to
-be delivered by the network) or non-retryable (e.g. a fatal network error). In
-the event of a failure call L<SSL_get_error(3)> to find out the reason which
+be delivered by the network) or non-retryable (e.g. a fatal network error).
+In the event of a failure call L<SSL_get_error(3)> to find out the reason which
 indicates whether the call is retryable or not.
 
 For SSL_read() and SSL_peek() the following return values can occur:
 
 =over 4
 
-=item E<gt>0
+=item E<gt> 0
 
-The read operation was successful; the return value is the number of
-bytes actually read from the TLS/SSL connection.
+The read operation was successful.
+The return value is the number of bytes actually read from the TLS/SSL
+connection.
 
-=item Z<>0
+=item Z<><= 0
 
-The read operation was not successful. The reason may either be a clean
-shutdown due to a "close notify" alert sent by the peer (in which case
-the SSL_RECEIVED_SHUTDOWN flag in the ssl shutdown state is set
-(see L<SSL_shutdown(3)>,
-L<SSL_set_shutdown(3)>). It is also possible, that
-the peer simply shut down the underlying transport and the shutdown is
-incomplete. Call SSL_get_error() with the return value B<ret> to find out,
-whether an error occurred or the connection was shut down cleanly
-(SSL_ERROR_ZERO_RETURN).
+The read operation was not successful, because either the connection was closed,
+an error occurred or action must be taken by the calling process.
+Call L<SSL_get_error(3)> with the return value B<ret> to find out the reason.
 
-=item E<lt>0
-
-The read operation was not successful, because either an error occurred
-or action must be taken by the calling process. Call SSL_get_error() with the
-return value B<ret> to find out the reason.
+Old documentation indicated a difference between 0 and -1, and that -1 was
+retryable.
+You should instead call SSL_get_error() to find out if it's retryable.
 
 =back