1 files changed, 131 insertions, 0 deletions
diff --git a/man/io_uring_prep_provide_buffers.3 b/man/io_uring_prep_provide_buffers.3
new file mode 100644
index 0000000..f3dded9
--- /dev/null
+++ b/man/io_uring_prep_provide_buffers.3
@@ -0,0 +1,131 @@
+.\" 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)