SSL_GET_RPOLL_DESCRIPTOR(3ossl)

🦋 SSL_GET_RPOLL_DESCRIPTOR 🦋

okay bestie, welcome to the 3ossl girlies' corner of the OpenSSL manual — this one's all about figuring out when your network I/O can actually do something useful ✨

🌸 NAME 🌸

SSL_get_rpoll_descriptor, SSL_get_wpoll_descriptor, SSL_net_read_desired, SSL_net_write_desired — the little squad of functions that hand you the info you need to know when network I/O can actually happen 💅

💖 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);

✨ DESCRIPTION ✨

So SSL_get_rpoll_descriptor() and SSL_get_wpoll_descriptor() are your go-tos when you need to know when an SSL object that represents a QUIC connection can do useful network I/O — like, the whole point is that if your app is using a QUIC connection SSL object in nonblocking mode, you can figure out when you should be calling SSL_handle_events(). no cap, that's the vibe 🫶

On success, these functions output poll descriptors. Want the full lore on poll descriptors? Go read BIO_get_rpoll_descriptor(3), it's all there 📖

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 at the current time, SSL_net_read_desired() will return 0; likewise, if an SSL object is not interested in writing data to the network at the current time, SSL_net_write_desired() will return 0. simple as that 💀

The intention here — the whole main character energy of this page — is that an app using QUIC in nonblocking mode can use these calls, together with SSL_get_event_timeout(3), to wait for network I/O conditions that let the SSL object do useful work. And when that condition shows up? That's your cue to call SSL_handle_events(3). slay 🎀

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 other than SSL_net_read_desired(), SSL_net_write_desired(), SSL_get_rpoll_descriptor(), SSL_get_wpoll_descriptor() and SSL_get_event_timeout(). so don't go assuming they're frozen in time 🙈

On non-QUIC SSL objects, 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. lowkey just delegation, we love to see it 💜

And on non-QUIC SSL objects, calls to SSL_net_read_desired() and SSL_net_write_desired() function identically to calls to SSL_want_read() and SSL_want_write() respectively. iconic behaviour, honestly 🌈

🔥 RETURN VALUES 🔥

These functions return 1 on success and 0 on failure. short and sweet, periodt 💅

🦋 SEE ALSO 🦋

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

👑 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. glow-up era ✨

🍓 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, bestie 🧚 this was version 3.5.6, dated 2026-04-07, straight from the SSL_GET_RPOLL_DESCRIPTOR(3ossl) files — go forth and poll responsibly 💖⭐