NAME

       io_uring_prep_provide_buffers - prepare a provide buffers request

SYNOPSIS

       #include <liburing.h>

       void io_uring_prep_provide_buffers(struct io_uring_sqe *sqe,
                                          void *addr,
                                          int len,
                                          int nr,
                                          int bgid,
                                          int bid);

DESCRIPTION

       The  io_uring_prep_provide_buffers(3)  function prepares a request for providing the kernel with buffers.
       The submission queue entry sqe is setup to consume nr number of len sized buffers starting  at  addr  and
       identified by the buffer group ID of bgid and numbered sequentially starting at bid.

       This  function  sets  up a request to provide buffers to the io_uring context that can be used by read or
       receive operations. This is done by filling in the SQE buf_group field and setting IOSQE_BUFFER_SELECT in
       the  SQE  flags  member.  If  buffer selection is used for a request, no buffer should be provided in the
       address field. Instead, the group ID is set to match one that was previously provided to the kernel.  The
       kernel will then select a buffer from this group for the IO operation. On successful completion of the IO
       request, the CQE flags field will have IORING_CQE_F_BUFFER  set  and  the  selected  buffer  ID  will  be
       indicated by the upper 16-bits of the flags field.

       Different  buffer  group  IDs  can be used by the application to have different sizes or types of buffers
       available. Once a buffer has been consumed for an operation, it is no longer known to io_uring.  It  must
       be re-provided if so desired or freed by the application if no longer needed.

       The  buffer IDs are internally tracked from bid and sequentially ascending from that value. If 16 buffers
       are provided and start with an initial bid of 0,  then  the  buffer  IDs  will  range  from  0..15.   The
       application must be aware of this to make sense of the buffer ID passed back in the CQE.

       Buffer  IDs  always  range  from 0 to 65535 , as there are only 16-bits available in the CQE to pass them
       back. This range is independent of how the buffer group initially got created. Attempting to  add  buffer
       IDs larger than that, or buffer IDs that will wrap when cast to a 16-bit value, will cause the request to
       fail with -E2BIG or -EINVAL .

       Not all requests support buffer selection, as it only really makes sense for requests that  receive  data
       from  the  kernel  rather than write or provide data.  Currently, this mode of operation is supported for
       any file read or socket receive request. Attempting  to  use  IOSQE_BUFFER_SELECT  with  a  command  that
       doesn't support it will result in a CQE res error of -EINVAL.  Buffer selection will work with operations
       that take a struct iovec as its data destination, but only if 1 iovec is provided.

RETURN VALUE

       None

ERRORS

       These are the errors that are reported in the CQE res field. On success, res will contain 0 or the number
       of successfully provided buffers.

       -ENOMEM
              The kernel was unable to allocate memory for the request.

       -EINVAL
              One of the fields set in the SQE was invalid.

       -E2BIG The  number  of  buffers  provided  was  too big, or the bid was too big. A max value of USHRT_MAX
              buffers can be specified.

       -EFAULT
              Some of the user memory given was invalid for the application.

       -EOVERFLOW
              The product of len and nr exceed the valid amount or overflowed, or the sum of addr and the length
              of buffers overflowed.

       -EBUSY Attempt to update a slot that is already used.

SEE ALSO

       io_uring_get_sqe(3), io_uring_submit(3), io_uring_register(2), io_uring_prep_remove_buffers(3)