io_uring_register_buffers(3)

✨ io_uring_register_buffers ✨

okay bestie, welcome to the liburing manual — this one is literally all about registering buffers so your fixed buffer ops can pop off 💅

💖 NAME 💖

io_uring_register_buffers — register buffers for fixed buffer operations 🦋

🌸 SYNOPSIS 🌸

#include <liburing.h>

int io_uring_register_buffers(struct io_uring *ring,
                              const struct iovec *iovecs,
                              unsigned nr_iovecs);

int io_uring_register_buffers_tags(struct io_uring *ring,
                                   const struct iovec *iovecs,
                                   const __u64 *tags,
                                   unsigned nr);

int io_uring_register_buffers_sparse(struct io_uring *ring,
                                     unsigned nr_iovecs);

int io_uring_register_buffers_update_tag(struct io_uring *ring,
                                         unsigned off,
                                         const struct iovec *iovecs,
                                         const __u64 *tags,
                                         unsigned nr);

🎀 DESCRIPTION 🎀

so. io_uring_register_buffers(3) registers nr_iovecs number of buffers — and those buffers are defined by the array iovecs, and they belong to the ring. that's the whole vibe 💫

io_uring_register_buffers_tags(3) does exactly the same thing as io_uring_register_buffers(3), no cap — but it additionally takes a tags parameter. if you wanna know how the resource tagging works, go look at IORING_REGISTER_BUFFERS2, it's all there 🫶

io_uring_register_buffers_sparse(3) registers nr_iovecs empty buffers belonging to the ring. bestie, listen — these buffers must be updated before use, like using io_uring_register_buffers_update_tag(3) or whatever equivalent. don't skip that step, i'm serious 😭

once the caller has registered the buffers, they can be used with one of the fixed buffers functions. iconic behavior honestly 👑

registered buffers are an optimization — and the tea is that it's super useful alongside O_DIRECT reads and writes. the way it works is: it maps the specified range into the kernel once, when the buffer is registered, instead of doing a whole map-and-unmap for every single IO every single time IO is performed to that region. exhausting, right? additionally, it also avoids manipulating the page reference counts for each IO. efficiency queen ✨

io_uring_register_buffers_update_tag(3) updates registered buffers with new ones — either turning a sparse entry into a real one, or replacing an existing entry, dealer's choice 💅 the off is the offset on which to start the update, and it updates nr number of buffers defined by the array iovecs belonging to the ring. the tags points to an array of tags. again, for the resource tagging description, see IORING_REGISTER_BUFFERS2 🌈

🦋 RETURN VALUE 🦋

on success, io_uring_register_buffers(3), io_uring_register_buffers_tags(3) and io_uring_register_buffers_sparse(3) return 0. slay ⭐

io_uring_register_buffers_update_tag(3) returns the number of buffers updated — so it's not just a boring old zero, it's giving receipts 📋

on failure they return -errno. yeah. that kind of failure 😔

🔥 SEE ALSO 🔥

• io_uring_register(2)
• io_uring_get_sqe(3)
• io_uring_unregister_buffers(3)
• io_uring_clone_buffers(3)
• io_uring_register_buf_ring(3)
• io_uring_prep_read_fixed(3)
• io_uring_prep_write_fixed(3)

and that's the page, bestie — this whole thing came to you from liburing-2.1, dated November 15, 2021. mwah, go register those buffers 💖🧚‍♀️