SSL_get_rpoll_descriptor.pod 3.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100
  1. =pod
  2. =head1 NAME
  3. SSL_get_rpoll_descriptor, SSL_get_wpoll_descriptor, SSL_net_read_desired,
  4. SSL_net_write_desired - obtain information which can be used to determine when
  5. network I/O can be performed
  6. =head1 SYNOPSIS
  7. #include <openssl/ssl.h>
  8. int SSL_get_rpoll_descriptor(SSL *s, BIO_POLL_DESCRIPTOR *desc);
  9. int SSL_get_wpoll_descriptor(SSL *s, BIO_POLL_DESCRIPTOR *desc);
  10. int SSL_net_read_desired(SSL *s);
  11. int SSL_net_write_desired(SSL *s);
  12. =head1 DESCRIPTION
  13. The functions SSL_get_rpoll_descriptor() and SSL_get_wpoll_descriptor() can be
  14. used to determine when an SSL object which represents a QUIC connection can
  15. perform useful network I/O, so that an application using a QUIC connection SSL
  16. object in nonblocking mode can determine when it should call SSL_handle_events().
  17. On success, these functions output poll descriptors. For more information on
  18. poll descriptors, see L<BIO_get_rpoll_descriptor(3)>.
  19. The functions SSL_net_read_desired() and SSL_net_write_desired() return 1 or 0
  20. depending on whether the SSL object is currently interested in receiving data
  21. from the network and/or writing data to the network respectively.
  22. If an SSL object is not interested in reading data from the network at the
  23. current time, SSL_net_read_desired() will return 0; likewise, if an SSL object is
  24. not interested in writing data to the network at the current time,
  25. SSL_net_write_desired() will return 0.
  26. The intention is that an application using QUIC in nonblocking mode can use
  27. these calls, in conjunction with L<SSL_get_event_timeout(3)> to wait for network
  28. I/O conditions which allow the SSL object to perform useful work. When such a
  29. condition arises, L<SSL_handle_events(3)> should be called.
  30. In particular, the expected usage is as follows:
  31. =over 4
  32. =item *
  33. SSL_handle_events() should be called whenever the timeout returned by
  34. SSL_get_event_timeout(3) (if any) expires
  35. =item *
  36. If the last call to SSL_net_read_desired() returned 1, SSL_handle_events() should be called
  37. whenever the poll descriptor output by SSL_get_rpoll_descriptor() becomes
  38. readable.
  39. =item *
  40. If the last call to SSL_net_write_desired() returned 1, SSL_handle_events() should be called
  41. whenever the poll descriptor output by SSL_get_wpoll_descriptor() becomes
  42. writable.
  43. =back
  44. The return values of the SSL_net_read_desired() and SSL_net_write_desired() functions
  45. may change in response to any call to the SSL object other than
  46. SSL_net_read_desired(), SSL_net_write_desired(), SSL_get_rpoll_descriptor(),
  47. SSL_get_wpoll_descriptor() and SSL_get_event_timeout().
  48. On non-QUIC SSL objects, calls to SSL_get_rpoll_descriptor() and
  49. SSL_get_wpoll_descriptor() function the same as calls to
  50. BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() on the respective read
  51. and write BIOs configured on the SSL object.
  52. On non-QUIC SSL objects, calls to SSL_net_read_desired() and
  53. SSL_net_write_desired() function identically to calls to SSL_want_read() and
  54. SSL_want_write() respectively.
  55. =head1 RETURN VALUES
  56. These functions return 1 on success and 0 on failure.
  57. =head1 SEE ALSO
  58. L<SSL_handle_events(3)>, L<SSL_get_event_timeout(3)>, L<ssl(7)>
  59. =head1 HISTORY
  60. The SSL_get_rpoll_descriptor(), SSL_get_wpoll_descriptor(), SSL_net_read_desired()
  61. and SSL_net_write_desired() functions were added in OpenSSL 3.2.
  62. =head1 COPYRIGHT
  63. Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved.
  64. Licensed under the Apache License 2.0 (the "License"). You may not use
  65. this file except in compliance with the License. You can obtain a copy
  66. in the file LICENSE in the source distribution or at
  67. L<https://www.openssl.org/source/license.html>.
  68. =cut