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.
Signed-off-by: Ammar Faizi <[email protected]>
---
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
--
Ammar Faizi
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.
Cc: Breno Leitao <[email protected]>
Cc: Christian Mazakas <[email protected]>
Fixes: 27180d7be059 ("Add io_uring_prep_msg_ring_cqe_flags function")
Signed-off-by: Ammar Faizi <[email protected]>
---
src/liburing-ffi.map | 1 +
1 file changed, 1 insertion(+)
diff --git a/src/liburing-ffi.map b/src/liburing-ffi.map
index 8dd4641..1a6df50 100644
--- a/src/liburing-ffi.map
+++ b/src/liburing-ffi.map
@@ -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:
*;
};
--
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 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!
Signed-off-by: Ammar Faizi <[email protected]>
---
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(+)
diff --git a/man/io_uring_prep_splice.3 b/man/io_uring_prep_splice.3
index cb82ad0..a177bc6 100644
--- a/man/io_uring_prep_splice.3
+++ b/man/io_uring_prep_splice.3
@@ -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.
--
Ammar Faizi
From: 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.
Signed-off-by: Ammar Faizi <[email protected]>
---
CHANGELOG | 2 ++
1 file changed, 2 insertions(+)
diff --git a/CHANGELOG b/CHANGELOG
index 93c500f..0722aae 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -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
--
Ammar Faizi
Ammar Faizi <[email protected]> writes:
> 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 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!
Hi Ammar,
A few suggestions below:
> --- a/man/io_uring_prep_splice.3
> +++ b/man/io_uring_prep_splice.3
> @@ -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."
> +
> +If
> +.I fd_in
> +does not refer to a pipe and
> +.I off_in
> +is -1, then bytes are read from
bytes -> nbytes ?
> +.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.
> +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
failed -> fail
Thanks,
--
Gabriel Krisman Bertazi
On 1/12/23 10:26 AM, Gabriel Krisman Bertazi wrote:
> Ammar Faizi <[email protected]> writes:
>
>> 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 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!
>
> Hi Ammar,
>
> A few suggestions below:
[snip]
Shoot, missed this. Ammar, can you send a fixup patch with the below
suggestions?
--
Jens Axboe
On Thu, 12 Jan 2023 22:57:05 +0700, Ammar Faizi wrote:
> 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.
>
> [...]
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: 55bbe5b71c7d39c9ea44e5abb886846010c67baa
Best regards,
--
Jens Axboe