# io_uring_register_files_sparse

## 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).  Note that if the size of
           the sparse table exceeds what **RLIMIT_NOFILE** allows, then
           io_uring_register_files_sparse(3) will attempt to raise the limit
           using setrlimit(2) and retry the operation. If the registration
           fails after doing that, then an error will be returned.  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**.
    


* * *