io_uring_clone_buffers(3) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | NOTES | RETURN VALUE | SEE ALSO | COLOPHON

io_uring_clone_buffers(3)    liburing Manual    io_uring_clone_buffers(3)

NAME         top

       io_uring_clone_buffers - Clones registered buffers between rings

SYNOPSIS         top

       #include <liburing.h>

       int io_uring_clone_buffers(struct io_uring *dst,
                                  struct io_uring * src);

       int __io_uring_clone_buffers(struct io_uring *dst,
                                    struct io_uring * src,
                                    unsigned int flags);

       int io_uring_clone_buffers_offset(struct io_uring *dst,
                                         struct io_uring * src,
                                         unsigned int dst_off,
                                         unsigned int src_off,
                                         unsigned int nr,
                                         unsigned int flags);

       int __io_uring_clone_buffers_offset(struct io_uring *dst,
                                           struct io_uring * src,
                                           unsigned int dst_off,
                                           unsigned int src_off,
                                           unsigned int nr,
                                           unsigned int flags);

DESCRIPTION         top

       The io_uring_clone_buffers(3) function clones registered buffers
       from the ring indicated by src to the ring indicated by dst.  Upon
       successful completion of this operation, src and dst will have the
       same set of registered buffers. This operation is identical to
       performing a io_uring_register_buffers(3) operation on the dst
       ring, if the src ring previously had that same buffer registration
       operating done.

       The dst ring must not have any buffers currently registered. If
       buffers are currently registered on the destination ring, they
       must be unregistered with io_uring_unregister_buffers(3) first.

       For __io_uring_clone_buffers(3), the only difference is that it
       takes a flags argument. By default, if the destination ring has a
       registered file descriptor through io_uring_register_ring_fd(3)
       AND the calling application is not the thread that registered that
       ring, then the kernel doesn't know how to look up the destination.
       This is problematic as io_uring_clone_buffers(3) defaults to using
       the registered index if the destination is setup as such.  Use
       __io_uring_clone_buffers(3) which doesn't set
       IORING_REGISTER_SRC_REGISTERED by default. This requires the
       application to still have the original ring file descriptor open.
       See below for the flag definition.

       Available since kernel 6.12.

       The io_uring_clone_buffers_offset(3) function also clones buffers
       from the src ring to the dst ring, however it supports cloning
       only a subset of the buffers, where io_uring_clone_buffers(3)
       always clones all of them.  dst_off indicates at what offset
       cloning should start in the destination, src_off indicates at what
       offset cloning should start in the source, and nr indicates how
       many buffers to clone at the given offset. If both dst_off,
       src_off, and nr are given as 0 , then
       io_uring_clone_buffers_offset(3) performs the same action as
       io_uring_clone_buffers(3).

       While io_uring_clone_buffers_offset(3) sets
       IORING_REGISTER_SRC_REGISTERED by default, the
       __io_uring_clone_buffers_offset(3) does not. See the explanation
       for __io_uring_clone_buffers(3) for details.

       flags may be set to the following value:

       IORING_REGISTER_SRC_REGISTERED
              If the source ring is registered AND the calling thread is
              the one that originally registered its ring fd, then this
              flag may be set to lookup the registered index rather than
              use the normal file descriptor. If the normal file
              descriptor wasn't closed after registering it, there's no
              need to set this flag.

       IORING_REGISTER_DST_REPLACE
              If set, cloning may happen for a destination ring that
              already has a buffer table assigned. In that case, existing
              nodes that overlap with the specified range will be
              released and replaced.IORING_REGISTER_DST_REPLACE If set,
              cloning may happen for a destination ring that already has
              a buffer table assigned. In that case, existing nodes that
              overlap with the specified range will be released and
              replaced.

       Available since kernel 6.13.

NOTES         top

       The source and target ring must shared address spaces, and hence
       internal kernel accounting.

RETURN VALUE         top

       On success io_uring_clone_buffers(3) and
       io_uring_clone_buffers_offset(3) return 0.  On failure, they
       returns -errno, specifically

       -EBUSY The destination ring already has buffers registered, and
              IORING_REGISTER_DST_REPLACE wasn't set.

       -ENOMEM
              The kernel ran out of memory.

       -ENXIO The source ring doesn't have any buffers registered.

SEE ALSO         top

       io_uring_register(2), io_uring_unregister_buffers(3),
       io_uring_register_buffers(3), io_uring_prep_read_fixed(3),
       io_uring_prep_write_fixed(3)

COLOPHON         top

       This page is part of the liburing (A library for io_uring)
       project.  Information about the project can be found at 
       ⟨https://github.com/axboe/liburing⟩.  If you have a bug report for
       this manual page, send it to [email protected].  This page
       was obtained from the project's upstream Git repository
       ⟨https://github.com/axboe/liburing⟩ on 2025-08-11.  (At that time,
       the date of the most recent commit that was found in the
       repository was 2025-08-02.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there is
       a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       [email protected]

liburing-2.9                September 12, 2024  io_uring_clone_buffers(3)

Pages that refer to this page: io_uring_clone_buffers(3)io_uring_clone_buffers_offset(3)io_uring_register_buffers(3)io_uring_register_buffers_sparse(3)io_uring_register_buffers_tags(3)io_uring_register_buffers_update_tag(3)