BIO_GET_RPOLL_DESCRIPTOR(3SSL)

📦
version 4.0.3 · 6 versions
, in ubuntu stonking

💖 BIO_GET_RPOLL_DESCRIPTOR(3SSL) 💖

okay bestie so this is a page from the OpenSSL manual, section 3SSL, and it's all about two lil functions that tell you when a BIO is gonna be ready for reads or writes. no cap, this is the "hey is it my turn yet" API. 🎀

✨ NAME ✨

BIO_get_rpoll_descriptor, BIO_get_wpoll_descriptor — grab yourself a structure that you can use to figure out when a BIO object can next be read from or written to. it's giving "poll me, bestie" energy fr fr.

✨ 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 like, on success, BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() fill in *desc with a poll descriptor. 💅 a poll descriptor is a tagged union structure, which is a fancy way of saying "it's a thing that says what kind of thing it is, and then the thing". it represents some kind of OS or non-OS resource that you can use to synchronise on I/O availability events. iykyk.

BIO_get_rpoll_descriptor() hands you a descriptor you can use to determine when the BIO can (potentially) next be read. BIO_get_wpoll_descriptor() hands you one you can use to determine when the BIO can (potentially) next be written. 💖

and yes, it's totally permissible for BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() to output the same descriptor. no drama, they can share. 🫶

poll descriptors can represent different kinds of information. a typical kind of resource they might represent is an OS file descriptor, which you can use with APIs such as select(). classic.

the kinds of poll descriptor that OpenSSL defines are:

  • BIO_POLL_DESCRIPTOR_TYPE_NONE — represents the absence of a valid poll descriptor. it might be used by BIO_get_rpoll_descriptor() or BIO_get_wpoll_descriptor() to say "nah this BIO is not pollable for readability or writeability respectively". for this type, no field inside the value field of the BIO_POLL_DESCRIPTOR is valid. like, none of them. don't touch. 🚫
  • BIO_POLL_DESCRIPTOR_TYPE_SOCK_FD — this poll descriptor represents an OS socket resource. the field value.fd in the BIO_POLL_DESCRIPTOR is valid if it's not set to -1. the resource is whatever kind of handle a given OS uses to represent sockets, which — surprise — can 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. 🌈

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. match the poll to the vibe, okay? ✨

  • 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. go off, build your own, we won't look. 👑

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 bestie. 🦋

✨ RETURN VALUES ✨

BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() return 1 on success and 0 on failure. simple as. ✨

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, a "yes" that means "no" but it's not a failure. the way that works is iconic honestly. 😭

✨ SEE ALSO ✨

go read those too, they're all in the same friend group. 💜

✨ HISTORY ✨

the BIO_get_rpoll_descriptor() and BIO_get_wpoll_descriptor() functions were added in OpenSSL 3.2. new-ish but already main character energy. ⭐

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>.

bestie this page is from OpenSSL version 4.0.3, dated 2026-09-29 — that's the tea, that's the whole manual page BIO_GET_RPOLL_DESCRIPTOR(3SSL), and you ate it. periodt. 💅🎀🦋
📦 where this page comes from