# io_uring_prep_openat2_direct

## NAME



           io_uring_prep_openat2 - prepare an openat2 request
    


## SYNOPSIS



           **#include <sys/types.h>**
           **#include <sys/stat.h>**
           **#include <fcntl.h>**
           **#include <linux/openat2.h>**
           **#include <liburing.h>**
    
           **void io_uring_prep_openat2(struct io_uring_sqe ***_sqe_**,**
                                      **int** _dfd_**,**
                                      **const char ***_path_**,**
                                      **struct open_how ***_how_**);**
    
           **void io_uring_prep_openat2_direct(struct io_uring_sqe ***_sqe_**,**
                                             **int** _dfd_**,**
                                             **const char ***_path_**,**
                                             **struct open_how ***_how_**,**
                                             **unsigned** _file_index_**);**
    


## DESCRIPTION



           The io_uring_prep_openat2(3) function prepares an openat2 request.
           The submission queue entry _sqe_ is setup to use the directory file
           descriptor _dfd_ to start opening a file described by _path_ and using
           the instructions on how to open the file given in _how_.
    
           If the direct variant is used, the application must first have
           registered a file table using io_uring_register_files(3) of the
           appropriate size. Once registered, a direct request may use any
           entry in that table and is specified in _file_index_ , as long as it
           is within the size of the registered table.  If the specified
           entry already contains a file, the file will first be removed from
           the table and closed. It's consistent with the behavior of
           updating an existing file with io_uring_register_files_update(3).
    
           If **IORING_FILE_INDEX_ALLOC** is used as the _file_index_ for a direct
           open, then io_uring will allocate a free direct descriptor in the
           existing table. The allocated descriptor is returned in the CQE
           _res_ field just like it would be for a non-direct open request. If
           no more entries are available in the direct descriptor table,
           **-ENFILE** is returned instead.
    
           Direct descriptors are io_uring private file descriptors. They
           avoid some of the overhead associated with thread shared file
           tables, and can be used in any subsequent io_uring request that
           takes a file descriptor. To do so, **IOSQE_FIXED_FILE** must be set in
           the SQE _flags_ member, and the SQE _fd_ field should use the direct
           descriptor value rather than the regular file descriptor. Direct
           descriptors are managed like registered files.
    
           The directory file descriptor _dfd_ is always a regular file
           descriptor.
    
           Note that old kernels don't check the SQE _file_index_ field, which
           is not a problem for liburing helpers, but users of the raw
           io_uring interface need to zero SQEs to avoid unexpected behavior.
    
           These functions prepare an async openat2(2) request. See that man
           page for details.
    


## RETURN VALUE



           None
    


## ERRORS



           The CQE _res_ field will contain the result of the operation. See
           the related man page for details on possible values. Note that
           where synchronous system calls will return **-1** on failure and set
           _errno_ to the actual error value, io_uring never uses _errno_.
           Instead it returns the negated _errno_ directly in the CQE _res_
           field.
    


## NOTES



           As with any request that passes in data in a struct, that data
           must remain valid until the request has been successfully
           submitted. It need not remain valid until completion. Once a
           request has been submitted, the in-kernel state is stable. Very
           early kernels (5.4 and earlier) required state to be stable until
           the completion occurred. Applications can test for this behavior
           by inspecting the **IORING_FEAT_SUBMIT_STABLE** flag passed back from
           io_uring_queue_init_params(3).
    


* * *