BIO_GET_RPOLL_DESCRIPTOR(3ossl)

💅 BIO_GET_RPOLL_DESCRIPTOR(3ossl) — an OpenSSL manual, but make it make sense

okay so bestie, welcome to the 3ossl corner of the OpenSSL manual — the bit where we talk about poll descriptors, and yes i promise it's more fun than it sounds 🫶

---

✨ NAME ✨

BIO_get_rpoll_descriptor, BIO_get_wpoll_descriptor — grab a structure that tells you when a BIO object can next be read or written. it's giving "hey, is this thing ready yet?" 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);

---

🦋 DESCRIPTION 🦋

so BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor(), when they succeed, fill *desc with a poll descriptor. and what is a poll descriptor, you ask? it's a tagged union structure that represents some kind of OS or non-OS resource — literally anything you can synchronise on I/O availability events with. iconic 🔥

BIO_get_rpoll_descriptor() hands you a descriptor you can use to figure out when the BIO can (potentially) next be read, and BIO_get_wpoll_descriptor() hands you one you can use to figure out when the BIO can (potentially) next be written. read vs write, the eternal struggle 💀

and here's a cute detail: it's totally permissible for BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() to output the same descriptor. twins! 👑

poll descriptors can represent different kinds of information. the classic vibe is an OS file descriptor — the kind of thing you'd use with APIs such as select().

the kinds of poll descriptor that OpenSSL defines are, in order:

• BIO_POLL_DESCRIPTOR_TYPE_NONE — represents the absence of a valid poll descriptor. BIO_get_rpoll_descriptor() or BIO_get_wpoll_descriptor() may use it to say "nah, this BIO isn't pollable for readability" or "…for writeability" respectively. for this type, no field within the value field of the BIO_POLL_DESCRIPTOR is valid. nothing. zero. don't touch 🙈
• BIO_POLL_DESCRIPTOR_TYPE_SOCK_FD — the poll descriptor represents an OS socket resource. the field value.fd in the BIO_POLL_DESCRIPTOR is valid as long as it's not set to -1. the resource is whatever kind of handle a given OS uses to represent sockets, which — surprise — may vary by OS. for example, on Windows the value is a SOCKET for use with the Winsock API; on POSIX-like platforms it's a file descriptor. same idea, different costume 💅

where a poll descriptor of this type comes out of BIO_get_rpoll_descriptor(), you should poll it for readability to determine when the BIO might next be able to successfully complete a BIO_read() operation. likewise, where one comes out of BIO_get_wpoll_descriptor(), poll it for writeability to determine when the BIO might next be able to successfully complete a BIO_write() operation. matching the poll mode to the operation? that's the whole game, bestie ✨

• BIO_POLL_DESCRIPTOR_CUSTOM_START — type values beginning with this value (inclusive) are reserved for application allocation for custom poll descriptor types. any of the definitions in the union field value can be used by the application arbitrarily as opaque values. it's your sandbox, go off 🎀

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 customizable fr fr 🌈

---

💖 RETURN VALUES 💖

• BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() return 1 on success and 0 on failure. one for yay, zero for nay 🍓

these functions are permitted to succeed and initialise *desc with a poll descriptor of type BIO_POLL_DESCRIPTOR_TYPE_NONE to indicate that the BIO is not pollable for readability or writeability respectively. so like… success that means "not pollable"? yes. that's a thing. don't come for them 😭

---

🌟 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 the whole friend group 🫶

---

⭐ HISTORY ⭐

the BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() functions were added in OpenSSL 3.2. so they're not ancient lore, they're new-gen 👑

---

🎀 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 page, bestie 💜 — brought to you by OpenSSL 3.5.0, dated 2026-09-25, filed under BIO_GET_RPOLL_DESCRIPTOR(3ossl). now go poll something responsibly, mwah 🌸