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

[Gabriel Krisman Bertazi <krisman@suse.de>]

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,

-- 
Gabriel Krisman Bertazi