132 lines
3.8 KiB
Groff
132 lines
3.8 KiB
Groff
.\" 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
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #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 ");"
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.PP
|
|
The
|
|
.BR io_uring_prep_provide_buffers (3)
|
|
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
|
|
.IR 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
|
|
.BR 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
|
|
.BR -EINVAL .
|
|
Buffer selection will work with operations that take a
|
|
.B 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),
|
|
.BR io_uring_submit (3),
|
|
.BR io_uring_register (2),
|
|
.BR io_uring_prep_remove_buffers (3)
|