BIO_GET_RPOLL_DESCRIPTOR(3ossl)

💅 BIO_get_rpoll_descriptor(3ossl) — bestie's guide to poll descriptors ✨

okay so this is one of those OpenSSL pages, from the 3ossl manual, and honestly? it's lowkey iconic once you get what it's doing. no cap. let's get into it 🫶

---

🌸 NAME 🌸

BIO_get_rpoll_descriptor, BIO_get_wpoll_descriptor — these two give you back a structure, and that structure is literally your ticket to knowing when a BIO object can next be read from or written to. it's giving "hey bestie, tell me when it's my turn" energy 💅

---

✨ SYNOPSIS ✨

#include <openssl/bio.h>

typedef struct bio_poll_descriptor_st {
    uint32_t type;
    union {
        int        fd;
        void       *custom;
        uintptr_t  custom_ui;
    } value;
} BIO_POLL_DESCRIPTOR;

int BIO_get_rpoll_descriptor(BIO *b, BIO_POLL_DESCRIPTOR *desc);
int BIO_get_wpoll_descriptor(BIO *b, BIO_POLL_DESCRIPTOR *desc);

copy that exactly, okay? the struct is doing the work here and she does not want to be paraphrased 🔥

---

🦋 DESCRIPTION 🦋

so when BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() succeed, they fill *desc with a poll descriptor. and a poll descriptor? it's a tagged union structure that represents some kind of OS or non-OS resource — basically a thing you can synchronise on I/O availability events with. main character resource energy, honestly 👑

BIO_get_rpoll_descriptor() outputs a descriptor you can use to figure out when the BIO can (potentially) next be read, and BIO_get_wpoll_descriptor() outputs a descriptor you can use to figure out when the BIO can (potentially) next be written. two different questions, two different answers, we love to see it 💖

and it is permissible for BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() to output the same descriptor. yes bestie, they can twin. it's fine. it's allowed 🎀

poll descriptors can represent different kinds of information. a super typical kind of resource that might be represented by a poll descriptor is an OS file descriptor — the kind of thing you'd use with APIs such as select(). like, that's the classic example, your standard-issue vibe.

the kinds of poll descriptor defined by OpenSSL are:

• BIO_POLL_DESCRIPTOR_TYPE_NONE — this one represents the absence of a valid poll descriptor. it's what BIO_get_rpoll_descriptor() or BIO_get_wpoll_descriptor() might hand you to say "nah, this BIO is not pollable for readability (or writeability, respectively)". and for this type, literally no field within the value field of the BIO_POLL_DESCRIPTOR is valid. nothing. don't touch. it's empty, it's giving ghosted 💀
• BIO_POLL_DESCRIPTOR_TYPE_SOCK_FD — this one represents an OS socket resource. the field value.fd in the BIO_POLL_DESCRIPTOR is valid if it is not set to -1. so like, check that first, bestie 🧚

the resource here is whatever kind of handle a given OS uses to represent sockets, which — plot twist — may vary by OS. for example, on Windows, the value is a SOCKET for use with the Winsock API. on POSIX-like platforms, it is a file descriptor. slay for portability, i guess 🌈

where a poll descriptor of this type is output by BIO_get_rpoll_descriptor(), it should be polled for readability to determine when the BIO might next be able to successfully complete a BIO_read() operation. likewise, where a poll descriptor of this type is output by BIO_get_wpoll_descriptor(), it should be polled for writeability to determine when the BIO might next be able to successfully complete a BIO_write() operation. read for reads, write for writes — the symmetry ate 🔥

• BIO_POLL_DESCRIPTOR_CUSTOM_START — type values beginning with this value (inclusive) are reserved for application allocation for custom poll descriptor types. so like, this is your section of the playground 🎠 any of the definitions in the union field value can be used by the application arbitrarily as opaque values. do whatever, they're yours, we're not looking 👀

and because poll descriptors are a tagged union structure, they can represent different kinds of information. new types of poll descriptor may be defined — including by applications — according to their needs. the future is yours, babes ⭐

---

🌸 RETURN VALUES 🌸

the functions BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() return 1 on success and 0 on failure. classic 1 or 0 situation, no surprises, we respect the consistency 🫶

these functions are permitted to succeed and initialise *desc with a poll descriptor of type BIO_POLL_DESCRIPTOR_TYPE_NONE — which is the way of saying the BIO is not pollable for readability or writeability, respectively. so like, "success" doesn't always mean "here's your fd". sometimes success is just honesty 😭

---

🦋 SEE ALSO 🦋

SSL_handle_events(3), SSL_get_event_timeout(3), SSL_get_rpoll_descriptor(3), SSL_get_wpoll_descriptor(3), bio(7) — go read those too, they're all in the same friend group, iykyk 💜

---

✨ HISTORY ✨

the BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() functions were added in OpenSSL 3.2. so if you're on something older, bestie… she's not there yet 🙈

---

🎀 COPYRIGHT 🎀

Copyright 2022-2024 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 thing, bestie 🍓 this page was brought to you by version 3.5.6, dated 2026-04-07, from the BIO_GET_RPOLL_DESCRIPTOR(3ossl) corner of the OpenSSL universe. go poll something responsibly 💖✨👑