1io_uring_prep_provide_buffers(3)liburing Manualio_uring_prep_provide_buffers(3)
2
6 io_uring_prep_provide_buffers - prepare a provide buffers request
7
9 #include <liburing.h>
10 void io_uring_prep_provide_buffers(struct io_uring_sqe *sqe,
12 void *addr,
13 int len,
14 int nr,
15 int bgid,
16 int bid);
17
19 The io_uring_prep_provide_buffers(3) function prepares a request for
20 providing the kernel with buffers. The submission queue entry sqe is
21 setup to consume len number of buffers starting at addr and identified
22 by the buffer group ID of bgid and numbered sequentially starting at
23 bid.
24 This function sets up a request to provide buffers to the io_uring con‐
26 text that can be used by read or receive operations. This is done by
27 filling in the SQE buf_group field and setting IOSQE_BUFFER_SELECT in
28 the SQE flags member. If buffer selection is used for a request, no
29 buffer should be provided in the address field. Instead, the group ID
30 is set to match one that was previously provided to the kernel. The
31 kernel will then select a buffer from this group for the IO operation.
32 On successful completion of the IO request, the CQE flags field will
33 have IORING_CQE_F_BUFFER set and the selected buffer ID will be indi‐
34 cated by the upper 16-bits of the flags field.
35 Different buffer group IDs can be used by the application to have dif‐
37 ferent sizes or types of buffers available. Once a buffer has been con‐
38 sumed for an operation, it is no longer known to io_uring. It must be
39 re-provided if so desired or freed by the application if no longer
40 needed.
41 The buffer IDs are internally tracked from bid and sequentially ascend‐
43 ing from that value. If 16 buffers are provided and start with an ini‐
44 tial bid of 0, then the buffer IDs will range from 0..15. The applica‐
45 tion must be aware of this to make sense of the buffer ID passed back
46 in the CQE.
47 Not all requests support buffer selection, as it only really makes
49 sense for requests that receive data from the kernel rather than write
50 or provide data. Currently, this mode of operation is supported for
51 any file read or socket receive request. Attempting to use IOSQE_BUF‐
52 FER_SELECT with a command that doesn't support it will result in a CQE
53 res error of -EINVAL. Buffer selection will work with operations that
54 take a struct iovec as its data destination, but only if 1 iovec is
55 provided.
56
58 None
59
61 These are the errors that are reported in the CQE res field. On suc‐
62 cess, res will contain the number of successfully provided buffers. On
63 error, the following errors can occur.
64 -ENOMEM
66 The kernel was unable to allocate memory for the request.
67 -EINVAL
69 One of the fields set in the SQE was invalid.
70 -E2BIG The number of buffers provided was too big, or the bid was too
72 big. A max value of USHRT_MAX buffers can be specified.
73 -EFAULT
75 Some of the user memory given was invalid for the application.
76 -EBADF On of the descriptors located in fds didn't refer to a valid
78 file descriptor, or one of the file descriptors in the array re‐
79 ferred to an io_uring instance.
80 -EOVERFLOW
82 The product of len and nr exceed the valid amount or overflowed,
83 or the sum of addr and the length of buffers overflowed.
84 -EBUSY Attempt to update a slot that is already used.
86
88 io_uring_get_sqe(3), io_uring_submit(3), io_uring_register(2), io_ur‐
89 ing_prep_remove_buffers(3)
90liburing-2.2 March 13, 2022io_uring_prep_provide_buffers(3)