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)