| .\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk> |
| .\" |
| .\" SPDX-License-Identifier: LGPL-2.0-or-later |
| .\" |
| .TH io_uring_prep_provide_buffers 3 "March 13, 2022" "liburing-2.2" "liburing Manual" |
| .SH NAME |
| io_uring_prep_provide_buffers - prepare a provide buffers request |
| .fi |
| .SH SYNOPSIS |
| .nf |
| .BR "#include <liburing.h>" |
| .PP |
| .BI "void io_uring_prep_provide_buffers(struct io_uring_sqe *" sqe "," |
| .BI " void *" addr "," |
| .BI " int " len "," |
| .BI " int " nr "," |
| .BI " int " bgid "," |
| .BI " int " bid ");" |
| .PP |
| .SH DESCRIPTION |
| .PP |
| The io_uring_prep_provide_buffers() function prepares a request for providing |
| the kernel with buffers. The submission queue entry |
| .I sqe |
| is setup to consume |
| .I len |
| number of buffers starting at |
| .I addr |
| and identified by the buffer group ID of |
| .I bgid |
| and numbered sequentially starting at |
| .I 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 |
| .I buf_group |
| field and setting |
| .B IOSQE_BUFFER_SELECT |
| in the SQE |
| .I 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 |
| .I flags |
| field will have |
| .B IORING_CQE_F_BUFFER |
| set and the selected buffer ID will be indicated by the upper 16-bits of the |
| .I 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 |
| .I bid |
| and sequentially ascending from that value. If |
| .B 16 |
| buffers are provided and start with an initial |
| .I bid |
| of 0, then the buffer IDs will range from |
| .B 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 |
| .B IOSQE_BUFFER_SELECT |
| with a command that doesn't support it will result in a CQE |
| .I res |
| error of |
| .B -EINVAL. |
| Buffer selection will work with operations that take a |
| .BR struct iovec |
| as its data destination, but only if 1 iovec is provided. |
| . |
| .SH RETURN VALUE |
| None |
| .SH ERRORS |
| These are the errors that are reported in the CQE |
| .I res |
| field. On success, |
| .I res |
| will contain the number of successfully provided buffers. On error, |
| the following errors can occur. |
| .TP |
| .B -ENOMEM |
| The kernel was unable to allocate memory for the request. |
| .TP |
| .B -EINVAL |
| One of the fields set in the SQE was invalid. |
| .TP |
| .B -E2BIG |
| The number of buffers provided was too big, or the |
| .I bid |
| was too big. A max value of |
| .B USHRT_MAX |
| buffers can be specified. |
| .TP |
| .B -EFAULT |
| Some of the user memory given was invalid for the application. |
| .TP |
| .B -EBADF |
| On of the descriptors located in |
| .I fds |
| didn't refer to a valid file descriptor, or one of the file descriptors in |
| the array referred to an io_uring instance. |
| .TP |
| .B -EOVERFLOW |
| The product of |
| .I len |
| and |
| .I nr |
| exceed the valid amount or overflowed, or the sum of |
| .I addr |
| and the length of buffers overflowed. |
| .TP |
| .B -EBUSY |
| Attempt to update a slot that is already used. |
| .SH SEE ALSO |
| .BR io_uring_get_sqe (3), io_uring_submit (3), io_uring_register (2), io_uring_prep_remove_buffers (3) |