diff mbox series

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

Message ID 20230112155709.303615-5-ammar.faizi@intel.com
State New
Headers
Series liburing updates for 2.4 |

Commit Message

Ammar Faizi Jan. 12, 2023, 3:57 p.m. UTC 
  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(+)

Comments

Gabriel Krisman Bertazi Jan. 12, 2023, 5:26 p.m. UTC | #1 
Ammar Faizi <ammarfaizi2@gnuweeb.org> writes:

> 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!

Hi Ammar,

A few suggestions below:

> --- 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.

Maybe

"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

bytes -> nbytes ?

> +.I fd_in
> +starting from the file offset and it is adjusted appropriately.

What do you think:

starting from the file offset, which is incremented by the number of
bytes read.

> +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

failed -> fail

Thanks,
Jens Axboe Jan. 12, 2023, 5:49 p.m. UTC | #2 
On 1/12/23 10:26 AM, Gabriel Krisman Bertazi wrote:
> Ammar Faizi <ammarfaizi2@gnuweeb.org> writes:
> 
>> 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!
> 
> Hi Ammar,
> 
> A few suggestions below:

[snip]

Shoot, missed this. Ammar, can you send a fixup patch with the below
suggestions?
diff mbox series

Patch

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.