From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 990F1C54EBD for ; Thu, 12 Jan 2023 16:06:29 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231906AbjALQG0 (ORCPT ); Thu, 12 Jan 2023 11:06:26 -0500 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:47414 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232596AbjALQGA (ORCPT ); Thu, 12 Jan 2023 11:06:00 -0500 Received: from gnuweeb.org (gnuweeb.org [51.81.211.47]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 93CC560C0; Thu, 12 Jan 2023 07:57:33 -0800 (PST) Received: from localhost.localdomain (unknown [182.253.183.184]) by gnuweeb.org (Postfix) with ESMTPSA id 3ABB57E74D; Thu, 12 Jan 2023 15:57:29 +0000 (UTC) X-GW-Data: lPqxHiMPbJw1wb7CM9QUryAGzr0yq5atzVDdxTR0iA== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gnuweeb.org; s=default; t=1673539053; bh=rH47GSDKKNn4IUUqXJmB8n2oZPbSj4OOp9WUqqpcbh8=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=nxvkGyjNUSjXd+lzOaZ4g9MRsycP+OfBHdwmVdPKMl1n+VWlEZdzKXk5V5smNWzyM AkeVdWcijkmoasznjtf/79Ke2SAXtVV8O5agAVVP5Q6iMvFvRYxxxIaIGDGKSGDGu2 toBr5Xra526B60HRmVfd3bb+4csF84dSkiLPRJOG6H2OvR5mliIwZBrWPJbQUDXKK1 O/LTV6P1zi1bTINjXGWcw6mFug5K1Xz+pwaKY0in6LW8CDx6f9m/3H2hU11JTTcYot KHtdqmPGtAddaMn0XHzGcJJKtPVcu5hiTZzijsgrbKcskT6y8OxDMMeSl/6dKbtPWw XvE679r7y4xLg== From: Ammar Faizi To: Jens Axboe Cc: Ammar Faizi , Pavel Begunkov , Breno Leitao , Christian Mazakas , Gilang Fachrezy , VNLX Kernel Department , io-uring Mailing List , Linux Kernel Mailing List , GNU/Weeb Mailing List Subject: [PATCH liburing v1 4/4] man/io_uring_prep_splice.3: Explain more about io_uring_prep_splice() Date: Thu, 12 Jan 2023 22:57:09 +0700 Message-Id: <20230112155709.303615-5-ammar.faizi@intel.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230112155709.303615-1-ammar.faizi@intel.com> References: <20230112155709.303615-1-ammar.faizi@intel.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Precedence: bulk List-ID: X-Mailing-List: io-uring@vger.kernel.org From: Ammar Faizi 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 --- 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(+) 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. -- Ammar Faizi