NAME

       io_uring_register_buffers - register buffers for fixed buffer operations

SYNOPSIS

       #include <liburing.h>

       int io_uring_register_buffers(struct io_uring *ring,
                                     const struct iovec *iovecs,
                                     unsigned nr_iovecs);

       int io_uring_register_buffers_tags(struct io_uring *ring,
                                          const struct iovec *iovecs,
                                          const __u64 *tags,
                                          unsigned nr);

       int io_uring_register_buffers_sparse(struct io_uring *ring,
                                            unsigned nr_iovecs);

       int io_uring_register_buffers_update_tag(struct io_uring *ring,
                                                unsigned off,
                                                const struct iovec *iovecs,
                                                const __u64 *tags,
                                                unsigned nr);

DESCRIPTION

       The io_uring_register_buffers(3) function registers nr_iovecs number of buffers defined by
       the array iovecs belonging to the ring.

       The     io_uring_register_buffers_tags(3)     function     behaves     the     same     as
       io_uring_register_buffers(3)   function   but   additionally  takes  tags  parameter.  See
       IORING_REGISTER_BUFFERS2 for the resource tagging description.

       The  io_uring_register_buffers_sparse(3)  function  registers  nr_iovecs   empty   buffers
       belonging   to   the   ring.    These  buffers  must  be  updated  before  use,  using  eg
       io_uring_register_buffers_update_tag(3).

       After the caller has registered the buffers, they can  be  used  with  one  of  the  fixed
       buffers functions.

       Registered  buffers  is  an optimization that is useful in conjunction with O_DIRECT reads
       and writes, where it maps the specified range into the kernel  once  when  the  buffer  is
       registered  rather  than  doing  a map and unmap for each IO every time IO is performed to
       that region. Additionally, it also avoids manipulating the page reference counts for  each
       IO.

       The  io_uring_register_buffers_update_tag(3)  function updates registered buffers with new
       ones, either turning a sparse entry into a real one, or replacing an existing  entry.  The
       off  is  offset  on  which  to  start the update nr number of buffers defined by the array
       iovecs  belonging  to  the  ring.   The  tags  points   to   an   array   of   tags.   See
       IORING_REGISTER_BUFFERS2 for the resource tagging description.

RETURN VALUE

       On    success    io_uring_register_buffers(3),    io_uring_register_buffers_tags(3)    and
       io_uring_register_buffers_sparse(3)  return  0.    io_uring_register_buffers_update_tag(3)
       return number of buffers updated.  On failure they return -errno.

SEE ALSO

       io_uring_register(2),         io_uring_get_sqe(3),         io_uring_unregister_buffers(3),
       io_uring_register_buf_ring(3), io_uring_prep_read_fixed(3), io_uring_prep_write_fixed(3)