SSL_GET_RPOLL_DESCRIPTOR(3ossl)

💖 SSL_GET_RPOLL_DESCRIPTOR 💖

okay bestie so you're in 3ossl land and you wanna know when your QUIC connection is actually ready to do network stuff instead of just spinning your event loop for no reason?? say less. this page is literally the glow-up guide for SSL_get_rpoll_descriptor, SSL_get_wpoll_descriptor, SSL_net_read_desired and SSL_net_write_desired — the four functions that tell you when network I/O can be performed. no cap.

---

✨ NAME ✨

SSL_get_rpoll_descriptor, SSL_get_wpoll_descriptor, SSL_net_read_desired, SSL_net_write_desired — obtain information which can be used to determine when network I/O can be performed 🦋

---

🌸 SYNOPSIS 🌸

#include <openssl/ssl.h>

int SSL_get_rpoll_descriptor(SSL *s, BIO_POLL_DESCRIPTOR *desc);
int SSL_get_wpoll_descriptor(SSL *s, BIO_POLL_DESCRIPTOR *desc);
int SSL_net_read_desired(SSL *s);
int SSL_net_write_desired(SSL *s);

like. that's it. four little guys. 🫶

---

💅 DESCRIPTION 💅

so SSL_get_rpoll_descriptor() and SSL_get_wpoll_descriptor() are the ones you call when you've got an SSL object representing a QUIC connection and you need to know when it can do useful network I/O. translation: if your app is using a QUIC connection SSL object in nonblocking mode, these tell you when you should be calling SSL_handle_events() instead of just sitting there guessing. 💀

On success, these functions output poll descriptors. For more info on what a poll descriptor even is, go read BIO_get_rpoll_descriptor(3) — she explains it better than I ever could.

Then we've got SSL_net_read_desired() and SSL_net_write_desired(), which return 1 or 0 depending on whether the SSL object is currently interested in receiving data from the network and/or writing data to the network, respectively. so:

• if an SSL object is not interested in reading data from the network right now, SSL_net_read_desired() returns 0
• if an SSL object is not interested in writing data to the network right now, SSL_net_write_desired() returns 0

main character energy is knowing when to chill and when to move. ✨

The intention — and yes, the manpage says "intention", so we're being intentional — is that an application using QUIC in nonblocking mode can use these calls, in conjunction with SSL_get_event_timeout(3), to wait for network I/O conditions which allow the SSL object to perform useful work. And when such a condition arises, SSL_handle_events(3) should be called. periodt.

In particular, the expected usage is as follows:

• SSL_handle_events() should be called whenever the timeout returned by SSL_get_event_timeout(3) (if any) expires ⏰
• If the last call to SSL_net_read_desired() returned 1, SSL_handle_events() should be called whenever the poll descriptor output by SSL_get_rpoll_descriptor() becomes readable.
• If the last call to SSL_net_write_desired() returned 1, SSL_handle_events() should be called whenever the poll descriptor output by SSL_get_wpoll_descriptor() becomes writable.

⚠️ heads up bestie, the return values of SSL_net_read_desired() and SSL_net_write_desired() may change in response to any call to the SSL object — except for SSL_net_read_desired(), SSL_net_write_desired(), SSL_get_rpoll_descriptor(), SSL_get_wpoll_descriptor() and SSL_get_event_timeout(). those five are the safe ones. everything else can flip the vibe.

Now, if you're on a non-QUIC SSL object (iykyk, the classic), things get even simpler:

• calls to SSL_get_rpoll_descriptor() and SSL_get_wpoll_descriptor() function the same as calls to BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() on the respective read and write BIOs configured on the SSL object 🌈
• calls to SSL_net_read_desired() and SSL_net_write_desired() function identically to calls to SSL_want_read() and SSL_want_write() respectively 💖

---

🎀 RETURN VALUES 🎀

These functions return 1 on success and 0 on failure. that's the whole thing. iconic, honestly.

---

👑 SEE ALSO 👑

SSL_handle_events(3), SSL_get_event_timeout(3), ssl(7)

go read those too, bestie, they're all part of the same friend group 🧚

---

⭐ HISTORY ⭐

The SSL_get_rpoll_descriptor(), SSL_get_wpoll_descriptor(), SSL_net_read_desired() and SSL_net_write_desired() functions were added in OpenSSL 3.2. so if you're on anything older, sorry babe, they don't exist yet 😭

---

💜 COPYRIGHT 💜

Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

---

and that's the whole page, slay 💅 this was OpenSSL version 3.5.9, dated 2026-09-29 — mwah, go forth and poll responsibly 🦋✨