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:   Ammar Faizi <ammarfaizi2@gnuweeb.org>
To:     Jens Axboe <axboe@kernel.dk>
Cc:     Ammar Faizi <ammarfaizi2@gnuweeb.org>,
        Caleb Sander <csander@purestorage.com>,
        Muhammad Rizki <kiizuha@gnuweeb.org>,
        Kanna Scarlet <knscarlet@gnuweeb.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: [RFC PATCH liburing v1 2/4] man: Clarify "man 2" entry for io_uring syscalls
Date:   Mon, 29 Aug 2022 10:07:37 +0700
Message-Id: <20220829030521.3373516-3-ammar.faizi@intel.com>
In-Reply-To: <20220829030521.3373516-1-ammar.faizi@intel.com>
References: <20220829030521.3373516-1-ammar.faizi@intel.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

From: Ammar Faizi <ammarfaizi2@gnuweeb.org>

io_uring_enter(), io_uring_register(), io_uring_setup() are not
declared in `<linux/io_uring.h>` and never were. Plus, these
functions don't intentionally set the `errno` variable. Reflect this
fact in the manpage.

Side note: On architectures other than x86, x86-64, and aarch64, those
functions _do_ set the `errno`, this is because the syscall is done via
libc as we don't yet have nolibc support for the mentioned archs. Users
should not rely on this behavior.

Cc: Caleb Sander <csander@purestorage.com>
Signed-off-by: Ammar Faizi <ammarfaizi2@gnuweeb.org>
---
 man/io_uring_enter.2    | 9 ++++-----
 man/io_uring_register.2 | 9 ++++-----
 man/io_uring_setup.2    | 8 +++-----
 3 files changed, 11 insertions(+), 15 deletions(-)

diff --git a/man/io_uring_enter.2 b/man/io_uring_enter.2
index 6bfe9c9..05f9f72 100644
--- a/man/io_uring_enter.2
+++ b/man/io_uring_enter.2
@@ -8,7 +8,7 @@
 io_uring_enter \- initiate and/or complete asynchronous I/O
 .SH SYNOPSIS
 .nf
-.BR "#include <linux/io_uring.h>"
+.BR "#include <liburing.h>"
 .PP
 .BI "int io_uring_enter(unsigned int " fd ", unsigned int " to_submit ,
 .BI "                   unsigned int " min_complete ", unsigned int " flags ,
@@ -1299,11 +1299,10 @@ completion queue entry (see section
 rather than through the system call itself.
 
 Errors that occur not on behalf of a submission queue entry are returned via the
-system call directly. On such an error,
-.B -1
-is returned and
+system call directly. On such an error, a negative error code is returned. The
+caller should not rely on
 .I errno
-is set appropriately.
+variable.
 .PP
 .SH ERRORS
 These are the errors returned by
diff --git a/man/io_uring_register.2 b/man/io_uring_register.2
index 6c440b9..6791375 100644
--- a/man/io_uring_register.2
+++ b/man/io_uring_register.2
@@ -8,7 +8,7 @@
 io_uring_register \- register files or user buffers for asynchronous I/O 
 .SH SYNOPSIS
 .nf
-.BR "#include <linux/io_uring.h>"
+.BR "#include <liburing.h>"
 .PP
 .BI "int io_uring_register(unsigned int " fd ", unsigned int " opcode ,
 .BI "                      void *" arg ", unsigned int " nr_args );
@@ -583,11 +583,10 @@ Available since 5.18.
 
 On success,
 .BR io_uring_register ()
-returns 0.  On error,
-.B -1
-is returned, and
+returns 0.  On error, a negative error code is returned. The caller should not
+rely on
 .I errno
-is set accordingly.
+variable.
 
 .SH ERRORS
 .TP
diff --git a/man/io_uring_setup.2 b/man/io_uring_setup.2
index 0a5fa92..32a9e2e 100644
--- a/man/io_uring_setup.2
+++ b/man/io_uring_setup.2
@@ -9,7 +9,7 @@
 io_uring_setup \- setup a context for performing asynchronous I/O
 .SH SYNOPSIS
 .nf
-.BR "#include <linux/io_uring.h>"
+.BR "#include <liburing.h>"
 .PP
 .BI "int io_uring_setup(u32 " entries ", struct io_uring_params *" p );
 .fi
@@ -566,11 +566,9 @@ or
 .BR io_uring_enter (2)
 system calls.
 
-On error,
-.B -1
-is returned and
+On error, a negative error code is returned. The caller should not rely on
 .I errno
-is set appropriately.
+variable.
 .PP
 .SH ERRORS
 .TP
-- 
Ammar Faizi