From: Ammar Faizi <ammarfaizi2@xxxxxxxxxxx> 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 <ammarfaizi2@xxxxxxxxxxx> --- 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
