SSL_pending.pod 2.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869
  1. =pod
  2. =head1 NAME
  3. SSL_pending, SSL_has_pending - check for readable bytes buffered in an
  4. SSL object
  5. =head1 SYNOPSIS
  6. #include <openssl/ssl.h>
  7. int SSL_pending(const SSL *ssl);
  8. int SSL_has_pending(const SSL *s);
  9. =head1 DESCRIPTION
  10. Data is received in whole blocks known as records from the peer. A whole record
  11. is processed (e.g. decrypted) in one go and is buffered by OpenSSL until it is
  12. read by the application via a call to L<SSL_read_ex(3)> or L<SSL_read(3)>.
  13. SSL_pending() returns the number of bytes which have been processed, buffered
  14. and are available inside B<ssl> for immediate read.
  15. If the B<SSL> object's I<read_ahead> flag is set (see
  16. L<SSL_CTX_set_read_ahead(3)>), additional protocol bytes (beyond the current
  17. record) may have been read containing more TLS/SSL records. This also applies to
  18. DTLS and pipelining (see L<SSL_CTX_set_split_send_fragment(3)>). These
  19. additional bytes will be buffered by OpenSSL but will remain unprocessed until
  20. they are needed. As these bytes are still in an unprocessed state SSL_pending()
  21. will ignore them. Therefore it is possible for no more bytes to be readable from
  22. the underlying BIO (because OpenSSL has already read them) and for SSL_pending()
  23. to return 0, even though readable application data bytes are available (because
  24. the data is in unprocessed buffered records).
  25. SSL_has_pending() returns 1 if B<s> has buffered data (whether processed or
  26. unprocessed) and 0 otherwise. Note that it is possible for SSL_has_pending() to
  27. return 1, and then a subsequent call to SSL_read_ex() or SSL_read() to return no
  28. data because the unprocessed buffered data when processed yielded no application
  29. data (for example this can happen during renegotiation). It is also possible in
  30. this scenario for SSL_has_pending() to continue to return 1 even after an
  31. SSL_read_ex() or SSL_read() call because the buffered and unprocessed data is
  32. not yet processable (e.g. because OpenSSL has only received a partial record so
  33. far).
  34. =head1 RETURN VALUES
  35. SSL_pending() returns the number of buffered and processed application data
  36. bytes that are pending and are available for immediate read. SSL_has_pending()
  37. returns 1 if there is buffered record data in the SSL object and 0 otherwise.
  38. =head1 SEE ALSO
  39. L<SSL_read_ex(3)>, L<SSL_read(3)>, L<SSL_CTX_set_read_ahead(3)>,
  40. L<SSL_CTX_set_split_send_fragment(3)>, L<ssl(7)>
  41. =head1 HISTORY
  42. The SSL_has_pending() function was added in OpenSSL 1.1.0.
  43. =head1 COPYRIGHT
  44. Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
  45. Licensed under the Apache License 2.0 (the "License"). You may not use
  46. this file except in compliance with the License. You can obtain a copy
  47. in the file LICENSE in the source distribution or at
  48. L<https://www.openssl.org/source/license.html>.
  49. =cut