Skip to contentSkip to conversation

man page improvements

PATCH RESEND Applied Gabriel Krisman Bertazi 2 participants 4 messages Aug 31 io_uring

lore
Share & tools
lore
#0 lore raw

cover man page improvements

A couple fixes to documentation requested on github issues I sent a while ago.

Gabriel Krisman Bertazi (2):
man: Fix FUTEX_WAIT/FUTEX_WAKE explanation man/io_uring_submit*.3: Point to error code documentation

 man/io_uring_enter.2                       | 39 +++++++++++-----------
 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 ++++++---
 7 files changed, 60 insertions(+), 33 deletions(-)
Signature · 1 line
2.55.0
#1 lore raw

PATCH RESEND 1/2 man: Fix FUTEX_WAIT/FUTEX_WAKE explanation

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.

---
 man/io_uring_enter.2 | 39 ++++++++++++++++++++-------------------
 1 file changed, 20 insertions(+), 19 deletions(-)
man/io_uring_enter.2 +20 -19
index 7b99335e..b2e93f43 100644
@@ -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.
 
Signature · 1 line
2.55.0
#2 lore raw

PATCH RESEND 2/2 man/io_uring_submit*.3: Point to error code documentation

In reply to 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.

---
 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(-)
man/io_uring_submit.3 +6 -1
index c7dbbed2..b78f0e63 100644
@@ -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)
man/io_uring_submit_and_get_events.3 +6 -1
index 9e143d1d..a30d7966 100644
@@ -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)
man/io_uring_submit_and_wait.3 +6 -1
index 2351f335..4a642875 100644
@@ -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)
man/io_uring_submit_and_wait_min_timeout.3 +7 -4
index 6a52806f..1812809f 100644
@@ -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)
man/io_uring_submit_and_wait_reg.3 +5 -2
index fc0bd76a..f82e432a 100644
@@ -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)
man/io_uring_submit_and_wait_timeout.3 +10 -5
index 74611766..20fe03ae 100644
@@ -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)
Signature · 1 line
2.55.0
maintainer Applied
#3 lore raw
In reply to Gabriel Krisman Bertazi
Quoted 15 lines · Gabriel Krisman Bertazi

A couple fixes to documentation requested on github issues I sent a while ago.

Gabriel Krisman Bertazi (2):
man: Fix FUTEX_WAIT/FUTEX_WAKE explanation man/io_uring_submit*.3: Point to error code documentation

man/io_uring_enter.2 | 39 +++++++++++-----------

 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 ++++++---
 7 files changed, 60 insertions(+), 33 deletions(-)
Quoted 1 line

[...]

Applied, thanks!

[1/2] man: Fix FUTEX_WAIT/FUTEX_WAKE explanation

      commit: 88add766c22ca9cee55e84145de29bd9d78dd685
[2/2] man/io_uring_submit*.3: Point to error code documentation
      commit: 914062b3b65644cb9deee25083bffe69d54f1e94

Best regards,

Signature · 1 line
Jens Axboe