NAME

       io_uring_prep_files_update - prepare a registered file update request

SYNOPSIS

       #include <liburing.h>

       void io_uring_prep_files_update(struct io_uring_sqe *sqe,
                                       int *fds,
                                       unsigned nr_fds,
                                       int offset);

DESCRIPTION

       The  io_uring_prep_files_update(3)  function  prepares  a request for updating a number of
       previously registered file descriptors. The submission queue entry sqe is setup to use the
       file  descriptor  array pointed to by fds and of nr_fds in length to update that amount of
       previously registered files starting at offset offset.

       Once a previously registered file is updated with a new one, the existing entry is updated
       and  then removed from the table. This operation is equivalent to first unregistering that
       entry and then inserting a new one, just bundled into one combined operation.

       If offset is specified as IORING_FILE_INDEX_ALLOC,  io_uring  will  allocate  free  direct
       descriptors  instead  of  having  the  application  to  pass,  and  store allocated direct
       descriptors into fds  array,  cqe->res  will  return  the  number  of  direct  descriptors
       allocated.

RETURN VALUE

       None

ERRORS

       These  are the errors that are reported in the CQE res field. On success, res will contain
       the number of successfully updated file descriptors. On error, the  following  errors  can
       occur.

       -ENOMEM
              The kernel was unable to allocate memory for the request.

       -EINVAL
              One of the fields set in the SQE was invalid.

       -EFAULT
              The kernel was unable to copy in the memory pointed to by fds.

       -EBADF On  of  the  descriptors located in fds didn't refer to a valid file descriptor, or
              one of the file descriptors in the array referred to an io_uring instance.

       -EOVERFLOW
              The product of offset and nr_fds exceed the valid amount or overflowed.

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).

SEE ALSO

       io_uring_get_sqe(3), io_uring_submit(3), io_uring_register(2)