summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPavel Begunkov <asml.silence@gmail.com>2021-11-27 01:50:25 +0000
committerJens Axboe <axboe@kernel.dk>2021-11-27 07:07:41 -0700
commit509873c4454012c5810c728695c21911c82acdc4 (patch)
tree0a3214294907c2367352aacf7e9039590f1f77f3
parent3cbc199a80f37ad5183e04144b4126bb9c619b8b (diff)
downloadliburing-509873c4454012c5810c728695c21911c82acdc4.tar.gz
liburing-509873c4454012c5810c728695c21911c82acdc4.tar.bz2
man/io_uring_enter.2: document IOSQE_CQE_SKIP_SUCCESS
Add a section about IOSQE_CQE_SKIP_SUCCESS describing the behaviour and use cases. Signed-off-by: Pavel Begunkov <asml.silence@gmail.com> Link: https://lore.kernel.org/r/381237725f0f09a2668ea7f38b804d5733595b1f.1637977800.git.asml.silence@gmail.com [axboe: some rewording] Signed-off-by: Jens Axboe <axboe@kernel.dk>
-rw-r--r--man/io_uring_enter.222
1 files changed, 22 insertions, 0 deletions
diff --git a/man/io_uring_enter.2 b/man/io_uring_enter.2
index 93b97e6..b003e05 100644
--- a/man/io_uring_enter.2
+++ b/man/io_uring_enter.2
@@ -1094,6 +1094,28 @@ are available and this flag is set, then the request will fail with
as the error code. Once a buffer has been used, it is no longer available in
the kernel pool. The application must re-register the given buffer again when
it is ready to recycle it (eg has completed using it). Available since 5.7.
+.TP
+.B IOSQE_CQE_SKIP_SUCCESS
+Don't generate a CQE if the request completes successfully. If the request
+fails, an appropriate CQE will be posted as usual and if there is no
+.B IOSQE_IO_HARDLINK,
+CQEs for all linked requests will be omitted. The notion of failure/success is
+opcode specific and is the same as with breaking chains of
+.B IOSQE_IO_LINK.
+One special case is when the request has a linked timeout, then the CQE
+generation for the linked timeout is decided solely by whether it has
+.B IOSQE_CQE_SKIP_SUCCESS
+set, regardless whether it timed out or was cancelled. In other words, if a
+linked timeout has the flag set, it's guaranteed to not post a CQE.
+
+The semantics are chosen to accommodate several use cases. First, when all but
+the last request of a normal link without linked timeouts are marked with the
+flag, only one CQE per lin is posted. Additionally, it enables supression of
+CQEs in cases where the side effects of a successfully executed operation is
+enough for userspace to know the state of the system. One such example would
+be writing to a synchronisation file.
+
+Available since 5.17.
.PP
.I ioprio