|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | NOTES | SEE ALSO | COLOPHON |
|
|
|
io_uring_setup_buf_ring(3) liburing Manual io_uring_setup_buf_ring(3)
io_uring_setup_buf_ring - setup and register buffer ring for
provided buffers
#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);
The io_uring_setup_buf_ring(3) function registers a shared buffer
ring to be used with provided buffers. For the request types that
support it, provided buffers are given to the ring and one is
selected by a request if it has IOSQE_BUFFER_SELECT set in the SQE
flags, when the request is ready to receive data. This allows both
clear ownership of the buffer lifetime, and a way to have more
read/receive type of operations in flight than buffers available.
The ring argument must be a pointer to the ring for which the
provided buffer ring is being registered, 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, and *err is a pointer to an integer for the error value
if any part of the ring allocation and registration fails.
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 handles the allocation of the ring
rather than letting the application open code it.
To unregister and free a buffer group ID setup with this function,
the application must call io_uring_free_buf_ring(3).
Available since 5.19.
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.
Note that 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.
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)
This page is part of the liburing (A library for io_uring)
project. Information about the project can be found at
⟨https://github.com/axboe/liburing⟩. If you have a bug report for
this manual page, send it to io-uring@vger.kernel.org. This page
was obtained from the project's upstream Git repository
⟨https://github.com/axboe/liburing⟩ on 2025-08-11. (At that time,
the date of the most recent commit that was found in the
repository was 2025-08-02.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
liburing-2.4 Mar 07, 2023 io_uring_setup_buf_ring(3)
Pages that refer to this page: io_uring_buf_ring_init(3), io_uring_free_buf_ring(3), io_uring_register_buf_ring(3), io_uring_setup_buf_ring(3)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|