[PATCH liburing v1 4/4] man/io_uring_prep_splice.3: Explain more about io_uring_prep_splice()

[Ammar Faizi <ammarfaizi2@gnuweeb.org>]

From: Ammar Faizi <ammarfaizi2@gnuweeb.org>

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@gnuweeb.org>
---

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