From d7c02c9a396cfba5cfa9ffe9b113cb7428096766 Mon Sep 17 00:00:00 2001 From: Andrew Consroe Date: Wed, 2 Oct 2024 11:52:16 -0500 Subject: [PATCH] man/prep_openat{2}: clarify IOSQE_FIXED_FILE minor rearrangement & split of pargraph clarify that IOSQE_FIXED_FILE is for subsequent sqe, not this one note that dfd is always a regular file descriptor Signed-off-by: Andrew Consroe --- man/io_uring_prep_openat.3 | 41 ++++++++++++++++++--------------- man/io_uring_prep_openat2.3 | 46 +++++++++++++++++++++---------------- 2 files changed, 49 insertions(+), 38 deletions(-) diff --git a/man/io_uring_prep_openat.3 b/man/io_uring_prep_openat.3 index d717b6cfa..071a9f832 100644 --- a/man/io_uring_prep_openat.3 +++ b/man/io_uring_prep_openat.3 @@ -54,32 +54,17 @@ Similarly .BR io_uring_prep_open (3) prepares an open request. -For a direct descriptor open request, the offset is specified by the -.I file_index -argument. Direct descriptors are io_uring private file descriptors. They -avoid some of the overhead associated with thread shared file tables, and -can be used in any io_uring request that takes a file descriptor. To do so, -.B IOSQE_FIXED_FILE -must be set in the SQE -.I flags -member, and the SQE -.I fd -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 file table using .BR io_uring_register_files (3) 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. +entry in that table and is specified in +.I file_index +, 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 and closed. 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. If .B IORING_FILE_INDEX_ALLOC @@ -93,6 +78,26 @@ are available in the direct descriptor table, .B -ENFILE is returned instead. +Direct descriptors are io_uring private file descriptors. They +avoid some of the overhead associated with thread shared file tables, and +can be used in any subsequent io_uring request that takes a file descriptor. To do so, +.B IOSQE_FIXED_FILE +must be set in the SQE +.I flags +member, and the SQE +.I fd +field should use the direct descriptor value rather than the regular file +descriptor. Direct descriptors are managed like registered files. + +The directory file descriptor +.I dfd +is always a regular file descriptor. + +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. + These functions prepare an async .BR openat (2) or diff --git a/man/io_uring_prep_openat2.3 b/man/io_uring_prep_openat2.3 index 338cf7eaa..109c381e1 100644 --- a/man/io_uring_prep_openat2.3 +++ b/man/io_uring_prep_openat2.3 @@ -41,32 +41,18 @@ and using the open flags in and using the instructions on how to open the file given in .IR how . -For a direct descriptor open request, the offset is specified by the -.I file_index -argument. Direct descriptors are io_uring private file descriptors. They -avoid some of the overhead associated with thread shared file tables, and -can be used in any io_uring request that takes a file descriptor. To do so, -.B IOSQE_FIXED_FILE -must be set in the SQE -.I flags -member, and the SQE -.I fd -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 file table using .BR io_uring_register_files (3) -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 +of the appropriate size. Once registered, a direct request may use any +entry in that table and is specified in +.I file_index +, as long as it is within the size of the registered table. +If the specified entry already contains a file, the file will first be removed from the table and closed. 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. + If .B IORING_FILE_INDEX_ALLOC is used as the @@ -79,6 +65,26 @@ are available in the direct descriptor table, .B -ENFILE is returned instead. +Direct descriptors are io_uring private file descriptors. They +avoid some of the overhead associated with thread shared file tables, and +can be used in any subsequent io_uring request that takes a file descriptor. To do so, +.B IOSQE_FIXED_FILE +must be set in the SQE +.I flags +member, and the SQE +.I fd +field should use the direct descriptor value rather than the regular file +descriptor. Direct descriptors are managed like registered files. + +The directory file descriptor +.I dfd +is always a regular file descriptor. + +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. + These functions prepare an async .BR openat2 (2) request. See that man page for details.