Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   Gabriel Krisman Bertazi <krisman@suse.de>
To:     Ammar Faizi <ammarfaizi2@gnuweeb.org>
Cc:     Jens Axboe <axboe@kernel.dk>,
        Pavel Begunkov <asml.silence@gmail.com>,
        Breno Leitao <leitao@debian.org>,
        Christian Mazakas <christian.mazakas@gmail.com>,
        Gilang Fachrezy <gilang4321@gmail.com>,
        VNLX Kernel Department <kernel@vnlx.org>,
        io-uring Mailing List <io-uring@vger.kernel.org>,
        Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
        GNU/Weeb Mailing List <gwml@vger.gnuweeb.org>
Subject: Re: [PATCH liburing v1 4/4] man/io_uring_prep_splice.3: Explain
 more about io_uring_prep_splice()
References: <20230112155709.303615-1-ammar.faizi@intel.com>
        <20230112155709.303615-5-ammar.faizi@intel.com>
Date:   Thu, 12 Jan 2023 14:26:00 -0300
In-Reply-To: <20230112155709.303615-5-ammar.faizi@intel.com> (Ammar Faizi's
        message of "Thu, 12 Jan 2023 22:57:09 +0700")
Message-ID: <87bkn3ekbb.fsf@suse.de>
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux)
MIME-Version: 1.0
Content-Type: text/plain
Precedence: bulk

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