|
HTML rendering created 2023-12-22 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | SEE ALSO | COLOPHON |
|
|
|
io_uring_p...ide_buffers(3) liburing Manual io_uring_p...ide_buffers(3)
io_uring_prep_provide_buffers - prepare a provide buffers request
#include <liburing.h>
void io_uring_prep_provide_buffers(struct io_uring_sqe *sqe,
void *addr,
int len,
int nr,
int bgid,
int bid);
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.
None
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.
io_uring_get_sqe(3), io_uring_submit(3), io_uring_register(2),
io_uring_prep_remove_buffers(3)
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 2023-12-22. (At that
time, the date of the most recent commit that was found in the
repository was 2023-12-19.) 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)
|
HTML rendering created 2023-12-22 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|