linux-kernel - [PATCH liburing v2 3/7] man: Clarify "man 2" entry for io

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Tue, 30 Aug 2022 07:56:39 +0700
From:   Ammar Faizi <ammarfaizi2@...weeb.org>
To:     Jens Axboe <axboe@...nel.dk>
Cc:     Ammar Faizi <ammarfaizi2@...weeb.org>,
        Caleb Sander <csander@...estorage.com>,
        Muhammad Rizki <kiizuha@...weeb.org>,
        Kanna Scarlet <knscarlet@...weeb.org>,
        io-uring Mailing List <io-uring@...r.kernel.org>,
        Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
        GNU/Weeb Mailing List <gwml@...r.gnuweeb.org>
Subject: [PATCH liburing v2 3/7] man: Clarify "man 2" entry for io_uring syscalls

From: Ammar Faizi <ammarfaizi2@...weeb.org>

io_uring_enter(), io_uring_register(), and io_uring_setup() are not
declared in `<linux/io_uring.h>` (and never were). A previous commit
adds the implementation of these functions in liburing. Change the
include header to `<liburing.h>`. Then clarify that those functions
don't intentionally set the `errno` variable. Instead they return
a negative error code when the syscall fails.

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. Users should not rely on this behavior as it may change in the
future when nolibc support is expanded to other architectures.

Cc: Caleb Sander <csander@...estorage.com>
Signed-off-by: Ammar Faizi <ammarfaizi2@...weeb.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