* [RESEND PATCH liburing 1/2] man: Fix FUTEX_WAIT/FUTEX_WAKE explanation
2026-08-31 15:44 [RESEND PATCH liburing 0/2] man page improvements Gabriel Krisman Bertazi
@ 2026-08-31 15:44 ` Gabriel Krisman Bertazi
2026-08-31 15:44 ` [RESEND PATCH liburing 2/2] man/io_uring_submit*.3: Point to error code documentation Gabriel Krisman Bertazi
2026-08-31 23:00 ` [RESEND PATCH liburing 0/2] man page improvements Jens Axboe
2 siblings, 0 replies; 4+ messages in thread
From: Gabriel Krisman Bertazi @ 2026-08-31 15:44 UTC (permalink / raw)
To: axboe; +Cc: io-uring, Gabriel Krisman Bertazi
The description of the futex_wait parameters is incorrect when
explaining the futex value. Correct it and rewrite the rest of the
futex operations description to make them clearer.
Closes: https://github.com/axboe/liburing/issues/1625
Signed-off-by: Gabriel Krisman Bertazi <krisman@suse.de>
---
man/io_uring_enter.2 | 39 ++++++++++++++++++++-------------------
1 file changed, 20 insertions(+), 19 deletions(-)
diff --git a/man/io_uring_enter.2 b/man/io_uring_enter.2
index 7b99335e..b2e93f43 100644
--- a/man/io_uring_enter.2
+++ b/man/io_uring_enter.2
@@ -1538,20 +1538,19 @@ system call.
.I addr
must hold a pointer to the futex,
.I addr2
-must hold the value to which the futex has to be changed so this caller to
-.BR futex_wait (2)
-can be woken by a call to
-.BR futex_wake (2),
+must hold the value of the futex word read by the application when
+submitting the operation. The kernel will only put the task to sleep
+and wait on the futex if, at the time of queueing, the futex word still
+matches this value.
.I addr3
-must hold the bitmask of this
+must hold a bitmask of this
.BR futex_wait (2)
-caller.
-For a caller of
-.BR futex_wake (2)
-to wake a waiter additionally the bitmask of the waiter and waker must have
-at least one set bit in common.
+caller, which will be used as a key by the kernel when
+deciding which callers to wake up.
.I fd
-must contain additional flags passed in.
+may contain additional flags following the
+.B futex2
+interface flags.
Available since 6.7.
@@ -1561,17 +1560,19 @@ Issues the equivalent of the
.BR futex_wake (2)
system call.
.I addr
-must hold a pointer to the futex,
+must hold a pointer to the futex to be awaken,
.I addr2
-must hold the maximum number of waiters waiting on this futex to wake,
+must hold the maximum number of waiters to be awaken by this call,
.I addr3
-must hold the bitmask of this
-.BR futex_wake (2)
-call.
-To wake a waiter additionally the bitmask of the waiter and waker must have
-at least one set bit in common.
+must hold a bitmask identifying which callers to wake.
+A waker will be waken if at least one bit of the bitmask matches,
+subject to the limit of waiters set by
+.IR addr2 .
.I fd
-must contain additional flags passed in.
+may contain additional flags following
+the
+.B futex2
+interface flags.
Available since 6.7.
--
2.55.0
^ permalink raw reply related [flat|nested] 4+ messages in thread
* [RESEND PATCH liburing 2/2] man/io_uring_submit*.3: Point to error code documentation
2026-08-31 15:44 [RESEND PATCH liburing 0/2] man page improvements Gabriel Krisman Bertazi
2026-08-31 15:44 ` [RESEND PATCH liburing 1/2] man: Fix FUTEX_WAIT/FUTEX_WAKE explanation Gabriel Krisman Bertazi
@ 2026-08-31 15:44 ` Gabriel Krisman Bertazi
2026-08-31 23:00 ` [RESEND PATCH liburing 0/2] man page improvements Jens Axboe
2 siblings, 0 replies; 4+ messages in thread
From: Gabriel Krisman Bertazi @ 2026-08-31 15:44 UTC (permalink / raw)
To: axboe; +Cc: io-uring, Gabriel Krisman Bertazi
There's an open issue in gh asking about the possible error codes
returned by io_uring_submit. Add pointers to io_uring_enter(2) in all
io_uring_submit* variants where the error codes are explained in
detail. The minor exception are _wait_timeout, wait_and_reg and
wait_min_timeout, where there are more error codes to be described.
Closes: https://github.com/axboe/liburing/issues/1511
Signed-off-by: Gabriel Krisman Bertazi <krisman@suse.de>
---
man/io_uring_submit.3 | 7 ++++++-
man/io_uring_submit_and_get_events.3 | 7 ++++++-
man/io_uring_submit_and_wait.3 | 7 ++++++-
man/io_uring_submit_and_wait_min_timeout.3 | 11 +++++++----
man/io_uring_submit_and_wait_reg.3 | 7 +++++--
man/io_uring_submit_and_wait_timeout.3 | 15 ++++++++++-----
6 files changed, 40 insertions(+), 14 deletions(-)
diff --git a/man/io_uring_submit.3 b/man/io_uring_submit.3
index c7dbbed2..b78f0e63 100644
--- a/man/io_uring_submit.3
+++ b/man/io_uring_submit.3
@@ -33,6 +33,10 @@ about how many submission queue entries have been successfully submitted, while
using SQPOLL, the user must fall back to repeatedly submitting a single submission
queue entry. On failure it returns
.BR -errno .
+See
+.BR io_uring_enter (2)
+for details on the possible error codes returned by
+.BR io_uring_submit (3) .
.SH NOTES
For any request that passes in data in a struct, that data must remain
valid until the request has been successfully submitted. It need not remain
@@ -48,4 +52,5 @@ mentioning this fact as well, if required for the given command.
.SH SEE ALSO
.BR io_uring_get_sqe (3),
.BR io_uring_submit_and_wait (3),
-.BR io_uring_submit_and_wait_timeout (3)
+.BR io_uring_submit_and_wait_timeout (3),
+.BR io_uring_enter (2)
diff --git a/man/io_uring_submit_and_get_events.3 b/man/io_uring_submit_and_get_events.3
index 9e143d1d..a30d7966 100644
--- a/man/io_uring_submit_and_get_events.3
+++ b/man/io_uring_submit_and_get_events.3
@@ -26,6 +26,11 @@ On success
.BR io_uring_submit_and_get_events (3)
returns the number of submitted submission queue entries. On failure it returns
.BR -errno .
+See
+.BR io_uring_enter (2)
+for details on the possible error codes returned by
+.BR io_uring_submit_and_get_events (3) .
.SH SEE ALSO
.BR io_uring_submit (3),
-.BR io_uring_get_events (3)
+.BR io_uring_get_events (3),
+.BR io_uring_enter (2)
diff --git a/man/io_uring_submit_and_wait.3 b/man/io_uring_submit_and_wait.3
index 2351f335..4a642875 100644
--- a/man/io_uring_submit_and_wait.3
+++ b/man/io_uring_submit_and_wait.3
@@ -37,8 +37,13 @@ On success
.BR io_uring_submit_and_wait (3)
returns the number of submitted submission queue entries. On failure it returns
.BR -errno .
+See
+.BR io_uring_enter (2)
+for details on the possible error codes returned by
+.BR io_uring_submit_and_wait (3) .
.SH SEE ALSO
.BR io_uring_queue_init_params (3),
.BR io_uring_get_sqe (3),
.BR io_uring_submit (3),
-.BR io_uring_submit_and_wait_timeout (3)
+.BR io_uring_submit_and_wait_timeout (3),
+.BR io_uring_enter (2)
diff --git a/man/io_uring_submit_and_wait_min_timeout.3 b/man/io_uring_submit_and_wait_min_timeout.3
index 6a52806f..1812809f 100644
--- a/man/io_uring_submit_and_wait_min_timeout.3
+++ b/man/io_uring_submit_and_wait_min_timeout.3
@@ -106,14 +106,17 @@ returns the number of submitted submission queue entries. On failure it returns
If the kernel doesn't support this functionality,
.BR -EINVAL
will be returned. See note on the feature flag.
-The most common failure case is not receiving a completion within the specified
-timeout,
+See
+.BR io_uring_enter (2)
+for details on the other possible error codes. In addition to those, this
+function can also return
.B -ETIME
-is returned in this case.
+if a completion was not received within the specified timeframe.
.SH SEE ALSO
.BR io_uring_queue_init_params (3),
.BR io_uring_get_sqe (3),
.BR io_uring_submit (3),
.BR io_uring_submit_and_wait (3),
.BR io_uring_submit_and_wait_timeout (3),
-.BR io_uring_wait_cqe (3)
+.BR io_uring_wait_cqe (3),
+.BR io_uring_enter (2)
diff --git a/man/io_uring_submit_and_wait_reg.3 b/man/io_uring_submit_and_wait_reg.3
index fc0bd76a..f82e432a 100644
--- a/man/io_uring_submit_and_wait_reg.3
+++ b/man/io_uring_submit_and_wait_reg.3
@@ -56,9 +56,12 @@ If the kernel doesn't support this functionality,
will be returned. If no events are submitted and the wait operation times
out, then
.BR -ETIME
-will be returned.
+will be returned. Otherwise, see
+.BR io_uring_enter (2)
+for details on the remaining possible error codes.
.SH SEE ALSO
.BR io_uring_register_region (3) ,
.BR io_uring_submit_and_wait_min_timeout (3) ,
-.BR io_uring_submit_and_wait_timeout (3)
+.BR io_uring_submit_and_wait_timeout (3) ,
+.BR io_uring_enter (2)
diff --git a/man/io_uring_submit_and_wait_timeout.3 b/man/io_uring_submit_and_wait_timeout.3
index 74611766..20fe03ae 100644
--- a/man/io_uring_submit_and_wait_timeout.3
+++ b/man/io_uring_submit_and_wait_timeout.3
@@ -60,15 +60,20 @@ On success
.BR io_uring_submit_and_wait_timeout (3)
returns the number of submitted submission queue entries. On failure it returns
.BR -errno .
+See
+.BR io_uring_enter (2)
+for details on the possible error codes. In addition to those, this
+function can also return
+.B -ETIME
+if a completion was not received within the specified timeframe, or
+.B -EAGAIN
+if the queue was full and it couldn't queue the timeout request.
Note that in earlier versions of the liburing library, the return value was 0
on success.
-The most common failure case is not receiving a completion within the specified
-timeout,
-.B -ETIME
-is returned in this case.
.SH SEE ALSO
.BR io_uring_queue_init_params (3),
.BR io_uring_get_sqe (3),
.BR io_uring_submit (3),
.BR io_uring_submit_and_wait (3),
-.BR io_uring_wait_cqe (3)
+.BR io_uring_wait_cqe (3),
+.BR io_uring_enter (2)
--
2.55.0
^ permalink raw reply related [flat|nested] 4+ messages in thread