[PATCH liburing 1/1] man: clarifications about direct open/accept

[PATCH liburing 1/1] man: clarifications about direct open/accept

[Pavel Begunkov]

Direct open/accept replaces files for slots that are taken, so it's not
necessary to use sparse file tables. Update on that, mention the
replacing mechanism, and add a note about possible compitability issues
for raw io_uring API users.

Signed-off-by: Pavel Begunkov <asml.silence@gmail.com>
---
 man/io_uring_prep_accept.3  | 17 +++++++++++------
 man/io_uring_prep_openat.3  | 17 +++++++++++------
 man/io_uring_prep_openat2.3 | 17 +++++++++++------
 3 files changed, 33 insertions(+), 18 deletions(-)

diff --git a/man/io_uring_prep_accept.3 b/man/io_uring_prep_accept.3
index 0fa2466..2942619 100644
--- a/man/io_uring_prep_accept.3
+++ b/man/io_uring_prep_accept.3
@@ -52,13 +52,18 @@ field should use the direct descriptor value rather than the regular file
 descriptor. Direct descriptors are managed like registered files.
 
 If the direct variant is used, the application must first have registered
-a sparse file table using
+a file table using
 .BR io_uring_register_files (3)
-of the appropriate size. A sparse table is one where each element is first
-registered with a value of
-.B -1.
-Once registered, a direct accept request may use any sparse entry in that
-table, as long as it is within the size of the registered table.
+of the appropriate size. Once registered, a direct accept request may use any
+entry in that table, as long as it is within the size of the registered table.
+If a specified entry already contains a file, the file will first be removed
+from the table. It's consistent with the behavior of updating an existing
+file with
+.BR io_uring_register_files_update(3).
+Note that old kernels don't check the SQE
+.I 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.
 
 This function prepares an async
 .BR accept4 (2)
diff --git a/man/io_uring_prep_openat.3 b/man/io_uring_prep_openat.3
index c5710be..b34a6aa 100644
--- a/man/io_uring_prep_openat.3
+++ b/man/io_uring_prep_openat.3
@@ -54,13 +54,18 @@ field should use the direct descriptor value rather than the regular file
 descriptor. Direct descriptors are managed like registered files.
 
 If the direct variant is used, the application must first have registered
-a sparse file table using
+a file table using
 .BR io_uring_register_files (3)
-of the appropriate size. A sparse table is one where each element is first
-registered with a value of
-.B -1.
-Once registered, a direct open request may use any sparse entry in that
-table, as long as it is within the size of the registered table.
+of the appropriate size. Once registered, a direct accept request may use any
+entry in that table, as long as it is within the size of the registered table.
+If a specified entry already contains a file, the file will first be removed
+from the table. It's consistent with the behavior of updating an existing
+file with
+.BR io_uring_register_files_update(3).
+Note that old kernels don't check the SQE
+.I 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.
 
 This function prepares an async
 .BR openat (2)
diff --git a/man/io_uring_prep_openat2.3 b/man/io_uring_prep_openat2.3
index 672fd7c..a985ff1 100644
--- a/man/io_uring_prep_openat2.3
+++ b/man/io_uring_prep_openat2.3
@@ -55,13 +55,18 @@ field should use the direct descriptor value rather than the regular file
 descriptor. Direct descriptors are managed like registered files.
 
 If the direct variant is used, the application must first have registered
-a sparse file table using
+a file table using
 .BR io_uring_register_files (3)
-of the appropriate size. A sparse table is one where each element is first
-registered with a value of
-.B -1.
-Once registered, a direct open request may use any sparse entry in that
-table, as long as it is within the size of the registered table.
+of the appropriate size. Once registered, a direct accept request may use any
+entry in that table, as long as it is within the size of the registered table.
+If a specified entry already contains a file, the file will first be removed
+from the table. It's consistent with the behavior of updating an existing
+file with
+.BR io_uring_register_files_update(3).
+Note that old kernels don't check the SQE
+.I 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.
 
 This function prepares an async
 .BR openat2 (2)
-- 
2.35.1