|
@@ -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
|
|
|
|