public inbox for [email protected]
 help / color / mirror / Atom feed
* [PATCH liburing 1/1] man: clarifications about direct open/accept
@ 2022-03-17 15:23 Pavel Begunkov
  2022-03-18  2:40 ` Jens Axboe
  0 siblings, 1 reply; 2+ messages in thread
From: Pavel Begunkov @ 2022-03-17 15:23 UTC (permalink / raw)
  To: io-uring; +Cc: Jens Axboe, asml.silence

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 <[email protected]>
---
 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


^ permalink raw reply related	[flat|nested] 2+ messages in thread

end of thread, other threads:[~2022-03-18  2:41 UTC | newest]

Thread overview: 2+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2022-03-17 15:23 [PATCH liburing 1/1] man: clarifications about direct open/accept Pavel Begunkov
2022-03-18  2:40 ` Jens Axboe

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox