NAME

       io_uring_register_files - register file descriptors

SYNOPSIS

       #include <liburing.h>

       int io_uring_register_files(struct io_uring *ring,
                                   const int *files,
                                   unsigned nr_files);

       int io_uring_register_files_tags(struct io_uring *ring,
                                        const int *files,
                                        const __u64 *tags,
                                        unsigned nr);

       int io_uring_register_files_sparse(struct io_uring *ring,
                                          unsigned nr_files);

       int io_uring_register_files_update(struct io_uring *ring,
                                          unsigned off,
                                          const int *files,
                                          unsigned nr_files);

       int io_uring_register_files_update_tag(struct io_uring *ring,
                                          unsigned off,
                                          const int *files,
                                          const __u64 *tags,
                                          unsigned nr_files);

DESCRIPTION

       The  io_uring_register_files(3)  function  registers  nr_files  number of file descriptors
       defined by the array files belonging to the ring for subsequent operations.

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

       The io_uring_register_files_sparse(3) function registers an empty file table  of  nr_files
       number   of   file  descriptors.  These  files  must  be  updated  before  use,  using  eg
       io_uring_register_files_update_tag(3).  The sparse variant is available  in  kernels  5.19
       and later.

       Registering  a  file  table  is  a  prerequisite  for  using  any request that uses direct
       descriptors.

       Registered files have less overhead per operation than normal files. This is  due  to  the
       kernel grabbing a reference count on a file when an operation begins, and dropping it when
       it's done. When the process file table is shared, for example  if  the  process  has  ever
       created  any threads, then this cost goes up even more. Using registered files reduces the
       overhead of file reference management across requests that operate on a file.

       The io_uring_register_files_update(3) function updates existing registered files. The  off
       is offset on which to start the update nr_files number of files defined by the array files
       belonging to the ring.

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

RETURN VALUE

       On     success     io_uring_register_files(3),     io_uring_register_files_tags(3)     and
       io_uring_register_files_sparse(3)   return   0.    io_uring_register_files_update(3)   and
       io_uring_register_files_update_tag(3) return number of files  updated.   On  failure  they
       return -errno.

SEE ALSO

       io_uring_register(2), io_uring_get_sqe(3), io_uring_unregister_files(3)