io_uring_clone_buffers(3)

💖 io_uring_clone_buffers(3) 💖

okay so bestie, this is a page from the liburing Manual and it's about copying your registered buffers from one ring to another. no cap, it's giving "sharing is caring" but for kernel rings. let's get into it 🫶

---

✨ NAME ✨

io_uring_clone_buffers — clones registered buffers between rings

---

🌸 SYNOPSIS 🌸

#include <liburing.h>

int io_uring_clone_buffers(struct io_uring *dst,
                           struct io_uring * src);

int __io_uring_clone_buffers(struct io_uring *dst,
                             struct io_uring * src,
                             unsigned int flags);

int io_uring_clone_buffers_offset(struct io_uring *dst,
                                  struct io_uring * src,
                                  unsigned int dst_off,
                                  unsigned int src_off,
                                  unsigned int nr,
                                  unsigned int flags);

int __io_uring_clone_buffers_offset(struct io_uring *dst,
                                    struct io_uring * src,
                                    unsigned int dst_off,
                                    unsigned int src_off,
                                    unsigned int nr,
                                    unsigned int flags);

---

🦋 DESCRIPTION 🦋

so io_uring_clone_buffers(3) clones registered buffers from the ring that is src over to the ring that is dst. once it's done and slaying, src and dst will literally have the same set of registered buffers. it's giving twins 👯 this whole operation is identical to doing an io_uring_register_buffers(3) on the dst ring, IF the src ring already had that exact same buffer registration done before. iykyk.

🚨 bestie, heads up: the dst ring must NOT have any buffers currently registered. if it does, you gotta unregister them with io_uring_unregister_buffers(3) first. no skipping this step, fr fr.

for __io_uring_clone_buffers(3), the only difference is that it takes a flags argument. okay so here's the tea 🍵 — by default, if the destination ring has a registered file descriptor through io_uring_register_ring_fd(3) AND the app doing the calling is not the thread that registered that ring, then the kernel literally doesn't know how to look up the destination. and that's problematic because io_uring_clone_buffers(3) defaults to using the registered index if the destination is set up as such. so use __io_uring_clone_buffers(3), which doesn't set IORING_REGISTER_SRC_REGISTERED by default. the catch? the application still has to have the original ring file descriptor open. see below for the flag definition 👇

Available since kernel 6.12.

now, io_uring_clone_buffers_offset(3) also clones buffers from the src ring to the dst ring, but it supports cloning only a subset of the buffers, whereas io_uring_clone_buffers(3) always clones, like, all of them. dst_off says at what offset cloning should start in the destination, src_off says at what offset cloning should start in the source, and nr says how many buffers to clone at the given offset. and if dst_off, src_off, and nr are all given as 0, then io_uring_clone_buffers_offset(3) does the exact same thing as io_uring_clone_buffers(3). iconic behavior tbh ✨

while io_uring_clone_buffers_offset(3) sets IORING_REGISTER_SRC_REGISTERED by default, the __io_uring_clone_buffers_offset(3) does not. see the explanation for __io_uring_clone_buffers(3) for the details 👑

flags may be set to the following value:

• IORING_REGISTER_SRC_REGISTERED — if the source ring is registered AND the calling thread is the one that originally registered its ring fd, then this flag may be set to look up the registered index rather than use the normal file descriptor. and if the normal file descriptor wasn't closed after registering it, there's literally no need to set this flag. you're already good 💅
• IORING_REGISTER_DST_REPLACE — if set, cloning may happen for a destination ring that already has a buffer table assigned. in that case, existing nodes that overlap with the specified range will be released and replaced. out with the old, in with the new 🎀

Available since kernel 6.13.

---

🎀 NOTES 🎀

the source and target ring must shared address spaces, and hence internal kernel accounting. (yes bestie, that's exactly how it's worded, we don't make the rules 💀)

---

🔥 RETURN VALUE 🔥

on success, io_uring_clone_buffers(3) and io_uring_clone_buffers_offset(3) return 0. on failure, they returns -errno, specifically:

• -EBUSY — the destination ring already has buffers registered, and IORING_REGISTER_DST_REPLACE wasn't set. 😭
• -ENOMEM — the kernel ran out of memory. 💀
• -ENXIO — the source ring doesn't have any buffers registered. 🙈

---

👑 SEE ALSO 👑

• io_uring_register(2)
• io_uring_unregister_buffers(3)
• io_uring_register_buffers(3)
• io_uring_prep_read_fixed(3)
• io_uring_prep_write_fixed(3)

---

and that's the whole page bestie, you ate it up 🌈💖 this little love letter came to you from liburing-2.9, dated September 12, 2024. go clone some buffers, you main character 👑✨🦋