[PATCH liburing v1] man/io_uring_prep_splice.3: Fix description in io_uring_prep_splice() manpage

[PATCH liburing v1] man/io_uring_prep_splice.3: Fix description in io_uring_prep_splice() manpage

[Ammar Faizi]

From: Ammar Faizi <ammarfaizi2@gnuweeb.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@outlook.com>
Suggested-by: Gabriel Krisman Bertazi <krisman@suse.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@gnuweeb.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

Re: [PATCH liburing v1] man/io_uring_prep_splice.3: Fix description in io_uring_prep_splice() manpage

[Gabriel Krisman Bertazi]

Ammar Faizi <ammarfaizi2@gnuweeb.org> writes:

> From: Ammar Faizi <ammarfaizi2@gnuweeb.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@outlook.com>
> Suggested-by: Gabriel Krisman Bertazi <krisman@suse.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@gnuweeb.org>

Reviewed-by: Gabriel Krisman Bertazi <krisman@suse.de>

-- 
Gabriel Krisman Bertazi

Re: [PATCH liburing v1] man/io_uring_prep_splice.3: Fix description in io_uring_prep_splice() manpage

[Jens Axboe]

On Fri, 13 Jan 2023 03:34:52 +0700, Ammar Faizi wrote:
> 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.
> 
> 
> [...]

Applied, thanks!

[1/1] man/io_uring_prep_splice.3: Fix description in io_uring_prep_splice() manpage
      commit: 0df8a379e929641699c2ab1f42de1efd2515b908

Best regards,
-- 
Jens Axboe