liburing updates for 2.4
cover liburing updates for 2.4
From: Ammar Faizi <[email protected]>
Hi Jens,
I have found two people confused about the io_uring_prep_splice() function, especially on the offset part. The current manpage for io_uring_prep_splice() doesn't tell about the rules of the offset arguments.
Despite these rules are already noted in "man 2 io_uring_enter", people who want to know about this prep function will prefer to read "man 3 io_uring_prep_splice". Let's explain it there.
Additionally, this series also contains:
- Fix a typo: 's/is adjust/is adjusted/' and indentation in liburing.h.
- Add io_uring_prep_msg_ring_cqe_flags() to liburing-ffi.map. Commit 27180d7be059 ("Add io_uring_prep_msg_ring_cqe_flags function") adds a new inline function in liburing.h, but it doesn't update the liburing-ffi.map file. Update it.
- Note about --nolibc configure option deprecation in the CHANGELOG. Since commit bfb432f4cce5 ("configure: Always enable CONFIG_NOLIBC if the arch is supported"), the --nolibc configure option is deprecated and has no effect. Plus, building liburing on x86-64, x86, and aarch64 always enables CONFIG_NOLIBC. Note these changes in the CHANGELOG file.
---
Ammar Faizi (4):
liburing-ffi.map: Add io_uring_prep_msg_ring_cqe_flags() function
CHANGELOG: Note about --nolibc configure option deprecation liburing.h: 's/is adjust/is adjusted/' and fix indentation man/io_uring_prep_splice.3: Explain more about io_uring_prep_splice()
CHANGELOG | 2 ++ man/io_uring_prep_splice.3 | 38 ++++++++++++++++++++++++++++++++++++++ src/include/liburing.h | 4 ++-- src/liburing-ffi.map | 1 + 4 files changed, 43 insertions(+), 2 deletions(-)
base-commit: 47679a9019e48bf4293a4f55adade9eae715f9e4
Signature · 1 line
Ammar Faizi
PATCH 1/4 liburing-ffi.map: Add io_uring_prep_msg_ring_cqe_flags() function
From: Ammar Faizi <[email protected]>
Commit 27180d7be059 ("Add io_uring_prep_msg_ring_cqe_flags function") adds a new inline function in liburing.h, but it doesn't update the liburing-ffi.map file. Update it.
--- src/liburing-ffi.map | 1 + 1 file changed, 1 insertion(+)
src/liburing-ffi.map +1 -0
@@ -164,6 +164,7 @@ LIBURING_2.4 { io_uring_register_restrictions; io_uring_prep_write; io_uring_prep_recv; + io_uring_prep_msg_ring_cqe_flags; local: *; };
Signature · 1 line
Ammar Faizi
PATCH 2/4 CHANGELOG: Note about --nolibc configure option deprecation
In reply to Ammar FaiziFrom: Ammar Faizi <[email protected]>
Since commit bfb432f4cce5 ("configure: Always enable CONFIG_NOLIBC if the arch is supported"), the --nolibc configure option is deprecated and has no effect. Plus, building liburing on x86-64, x86, and aarch64 always enables CONFIG_NOLIBC. Note these changes in the CHANGELOG file.
--- CHANGELOG | 2 ++ 1 file changed, 2 insertions(+)
CHANGELOG +2 -0
@@ -4,6 +4,8 @@ liburing-2.4 release - Add IO_URING_{MAJOR,MINOR,CHECK}_VERSION() macros. - FFI support (for non-C/C++ languages integration). - Add io_uring_prep_msg_ring_cqe_flags() function. +- Deprecate --nolibc configure option. +- CONFIG_NOLIBC is always enabled on x86-64, x86, and aarch64. liburing-2.3 release
Signature · 1 line
Ammar Faizi
PATCH 3/4 liburing.h: 's/is adjust/is adjusted/' and fix indentation
In reply to Ammar FaiziFrom: Ammar Faizi <[email protected]>
- Fix a typo: 's/is adjust/is adjusted/'.
- Fix indentation.
--- src/include/liburing.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
src/include/liburing.h +2 -2
@@ -388,8 +388,8 @@ IOURINGINLINE void io_uring_prep_rw(int op, struct io_uring_sqe *sqe, int fd,* @param off_in If fd_in refers to a pipe, off_in must be (int64_t) -1; * If fd_in does not refer to a pipe and off_in is (int64_t) -1, * then bytes are read from fd_in starting from the file offset -* and it is adjust appropriately; -* If fd_in does not refer to a pipe and off_in is not +* and it is adjusted appropriately; +* If fd_in does not refer to a pipe and off_in is not * (int64_t) -1, then the starting offset of fd_in will be * off_in. * @param off_out The description of off_in also applied to off_out.
Signature · 1 line
Ammar Faizi
PATCH 4/4 man/io_uring_prep_splice.3: Explain more about io_uring_prep_splice()
In reply to Ammar FaiziFrom: Ammar Faizi <[email protected]>
I have found two people confused about the io_uring_prep_splice() function, especially on the offset part. The current manpage for io_uring_prep_splice() doesn't tell about the rules of the offset arguments.
Despite these rules are already noted in "man 2 io_uring_enter", people who want to know about this prep function will prefer to read "man 3 io_uring_prep_splice".
Let's explain it there!
---
Stolen from liburing comment (with some modifications):
If fd_in refers to a pipe, off_in must be -1.
If fd_in does not refer to a pipe and off_in is -1, then bytes are read from fd_in starting from the file offset and it is adjusted appropriately.
If fd_in does not refer to a pipe and off_in is not -1, then the starting offset of fd_in will be off_in.
The same rules apply to fd_out and off_out.
Note that even if fd_in or fd_out refers to a pipe, the splice operation can still failed with EINVAL if one of the fd doesn't explicitly support splice operation, e.g. reading from terminal is unsupported from kernel 5.7 to 5.11.
man/io_uring_prep_splice.3 | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+)
man/io_uring_prep_splice.3 +38 -0
@@ -52,6 +52,34 @@ and .I fd_in given as a registered file descriptor offset. +If +.I fd_in +refers to a pipe, +.IR off_in +must be -1. + +If +.I fd_in +does not refer to a pipe and +.I off_in +is -1, then bytes are read from +.I fd_in +starting from the file offset and it is adjusted appropriately. + +If +.I fd_in +does not refer to a pipe and +.I off_in +is not -1, then the starting offset of +.I fd_in +will be +.IR off_in . + +The same rules apply to +.I fd_out +and +.IR off_out . + This function prepares an async .BR splice (2) request. See that man page for details.
@@ -78,3 +106,13 @@ field. .BR io_uring_submit (3), .BR io_uring_register (2), .BR splice (2) + +.SH NOTES +Note that even if +.I fd_in +or +.I fd_out +refers to a pipe, the splice operation can still failed with +.B EINVAL +if one of the fd doesn't explicitly support splice operation, e.g. reading from +terminal is unsupported from kernel 5.7 to 5.11.
Signature · 1 line
Ammar Faizi
Re: [PATCH liburing v1 4/4] man/io_uring_prep_splice.3: Explain more about io_uring_prep_splice()
Quoted 7 lines · Ammar Faizi
From: Ammar Faizi <[email protected]>
I have found two people confused about the
io_uring_prep_splice()function, especially on the offset part. The current manpage forio_uring_prep_splice()doesn't tell about the rules of the offset arguments.
Quoted 5 lines
Despite these rules are already noted in "man 2
io_uring_enter", people who want to know about this prep function will prefer to read "man 3io_uring_prep_splice".Let's explain it there!
Hi Ammar,
A few suggestions below:
man/io_uring_prep_splice.3 and · line 59
Quoted 11 lines
man/io_uring_prep_splice.3 +5
-0@@ -52,6 +52,34 @@ and .I fd_in given as a registered file descriptor offset. +If +.I fd_in +refers to a pipe, +.IR off_in +must be -1.
Maybe
"off_in is ignored and must be set to -1."
man/io_uring_prep_splice.3 and · line 65
Quoted 6 lines
man/io_uring_prep_splice.3 +6
-0+ +If +.I fd_in +does not refer to a pipe and +.I off_in +is -1, then bytes are read from
bytes -> nbytes ?
man/io_uring_prep_splice.3 and · line 67
Quoted 2 lines
man/io_uring_prep_splice.3 +2
-0+.I fd_in +starting from the file offset and it is adjusted appropriately.
What do you think:
starting from the file offset, which is incremented by the number of bytes read.
Quoted 18 lines
man/io_uring_prep_splice.3 +14
-0+If +.I fd_in +does not refer to a pipe and +.I off_in +is not -1, then the starting offset of +.I fd_in +will be +.IR off_in . + +The same rules apply to +.I fd_out +and +.IR off_out . + This function prepares an async .BR splice (2) request. See that man page for details.
man/io_uring_prep_splice.3 field. · line 115
Quoted 10 lines
man/io_uring_prep_splice.3 +7
-0@@ -78,3 +106,13 @@ field. .BR io_uring_submit (3), .BR io_uring_register (2), .BR splice (2) + +.SH NOTES +Note that even if +.I fd_in +or +.I fd_out +refers to a pipe, the splice operation can still failed with
failed -> fail
Thanks,
Signature · 1 line
Gabriel Krisman Bertazi
Jens Axboe
maintainerRe: [PATCH liburing v1 4/4] man/io_uring_prep_splice.3: Explain more about io_uring_prep_splice()
Quoted 13 lines · Gabriel Krisman Bertazi
Quoted 11 lines · Ammar Faizi
From: Ammar Faizi <[email protected]>
I have found two people confused about the
io_uring_prep_splice()function, especially on the offset part. The current manpage forio_uring_prep_splice()doesn't tell about the rules of the offset arguments.Despite these rules are already noted in "man 2
io_uring_enter", people who want to know about this prep function will prefer to read "man 3io_uring_prep_splice".
Quoted 5 lines
Quoted 1 line
Let's explain it there!
Hi Ammar,
A few suggestions below:
[snip]
Shoot, missed this. Ammar, can you send a fixup patch with the below suggestions?
Signature · 1 line
Jens Axboe
Quoted 10 lines · Ammar Faizi
I have found two people confused about the
io_uring_prep_splice()function, especially on the offset part. The current manpage forio_uring_prep_splice()doesn't tell about the rules of the offset arguments.Despite these rules are already noted in "man 2
io_uring_enter", people who want to know about this prep function will prefer to read "man 3io_uring_prep_splice". Let's explain it there.[...]
Applied, thanks!
[1/4] liburing-ffi.map: Add io_uring_prep_msg_ring_cqe_flags() function
commit: 390b4f6a1314f8b1c51ced51c70b8646a51ad081
[2/4] CHANGELOG: Note about --nolibc configure option deprecation
commit: 68c2a983819edae4e724b49b2e644767684eb103
[3/4] liburing.h: 's/is adjust/is adjusted/' and fix indentation
commit: f63a594cbc58bb0f680e7d424f2d8f836142aa35
[4/4] man/io_uring_prep_splice.3: Explain more about io_uring_prep_splice()
commit: 55bbe5b71c7d39c9ea44e5abb886846010c67baaBest regards,
Signature · 1 line
Jens Axboe