io_uring_register_buf_ring(3) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | NOTES | SEE ALSO | COLOPHON

io_uring_re...er_buf_ring(3) liburing Manualio_uring_re...er_buf_ring(3)

NAME         top

       io_uring_register_buf_ring - register buffer ring for provided
       buffers

SYNOPSIS         top

       #include <liburing.h>

       int io_uring_register_buf_ring(struct io_uring *ring,
                                      struct io_uring_buf_reg *reg,
                                      unsigned int flags);

DESCRIPTION         top

       The io_uring_register_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 reg argument must be filled in with the appropriate
       information. It looks as follows:

           struct io_uring_buf_reg {
               __u64 ring_addr;
               __u32 ring_entries;
               __u16 bgid;
               __u16 pad;
               __u64 resv[3];
           };

       The ring_addr field must contain the address to the memory
       allocated to fit this ring.  The memory must be page aligned and
       hence allocated appropriately using eg posix_memalign(3) or
       similar. The size of the ring is the product of ring_entries and
       the size of struct io_uring_buf.  ring_entries is the desired
       size of the ring, and must be a power-of-2 in size. The maximum
       size allowed is 2^15 (32768).  bgid is the buffer group ID
       associated with this ring. SQEs that select a buffer have a
       buffer group associated with them in their buf_group field, and
       the associated CQEs will have IORING_CQE_F_BUFFER set in their
       flags member, which will also contain the specific ID of the
       buffer selected. The rest of the fields are reserved and must be
       cleared to zero.

       The flags argument is currently unused and must be set to zero.

       A shared buffer ring looks as follows:

           struct io_uring_buf_ring {
               union {
                struct {
                       __u64 resv1;
                       __u32 resv2;
                       __u16 resv3;
                       __u16 tail;
                };
                struct io_uring_buf bufs[0];
               };
           };

       where tail is the index at which the application can insert new
       buffers for consumption by requests, and struct io_uring_buf is
       buffer definition:

           struct io_uring_buf {
               __u64 addr;
               __u32 len;
               __u16 bid;
               __u16 resv;
           };

       where addr is the address for the buffer, len is the length of
       the buffer in bytes, and bid is the buffer ID that will be
       returned in the CQE once consumed.

       Reserved fields must not be touched. Applications must use
       io_uring_buf_ring_init(3) to initialise the buffer ring before
       use. Applications may use io_uring_buf_ring_add(3) and
       io_uring_buf_ring_advance(3) or io_uring_buf_ring_cq_advance(3)
       to provide buffers, which will set these fields and update the
       tail.

       Available since 5.19.

RETURN VALUE         top

       On success io_uring_register_buf_ring(3) returns 0. On failure it
       returns -errno.

NOTES         top

       Unless manual setup is needed, it's recommended to use
       io_uring_setup_buf_ring(3) as it provides a simpler way to setup
       a provided buffer ring.

SEE ALSO         top

       io_uring_buf_ring_init(3), io_uring_buf_ring_add(3),
       io_uring_setup_buf_ring(3), io_uring_buf_ring_advance(3),
       io_uring_buf_ring_cq_advance(3)

COLOPHON         top

       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 2024-06-14.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2024-06-03.)  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.2                  May 18, 2022  io_uring_re...er_buf_ring(3)

Pages that refer to this page: io_uring_register(2)io_uring_buf_ring_add(3)io_uring_buf_ring_advance(3)io_uring_buf_ring_available(3)io_uring_buf_ring_cq_advance(3)__io_uring_buf_ring_cq_advance(3)io_uring_buf_ring_init(3)io_uring_buf_ring_mask(3)io_uring_register_buffers(3)io_uring_register_buffers_sparse(3)io_uring_register_buffers_tags(3)io_uring_register_buffers_update_tag(3)io_uring_register_buf_ring(3)io_uring_register_file_alloc_range(3)io_uring_setup_buf_ring(3)io_uring_sqe_set_flags(3)io_uring_unregister_buf_ring(3)