1io_uring_register_buffers(3)    liburing Manual   io_uring_register_buffers(3)
2
3
4

NAME

6       io_uring_register_buffers  -  register  buffers for fixed buffer opera‐
7       tions
8

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

SEE ALSO

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)
Impressum