1*4724848cSchristos=pod 2*4724848cSchristos 3*4724848cSchristos=head1 NAME 4*4724848cSchristos 5*4724848cSchristosSSL_pending, SSL_has_pending - check for readable bytes buffered in an 6*4724848cSchristosSSL object 7*4724848cSchristos 8*4724848cSchristos=head1 SYNOPSIS 9*4724848cSchristos 10*4724848cSchristos #include <openssl/ssl.h> 11*4724848cSchristos 12*4724848cSchristos int SSL_pending(const SSL *ssl); 13*4724848cSchristos int SSL_has_pending(const SSL *s); 14*4724848cSchristos 15*4724848cSchristos=head1 DESCRIPTION 16*4724848cSchristos 17*4724848cSchristosData is received in whole blocks known as records from the peer. A whole record 18*4724848cSchristosis processed (e.g. decrypted) in one go and is buffered by OpenSSL until it is 19*4724848cSchristosread by the application via a call to L<SSL_read_ex(3)> or L<SSL_read(3)>. 20*4724848cSchristos 21*4724848cSchristosSSL_pending() returns the number of bytes which have been processed, buffered 22*4724848cSchristosand are available inside B<ssl> for immediate read. 23*4724848cSchristos 24*4724848cSchristosIf the B<SSL> object's I<read_ahead> flag is set (see 25*4724848cSchristosL<SSL_CTX_set_read_ahead(3)>), additional protocol bytes (beyond the current 26*4724848cSchristosrecord) may have been read containing more TLS/SSL records. This also applies to 27*4724848cSchristosDTLS and pipelining (see L<SSL_CTX_set_split_send_fragment(3)>). These 28*4724848cSchristosadditional bytes will be buffered by OpenSSL but will remain unprocessed until 29*4724848cSchristosthey are needed. As these bytes are still in an unprocessed state SSL_pending() 30*4724848cSchristoswill ignore them. Therefore, it is possible for no more bytes to be readable from 31*4724848cSchristosthe underlying BIO (because OpenSSL has already read them) and for SSL_pending() 32*4724848cSchristosto return 0, even though readable application data bytes are available (because 33*4724848cSchristosthe data is in unprocessed buffered records). 34*4724848cSchristos 35*4724848cSchristosSSL_has_pending() returns 1 if B<s> has buffered data (whether processed or 36*4724848cSchristosunprocessed) and 0 otherwise. Note that it is possible for SSL_has_pending() to 37*4724848cSchristosreturn 1, and then a subsequent call to SSL_read_ex() or SSL_read() to return no 38*4724848cSchristosdata because the unprocessed buffered data when processed yielded no application 39*4724848cSchristosdata (for example this can happen during renegotiation). It is also possible in 40*4724848cSchristosthis scenario for SSL_has_pending() to continue to return 1 even after an 41*4724848cSchristosSSL_read_ex() or SSL_read() call because the buffered and unprocessed data is 42*4724848cSchristosnot yet processable (e.g. because OpenSSL has only received a partial record so 43*4724848cSchristosfar). 44*4724848cSchristos 45*4724848cSchristos=head1 RETURN VALUES 46*4724848cSchristos 47*4724848cSchristosSSL_pending() returns the number of buffered and processed application data 48*4724848cSchristosbytes that are pending and are available for immediate read. SSL_has_pending() 49*4724848cSchristosreturns 1 if there is buffered record data in the SSL object and 0 otherwise. 50*4724848cSchristos 51*4724848cSchristos=head1 SEE ALSO 52*4724848cSchristos 53*4724848cSchristosL<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_CTX_set_read_ahead(3)>, 54*4724848cSchristosL<SSL_CTX_set_split_send_fragment(3)>, L<ssl(7)> 55*4724848cSchristos 56*4724848cSchristos=head1 HISTORY 57*4724848cSchristos 58*4724848cSchristosThe SSL_has_pending() function was added in OpenSSL 1.1.0. 59*4724848cSchristos 60*4724848cSchristos=head1 COPYRIGHT 61*4724848cSchristos 62*4724848cSchristosCopyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. 63*4724848cSchristos 64*4724848cSchristosLicensed under the OpenSSL license (the "License"). You may not use 65*4724848cSchristosthis file except in compliance with the License. You can obtain a copy 66*4724848cSchristosin the file LICENSE in the source distribution or at 67*4724848cSchristosL<https://www.openssl.org/source/license.html>. 68*4724848cSchristos 69*4724848cSchristos=cut 70