[RESEND PATCH liburing 0/2] man page improvements

[RESEND PATCH liburing 0/2] man page improvements

[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(-)

-- 
2.55.0

[RESEND PATCH liburing 1/2] man: Fix FUTEX_WAIT/FUTEX_WAKE explanation

[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

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

[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