man page improvements
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
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
@@ -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
PATCH RESEND 2/2 man/io_uring_submit*.3: Point to error code documentation
In reply to Gabriel Krisman BertaziThere'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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
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 documentationman/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: 914062b3b65644cb9deee25083bffe69d54f1e94Best regards,
Signature · 1 line
Jens Axboe