public inbox for [email protected]
 help / color / mirror / Atom feed
* [PATCH liburing v1] man/io_uring_prep_splice.3: Fix description in io_uring_prep_splice() manpage
@ 2023-01-12 20:34 Ammar Faizi
  2023-01-12 20:47 ` Gabriel Krisman Bertazi
  2023-01-12 23:16 ` Jens Axboe
  0 siblings, 2 replies; 3+ messages in thread
From: Ammar Faizi @ 2023-01-12 20:34 UTC (permalink / raw)
  To: Jens Axboe
  Cc: Ammar Faizi, Pavel Begunkov, Breno Leitao, Christian Mazakas,
	Gilang Fachrezy, io-uring Mailing List, VNLX Kernel Department,
	Linux Kernel Mailing List, GNU/Weeb Mailing List, Jiahao XU,
	Gabriel Krisman Bertazi

From: Ammar Faizi <[email protected]>

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 <[email protected]>
Suggested-by: Gabriel Krisman Bertazi <[email protected]>
Link: https://lore.kernel.org/io-uring/[email protected]
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 <[email protected]>
---
 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


^ permalink raw reply related	[flat|nested] 3+ messages in thread
end of thread, other threads:[~2023-01-12 23:16 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-01-12 20:34 [PATCH liburing v1] man/io_uring_prep_splice.3: Fix description in io_uring_prep_splice() manpage Ammar Faizi
2023-01-12 20:47 ` Gabriel Krisman Bertazi
2023-01-12 23:16 ` Jens Axboe

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox