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 *ret);

DESCRIPTION

       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.  bgid is the chosen buffer  group  ID,  flags  are  modifier
       flags for the operation, and *ret is is a pointer to an integer for the error value if any
       part of the ring allocation and registration fails.

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

       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

       On success io_uring_setup_buf_ring(3) returns a pointer to the buffer ring. On failure  it
       returns NULL and sets *ret to -errno.

NOTES

       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

       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)