SSL_GET_RPOLL_DESCRIPTOR(3SSL)

📦
version 4.0.3 · 6 versions
, in ubuntu stonking

💅 SSL_GET_RPOLL_DESCRIPTOR 💅

okay bestie, welcome to the OpenSSL corner of the man pages. this one lives in section 3SSL, and it's all about knowing when your QUIC connection actually wants to do network stuff. no cap, it's giving "how do i know when to wake my socket up" energy. 🦋

✨ NAME ✨

SSL_get_rpoll_descriptor, SSL_get_wpoll_descriptor, SSL_net_read_desired, SSL_net_write_desired — get the info you need to figure out when network I/O can actually happen, fr fr.

🌸 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 like, SSL_get_rpoll_descriptor() and SSL_get_wpoll_descriptor() are the ones you call when you've got an SSL object that represents a QUIC connection, and you wanna know when it could do something actually useful over the network. the whole point is that if your app is using a QUIC connection SSL object in nonblocking mode, these tell you when it's time to hit up SSL_handle_events().

on success, these functions output poll descriptors. wanna know more about what a poll descriptor even is? go read BIO_get_rpoll_descriptor(3). iykyk. ✨

then there's SSL_net_read_desired() and SSL_net_write_desired(), which return 1 or 0 depending on whether the SSL object is currently, like, interested in receiving data from the network, and/or writing data to the network. respectively. 💖

  • if the SSL object is not interested in reading from the network right now, SSL_net_read_desired() returns 0.
  • same vibe for writing: if it's not interested in writing to the network right now, SSL_net_write_desired() returns 0.

the whole intention here? an app running QUIC in nonblocking mode can use these calls, paired up with SSL_get_event_timeout(3), to wait for the network I/O conditions that let the SSL object do useful work. and the moment one of those conditions shows up, bestie, you call SSL_handle_events(3). slay. 👑

🌈 the expected usage (the vibes)

  1. call SSL_handle_events() whenever the timeout returned by SSL_get_event_timeout(3) (if there is one) expires.
  2. if the last call to SSL_net_read_desired() returned 1, call SSL_handle_events() whenever the poll descriptor output by SSL_get_rpoll_descriptor() becomes readable.
  3. if the last call to SSL_net_write_desired() returned 1, call SSL_handle_events() 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() can 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(). so don't go assuming they're frozen in place. 💀

🦋 non-QUIC objects (yes, they still eat)

on SSL objects that aren't QUIC, 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.

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.

⭐ RETURN VALUES ⭐

these functions return 1 on success and 0 on failure. periodt.

🫶 SEE ALSO 🫶

🧚 HISTORY 🧚

SSL_get_rpoll_descriptor(), SSL_get_wpoll_descriptor(), SSL_net_read_desired() and SSL_net_write_desired() all showed up in OpenSSL 3.2. iconic behavior, honestly. 🌟

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 a wrap, bestie 🎀 this page came straight out of OpenSSL 4.0.3, dated 2026-09-29, and it's the SSL_GET_RPOLL_DESCRIPTOR(3SSL) one. go forth and poll responsibly. 💅✨

📦 where this page comes from