io_uring_setup_buf_ring(3)

✨ io_uring_setup_buf_ring(3) — the liburing glow-up ✨

okay bestie, so this one lives in the liburing Manual and it's literally about setting up and registering a buffer ring for provided buffers. let's get into it 💖

---

🌸 NAME 🌸

io_uring_setup_buf_ring — setup and register buffer ring for provided buffers

---

🦋 SYNOPSIS 🦋

#include <liburing.h>

struct io_uring_buf_ring *io_uring_setup_buf_ring(struct io_uring *ring,
                                                  unsigned int nentries,
                                                  int bgid,
                                                  unsigned int flags,
                                                  int *err);

---

👑 DESCRIPTION 👑

So io_uring_setup_buf_ring(3) registers a shared buffer ring that you're gonna use with provided buffers. for the request types that support it, provided buffers get handed over to the ring, and then a request can pick one out if it has IOSQE_BUFFER_SELECT set in the SQE flags — but only when the request is actually ready to receive data. the way this slays is that it gives you clear ownership of the buffer lifetime, plus a way to have more read/receive type operations in flight than you have buffers available. main character energy fr 🔥

• the ring argument must be a pointer to the ring that the provided buffer ring is being registered for
• nentries is the number of entries requested in the buffer ring. this argument must be a power-of 2 in size, and can be up to 32768 in size
• bgid is the chosen buffer group ID
• flags are modifier flags for the operation
• *err is a pointer to an integer for the error value, in case any part of the ring allocation and registration fails

💅 flags values 💅

The flags argument can be set to one of the following values:

• IOU_PBUF_RING_INC — the buffers in this ring can be incrementally consumed. with partial consumption, each completion of a given buffer ID will continue where the previous one left off, or from the start if no completions have been seen yet. when more completions should be expected for a given buffer ID, the CQE will have IORING_CQE_F_BUF_MORE set in the flags member. Available since 6.12.

---

under the covers, this function uses io_uring_register_buf_ring(3) to register the ring, and it handles the allocation of the ring itself instead of letting the application open code it. no cap, it's doing the work so you don't have to 🫶

and to unregister and free a buffer group ID that you set up with this function, the application must call io_uring_free_buf_ring(3). don't leave it hanging bestie 😭

Available since 5.19.

---

⭐ RETURN VALUE ⭐

• On success, io_uring_setup_buf_ring(3) returns a pointer to the buffer ring 💖
• On failure it returns NULL and sets *err to -errno 💀

---

🎀 NOTES 🎀

heads up: even if the kernel supports this feature, registering a provided buffer ring may still fail with -EINVAL if the host is a 32-bit architecture and the memory being passed in resides in high memory. it's giving ✨circumstantial✨, not a you problem.

---

🌈 SEE ALSO 🌈

• io_uring_register_buf_ring(3)
• io_uring_buf_ring_init(3)
• io_uring_buf_ring_add(3)
• io_uring_buf_ring_advance(3)
• io_uring_buf_ring_cq_advance(3)

---

and that's the whole page, bestie — this one's from liburing-2.4, dated Mar 07, 2023. go register some rings and stay iconic 👑💜