io_uring_setup_buf_ring(3) — Linux manual page

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

io_uring_setup_buf_ring(3)   liburing Manual   io_uring_setup_buf_ring(3)

NAME         top

       io_uring_setup_buf_ring - setup and register buffer ring for
       provided buffers

SYNOPSIS         top

       #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         top

       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 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 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.

RETURN VALUE         top

       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         top

       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.

SEE ALSO         top

       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)

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 2025-02-02.  (At that time,
       the date of the most recent commit that was found in the
       repository was 2025-01-22.)  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)