1io_uring_register_buffers(3) liburing Manual io_uring_register_buffers(3)
2
3
4
6 io_uring_register_buffers - register buffers for fixed buffer opera‐
7 tions
8
10 #include <liburing.h>
11
12 int io_uring_register_buffers(struct io_uring *ring,
13 const struct iovec *iovecs,
14 unsigned nr_iovecs);
15
16 int io_uring_register_buffers_tags(struct io_uring *ring,
17 const struct iovec *iovecs,
18 const __u64 *tags,
19 unsigned nr);
20
21 int io_uring_register_buffers_sparse(struct io_uring *ring,
22 unsigned nr_iovecs);
23
24 int io_uring_register_buffers_update_tag(struct io_uring *ring,
25 unsigned off,
26 const struct iovec *iovecs,
27 const __u64 *tags,
28 unsigned nr);
29
31 The io_uring_register_buffers(3) function registers nr_iovecs number of
32 buffers defined by the array iovecs belonging to the ring.
33
34 The io_uring_register_buffers_tags(3) function behaves the same as
35 io_uring_register_buffers(3) function but additionally takes tags pa‐
36 rameter. See IORING_REGISTER_BUFFERS2 for the resource tagging descrip‐
37 tion.
38
39 The io_uring_register_buffers_sparse(3) function registers nr_iovecs
40 empty buffers belonging to the ring. These buffers must be updated be‐
41 fore use, using eg io_uring_register_buffers_update_tag(3).
42
43 After the caller has registered the buffers, they can be used with one
44 of the fixed buffers functions.
45
46 Registered buffers is an optimization that is useful in conjunction
47 with O_DIRECT reads and writes, where it maps the specified range into
48 the kernel once when the buffer is registered rather than doing a map
49 and unmap for each IO every time IO is performed to that region. Addi‐
50 tionally, it also avoids manipulating the page reference counts for
51 each IO.
52
53 The io_uring_register_buffers_update_tag(3) function updates registered
54 buffers with new ones, either turning a sparse entry into a real one,
55 or replacing an existing entry. The off is offset on which to start the
56 update nr number of buffers defined by the array iovecs belonging to
57 the ring. The tags points to an array of tags. See IORING_REGIS‐
58 TER_BUFFERS2 for the resource tagging description.
59
60
62 On success io_uring_register_buffers(3), io_uring_register_buf‐
63 fers_tags(3) and io_uring_register_buffers_sparse(3) return 0. io_ur‐
64 ing_register_buffers_update_tag(3) return number of buffers updated.
65 On failure they return -errno.
66
68 io_uring_register(2), io_uring_get_sqe(3), io_uring_unregister_buf‐
69 fers(3), io_uring_register_buf_ring(3), io_uring_prep_read_fixed(3),
70 io_uring_prep_write_fixed(3)
71
72
73
74liburing-2.1 November 15, 2021 io_uring_register_buffers(3)