# io_uring_prep_provide_buffers

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


* * *