linux-kernel - [PATCH liburing v1 4/4] man/io_uring_prep_splice.3: Explain more about io_uring_prep

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <20230112155709.303615-5-ammar.faizi@intel.com>
Date:   Thu, 12 Jan 2023 22:57:09 +0700
From:   Ammar Faizi <ammarfaizi2@...weeb.org>
To:     Jens Axboe <axboe@...nel.dk>
Cc:     Ammar Faizi <ammarfaizi2@...weeb.org>,
        Pavel Begunkov <asml.silence@...il.com>,
        Breno Leitao <leitao@...ian.org>,
        Christian Mazakas <christian.mazakas@...il.com>,
        Gilang Fachrezy <gilang4321@...il.com>,
        VNLX Kernel Department <kernel@...x.org>,
        io-uring Mailing List <io-uring@...r.kernel.org>,
        Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
        GNU/Weeb Mailing List <gwml@...r.gnuweeb.org>
Subject: [PATCH liburing v1 4/4] man/io_uring_prep_splice.3: Explain more about io_uring_prep_splice()

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