plucky (3) io_uring_setup_buf_ring.3.gz

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

       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

       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

       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)