summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJens Axboe <axboe@kernel.dk>2021-09-16 09:26:59 -0600
committerJens Axboe <axboe@kernel.dk>2021-09-16 09:26:59 -0600
commitd68917b4207bd9a6d39a5b87109e9cfdde574878 (patch)
tree0a787db92297427c05a1506b77fdefcdceccef27
parent64bcc40862b20d25efde357422e2dc76c9985c77 (diff)
downloadliburing-d68917b4207bd9a6d39a5b87109e9cfdde574878.tar.gz
liburing-d68917b4207bd9a6d39a5b87109e9cfdde574878.tar.bz2
man/io_uring.7: clarify how success and error returns are propagated
Also make it clear that IORING_OP_READ isn't a direct match for read(2), rather it's a mix of pread(2) and preadv2(2) in that it both takes an explicit file offset, and also supports using -1 for that offset to indicate that the current file position should be used. Fixes: https://github.com/axboe/liburing/issues/435 Signed-off-by: Jens Axboe <axboe@kernel.dk>
-rw-r--r--man/io_uring.736
1 files changed, 27 insertions, 9 deletions
diff --git a/man/io_uring.7 b/man/io_uring.7
index 972683b..dc76f42 100644
--- a/man/io_uring.7
+++ b/man/io_uring.7
@@ -84,17 +84,35 @@ a read operation under
.BR io_uring ,
started with the
.BR IORING_OP_READ
-operation,
-which issues the equivalent of the
+operation, issues the equivalent of the
.BR read (2)
-system call,
-would return as part of
+system call. In practice, it mixes the semantics of
+.BR pread (2)
+and
+.BR preadv2 (2)
+in that it takes an explicit offset, and supports using -1 for the offset to
+indicate that the current file position should be used instead of passing in
+an explicit offset. See the opcode documentation for more details. Given that
+io_uring is an async interface,
+.I errno
+is never used for passing back error information. Instead,
.I res
-what
-.BR read (2)
-would have returned if called directly,
-without using
-.BR io_uring .
+will contain what the equivalent system call would have returned in case
+of success, and in case of error
+.I res
+will contain
+.I -errno .
+For example, if the normal read system call would have returned -1 and set
+.I errno
+to
+.B EINVAL ,
+then
+.I res
+would contain
+.B -EINVAL .
+If the normal system call would have returned a read size of 1024, then
+.I res
+would contain 1024.
.IP \(bu
Optionally,
.BR io_uring_enter (2)