NAME

       io_uring_prep_fixed_fd_install - prepare fixed file fd installation request

SYNOPSIS

       #include <liburing.h>

       void io_uring_prep_fixed_fd_install(struct io_uring_sqe *sqe,
                                           int fd,
                                           unsigned int file_flags,
                                           unsigned int flags);

DESCRIPTION

       The   io_uring_prep_fixed_fd_install(3)  helper  prepares  a  fixed  file  descriptor  installation.  The
       submission queue entry sqe is setup to install the direct/fixed file descriptor  fd  with  the  specified
       file_flags  file  installation  flags,  and the flags request specific flags into the normal process file
       table.

       One use case of direct/fixed file descriptors is to turn a regular file descriptor  into  a  direct  one,
       reducing the overhead of any request that needs to access this file. This helper provides a way to go the
       other  way, turning a direct descriptor into a regular file descriptor that can then subsequently be used
       by regular system calls that take a normal file descriptor.   This  can  be  handy  if  no  regular  file
       descriptor  exists  for  this  direct  descriptor. Either because it was instantiated directly as a fixed
       descriptor, or because the regular file was closed  with  close(2)  after  being  turned  into  a  direct
       descriptor.

       Upon successful return of this request, both a normal and fixed file descriptor exists for the same file.
       Either  one  of  them may be used to access the file.  Either one of them may be closed without affecting
       the other one.

       file_flags may be either zero, or set to O_CLOEXEC to indicate  that  the  new  regular  file  descriptor
       should  be  closed  during  exec.  Setting this field to anything but those two values will result in the
       request being failed with -EINVAL in the CQE res field.

       flags is as-of yet unused and must be set to zero.

RETURN VALUE

       None

ERRORS

       The CQE res field will contain the result of the operation, which in this case will be the value  of  the
       new regular file descriptor. In case of failure, a negative value is returned.

SEE ALSO

       io_uring_get_sqe(3),    io_uring_submit(3),   io_uring_register_files(3),   io_uring_unregister_files(3),
       io_uring_prep_close_direct(3), io_uring_prep_openat_direct(3)

liburing-2.6                                    December 8, 2023               io_uring_prep_fixed_fd_install(3)