io_uring_prep_provide_buffers(3) — Linux manual page

io_uring_p...ide_buffers(3)  liburing Manual io_uring_p...ide_buffers(3)

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)

COLOPHON

       This page is part of the liburing (A library for io_uring)
       project.  Information about the project can be found at 
       ⟨https://github.com/axboe/liburing⟩.  If you have a bug report for
       this manual page, send it to io-uring@vger.kernel.org.  This page
       was obtained from the project's upstream Git repository
       ⟨https://github.com/axboe/liburing⟩ on 2024-06-14.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2024-06-03.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

liburing-2.2                 March 13, 2022  io_uring_p...ide_buffers(3)

Pages that refer to this page: io_uring_prep_provide_buffers(3), io_uring_prep_remove_buffers(3)

---