SSL_read.pod revision 72613
168651Skris=pod 268651Skris 368651Skris=head1 NAME 468651Skris 568651SkrisSSL_read - read bytes from a TLS/SSL connection. 668651Skris 768651Skris=head1 SYNOPSIS 868651Skris 968651Skris #include <openssl/ssl.h> 1068651Skris 1168651Skris int SSL_read(SSL *ssl, char *buf, int num); 1268651Skris 1368651Skris=head1 DESCRIPTION 1468651Skris 1568651SkrisSSL_read() tries to read B<num> bytes from the specified B<ssl> into the 1668651Skrisbuffer B<buf>. 1768651Skris 1868651Skris=head1 NOTES 1968651Skris 2068651SkrisIf necessary, SSL_read() will negotiate a TLS/SSL session, if 2168651Skrisnot already explicitly performed by SSL_connect() or SSL_accept(). If the 2268651Skrispeer requests a re-negotiation, it will be performed transparently during 2368651Skristhe SSL_read() operation. The behaviour of SSL_read() depends on the 2468651Skrisunderlying BIO. 2568651Skris 2668651SkrisIf the underlying BIO is B<blocking>, SSL_read() will only return, once the 2768651Skrisread operation has been finished or an error occurred. 2868651Skris 2968651SkrisIf the underlying BIO is B<non-blocking>, SSL_read() will also return 3068651Skriswhen the underlying BIO could not satisfy the needs of SSL_read() 3168651Skristo continue the operation. In this case a call to SSL_get_error() with the 3268651Skrisreturn value of SSL_read() will yield B<SSL_ERROR_WANT_READ> or 3368651SkrisB<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a 3468651Skriscall to SSL_read() can also cause write operations! The calling process 3568651Skristhen must repeat the call after taking appropriate action to satisfy the 3668651Skrisneeds of SSL_read(). The action depends on the underlying BIO. When using a 3768651Skrisnon-blocking socket, nothing is to be done, but select() can be used to check 3868651Skrisfor the required condition. When using a buffering BIO, like a BIO pair, data 3968651Skrismust be written into or retrieved out of the BIO before being able to continue. 4068651Skris 4168651Skris=head1 WARNING 4268651Skris 4368651SkrisWhen an SSL_read() operation has to be repeated because of 4468651SkrisB<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated 4568651Skriswith the same arguments. 4668651Skris 4768651Skris=head1 RETURN VALUES 4868651Skris 4968651SkrisThe following return values can occur: 5068651Skris 5168651Skris=over 4 5268651Skris 5368651Skris=item E<gt>0 5468651Skris 5568651SkrisThe read operation was successful; the return value is the number of 5668651Skrisbytes actually read from the TLS/SSL connection. 5768651Skris 5868651Skris=item 0 5968651Skris 6068651SkrisThe read operation was not successful, probably because no data was 6168651Skrisavailable. Call SSL_get_error() with the return value B<ret> to find out, 6268651Skriswhether an error occurred. 6368651Skris 6472613Skris=item E<lt>0 6568651Skris 6668651SkrisThe read operation was not successful, because either an error occurred 6768651Skrisor action must be taken by the calling process. Call SSL_get_error() with the 6868651Skrisreturn value B<ret> to find out the reason. 6968651Skris 7068651Skris=back 7168651Skris 7268651Skris=head1 SEE ALSO 7368651Skris 7468651SkrisL<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_write(3)|SSL_write(3)>, 7568651SkrisL<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> 7668651Skris 7768651Skris=cut 78