1io_uring_prep_files_update(3)   liburing Manual  io_uring_prep_files_update(3)
2
3
4

NAME

6       io_uring_prep_files_update - prepare a registered file update request
7

SYNOPSIS

9       #include <liburing.h>
10
11       void io_uring_prep_files_update(struct io_uring_sqe *sqe,
12                                       int *fds,
13                                       unsigned nr_fds,
14                                       int offset);
15

DESCRIPTION

17       The  io_uring_prep_files_update(3)  function prepares a request for up‐
18       dating a number of previously registered file descriptors. The  submis‐
19       sion  queue entry sqe is setup to use the file descriptor array pointed
20       to by fds and of nr_fds in length to update that amount  of  previously
21       registered files starting at offset offset.
22
23       Once a previously registered file is updated with a new one, the exist‐
24       ing entry is updated and then removed from the table. This operation is
25       equivalent  to  first unregistering that entry and then inserting a new
26       one, just bundled into one combined operation.
27
28       If offset is specified as IORING_FILE_INDEX_ALLOC, io_uring will  allo‐
29       cate free direct descriptors instead of having the application to pass,
30       and store allocated direct descriptors into fds  array,  cqe->res  will
31       return the number of direct descriptors allocated.
32
33

RETURN VALUE

35       None
36

ERRORS

38       These  are  the  errors that are reported in the CQE res field. On suc‐
39       cess, res will contain the number of successfully updated file descrip‐
40       tors. On error, the following errors can occur.
41
42       -ENOMEM
43              The kernel was unable to allocate memory for the request.
44
45       -EINVAL
46              One of the fields set in the SQE was invalid.
47
48       -EFAULT
49              The kernel was unable to copy in the memory pointed to by fds.
50
51       -EBADF On  of  the  descriptors  located in fds didn't refer to a valid
52              file descriptor, or one of the file descriptors in the array re‐
53              ferred to an io_uring instance.
54
55       -EOVERFLOW
56              The  product  of  offset  and  nr_fds exceed the valid amount or
57              overflowed.
58

NOTES

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

SEE ALSO

69       io_uring_get_sqe(3), io_uring_submit(3), io_uring_register(2)
70
71
72
73liburing-2.2                    March 13, 2022   io_uring_prep_files_update(3)
Impressum