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  len  number  of  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.

       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
       the number of successfully provided buffers. On error, the following errors can occur.

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

       -EBADF On of the descriptors located in fds didn't refer to a valid  file  descriptor,  or
              one of the file descriptors in the array referred to an io_uring instance.

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