diff mbox series

[liburing,v2,3/7] man: Clarify "man 2" entry for io_uring syscalls

Message ID 20220830005122.885209-4-ammar.faizi@intel.com (mailing list archive)
State New
Headers show
Series Export io_uring syscall functions | expand

Commit Message

Ammar Faizi Aug. 30, 2022, 12:56 a.m. UTC 
From: Ammar Faizi <ammarfaizi2@gnuweeb.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@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 mbox series

Patch

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