linux-kernel - [PATCH liburing v1] man/io_uring_prep_splice.3: Fix description in 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-next>] [day] [month] [year] [list]

Message-Id: <20230112203452.317648-1-ammar.faizi@intel.com>
Date:   Fri, 13 Jan 2023 03:34:52 +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>,
        io-uring Mailing List <io-uring@...r.kernel.org>,
        VNLX Kernel Department <kernel@...x.org>,
        Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
        GNU/Weeb Mailing List <gwml@...r.gnuweeb.org>,
        Jiahao XU <Jiahao_XU@...look.com>,
        Gabriel Krisman Bertazi <krisman@...e.de>
Subject: [PATCH liburing v1] man/io_uring_prep_splice.3: Fix description in io_uring_prep_splice() manpage

From: Ammar Faizi <ammarfaizi2@...weeb.org>

Commit 55bbe5b71c7d missed a review from Gabriel. It was blindly copied
from liburing.h comment with just a modification to support manpage
formatting. Fix that.

While in there, also fix the liburing.h from which that mistake comes.

Cc: Jiahao XU <Jiahao_XU@...look.com>
Suggested-by: Gabriel Krisman Bertazi <krisman@...e.de>
Link: https://lore.kernel.org/io-uring/87bkn3ekbb.fsf@suse.de
Fixes: 55bbe5b71c7d ("man/io_uring_prep_splice.3: Explain more about io_uring_prep_splice()")
Fixes: d871f482d911 ("Add inline doc in the comments for io_uring_prep_splice")
Signed-off-by: Ammar Faizi <ammarfaizi2@...weeb.org>
---
 man/io_uring_prep_splice.3 | 12 +++++++-----
 src/include/liburing.h     | 27 +++++++++++++--------------
 2 files changed, 20 insertions(+), 19 deletions(-)

diff --git a/man/io_uring_prep_splice.3 b/man/io_uring_prep_splice.3
index a177bc6..3d6e38f 100644
--- a/man/io_uring_prep_splice.3
+++ b/man/io_uring_prep_splice.3
@@ -55,16 +55,18 @@ given as a registered file descriptor offset.
 If
 .I fd_in
 refers to a pipe,
-.IR off_in
-must be -1.
+.I 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
+is -1, then
+.I nbytes
+are read from
 .I fd_in
-starting from the file offset and it is adjusted appropriately.
+starting from the file offset, which is incremented by the number of bytes read.
 
 If
 .I fd_in
@@ -112,7 +114,7 @@ Note that even if
 .I fd_in
 or
 .I fd_out
-refers to a pipe, the splice operation can still failed with
+refers to a pipe, the splice operation can still fail 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.
diff --git a/src/include/liburing.h b/src/include/liburing.h
index c7139ef..41a58eb 100644
--- a/src/include/liburing.h
+++ b/src/include/liburing.h
@@ -383,26 +383,25 @@ IOURINGINLINE void io_uring_prep_rw(int op, struct io_uring_sqe *sqe, int fd,
 	sqe->__pad2[0] = 0;
 }
 
-/**
- * @pre Either fd_in or fd_out must be a pipe.
- * @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 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.
- * @param splice_flags see man splice(2) for description of flags.
+/*
+ * io_uring_prep_splice() - Either @fd_in or @fd_out must be a pipe.
+ *
+ * - If @fd_in refers to a pipe, @off_in is ignored and must be set to -1.
+ *
+ * - If @fd_in does not refer to a pipe and @off_in is -1, then @nbytes are read
+ *   from @fd_in starting from the file offset, which is incremented by the
+ *   number of bytes read.
+ *
+ * - 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.
  *
  * This splice operation can be used to implement sendfile by splicing to an
  * intermediate pipe first, then splice to the final destination.
  * In fact, the implementation of sendfile in kernel uses splice internally.
  *
  * 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.
+ * can still fail 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.
  * Check issue #291 for more information.
  */
 IOURINGINLINE void io_uring_prep_splice(struct io_uring_sqe *sqe,

base-commit: 55bbe5b71c7d39c9ea44e5abb886846010c67baa
-- 
Ammar Faizi