5 SSL_read - read bytes from a TLS/SSL connection.
9 #include <openssl/ssl.h>
11 int SSL_read(SSL *ssl, char *buf, int num);
15 SSL_read() tries to read B<num> bytes from the specified B<ssl> into the
20 If necessary, SSL_read() will negotiate a TLS/SSL session, if
21 not already explicitly performed by SSL_connect() or SSL_accept(). If the
22 peer requests a re-negotiation, it will be performed transparently during
23 the SSL_read() operation. The behaviour of SSL_read() depends on the
26 If the underlying BIO is B<blocking>, SSL_read() will only return, once the
27 read operation has been finished or an error occurred, except when a
28 renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur.
29 This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the
30 L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> call.
32 If the underlying BIO is B<non-blocking>, SSL_read() will also return
33 when the underlying BIO could not satisfy the needs of SSL_read()
34 to continue the operation. In this case a call to SSL_get_error() with the
35 return value of SSL_read() will yield B<SSL_ERROR_WANT_READ> or
36 B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a
37 call to SSL_read() can also cause write operations! The calling process
38 then must repeat the call after taking appropriate action to satisfy the
39 needs of SSL_read(). The action depends on the underlying BIO. When using a
40 non-blocking socket, nothing is to be done, but select() can be used to check
41 for the required condition. When using a buffering BIO, like a BIO pair, data
42 must be written into or retrieved out of the BIO before being able to continue.
46 When an SSL_read() operation has to be repeated because of
47 B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated
48 with the same arguments.
52 The following return values can occur:
58 The read operation was successful; the return value is the number of
59 bytes actually read from the TLS/SSL connection.
63 The read operation was not successful, probably because no data was
64 available. Call SSL_get_error() with the return value B<ret> to find out,
65 whether an error occurred.
69 The read operation was not successful, because either an error occurred
70 or action must be taken by the calling process. Call SSL_get_error() with the
71 return value B<ret> to find out the reason.
77 L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_write(3)|SSL_write(3)>,
78 L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>,
79 L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>