polyphony 0.93 → 0.95

data/vendor/liburing/man/io_uring_setup.2

@@ -4,20 +4,22 @@
 .\"
 .\" SPDX-License-Identifier: LGPL-2.0-or-later
 .\"
-.TH IO_URING_SETUP 2 2019-01-29 "Linux" "Linux Programmer's Manual"
+.TH io_uring_setup 2 2019-01-29 "Linux" "Linux Programmer's Manual"
 .SH NAME
 io_uring_setup \- setup a context for performing asynchronous I/O
 .SH SYNOPSIS
 .nf
-.BR "#include <linux/io_uring.h>"
+.BR "#include <liburing.h>"
 .PP
 .BI "int io_uring_setup(u32 " entries ", struct io_uring_params *" p );
 .fi
-.PP
+.PPAA
 .SH DESCRIPTION
 .PP
-The io_uring_setup() system call sets up a submission queue (SQ) and
-completion queue (CQ) with at least
+The
+.BR io_uring_setup (2)
+system call sets up a submission queue (SQ) and completion queue (CQ) with at
+least
 .I entries
 entries, and returns a file descriptor which can be used to perform
 subsequent operations on the io_uring instance.  The submission and
@@ -171,7 +173,7 @@ then it will be clamped at
 .B IORING_MAX_CQ_ENTRIES .
 .TP
 .B IORING_SETUP_ATTACH_WQ
-This flag should be set in conjunction with 
+This flag should be set in conjunction with
 .IR "struct io_uring_params.wq_fd"
 being set to an existing io_uring ring file descriptor. When set, the
 io_uring instance being created will share the asynchronous worker
@@ -188,7 +190,7 @@ for details on how to enable the ring. Available since 5.10.
 .B IORING_SETUP_SUBMIT_ALL
 Normally io_uring stops submitting a batch of request, if one of these requests
 results in an error. This can cause submission of less than what is expected,
-if a request ends in error while being submitted. If the ring is creted with
+if a request ends in error while being submitted. If the ring is created with
 this flag,
 .BR io_uring_enter (2)
 will continue submitting requests even if it encounters an error submitting
@@ -196,6 +198,86 @@ a request. CQEs are still posted for errored request regardless of whether or
 not this flag is set at ring creation time, the only difference is if the
 submit sequence is halted or continued when an error is observed. Available
 since 5.18.
+.TP
+.B IORING_SETUP_COOP_TASKRUN
+By default, io_uring will interrupt a task running in userspace when a
+completion event comes in. This is to ensure that completions run in a timely
+manner. For a lot of use cases, this is overkill and can cause reduced
+performance from both the inter-processor interrupt used to do this, the
+kernel/user transition, the needless interruption of the tasks userspace
+activities, and reduced batching if completions come in at a rapid rate. Most
+applications don't need the forceful interruption, as the events are processed
+at any kernel/user transition. The exception are setups where the application
+uses multiple threads operating on the same ring, where the application
+waiting on completions isn't the one that submitted them. For most other
+use cases, setting this flag will improve performance. Available since 5.19.
+.TP
+.B IORING_SETUP_TASKRUN_FLAG
+Used in conjunction with
+.B IORING_SETUP_COOP_TASKRUN,
+this provides a flag,
+.B IORING_SQ_TASKRUN,
+which is set in the SQ ring
+.I flags
+whenever completions are pending that should be processed. liburing will check
+for this flag even when doing
+.BR io_uring_peek_cqe (3)
+and enter the kernel to process them, and applications can do the same. This
+makes
+.B IORING_SETUP_TASKRUN_FLAG
+safe to use even when applications rely on a peek style operation on the CQ
+ring to see if anything might be pending to reap. Available since 5.19.
+.TP
+.B IORING_SETUP_SQE128
+If set, io_uring will use 128-byte SQEs rather than the normal 64-byte sized
+variant. This is a requirement for using certain request types, as of 5.19
+only the
+.B IORING_OP_URING_CMD
+passthrough command for NVMe passthrough needs this. Available since 5.19.
+.TP
+.B IORING_SETUP_CQE32
+If set, io_uring will use 32-byte CQEs rather than the normal 16-byte sized
+variant. This is a requirement for using certain request types, as of 5.19
+only the
+.B IORING_OP_URING_CMD
+passthrough command for NVMe passthrough needs this. Available since 5.19.
+.TP
+.B IORING_SETUP_SINGLE_ISSUER
+A hint to the kernel that only a single task (or thread) will submit requests, which is
+used for internal optimisations. The submission task is either the task that created the
+ring, or if
+.B IORING_SETUP_R_DISABLED
+is specified then it is the task that enables the ring through
+.BR io_uring_register (2) .
+The kernel enforces this rule, failing requests with
+.B -EEXIST
+if the restriction is violated.
+Note that when
+.B IORING_SETUP_SQPOLL
+is set it is considered that the polling task is doing all submissions
+on behalf of the userspace and so it always complies with the rule disregarding
+how many userspace tasks do
+.BR io_uring_enter(2).
+Available since 6.0.
+.TP
+.B IORING_SETUP_DEFER_TASKRUN
+By default, io_uring will process all outstanding work at the end of any system
+call or thread interrupt. This can delay the application from making other progress.
+Setting this flag will hint to io_uring that it should defer work until an
+.BR io_uring_enter(2)
+call with the 
+.B IORING_ENTER_GETEVENTS
+flag set. This allows the application to request work to run just before it wants to
+process completions.
+This flag requires the
+.BR IORING_SETUP_SINGLE_ISSUER
+flag to be set, and also enforces that the call to
+.BR io_uring_enter(2)
+is called from the same thread that submitted requests.
+Note that if this flag is set then it is the application's responsibility to periodically
+trigger work (for example via any of the CQE waiting functions) or else completions may
+not be delivered.
+Available since 6.1.
 .PP
 If no flags are specified, the io_uring instance is setup for
 interrupt driven I/O.  I/O may be submitted using
@@ -218,7 +300,7 @@ call. The SQEs must still be allocated separately. This brings the necessary
 calls down from three to two. Available since kernel 5.4.
 .TP
 .B IORING_FEAT_NODROP
-If this flag is set, io_uring supports never dropping completion events.
+If this flag is set, io_uring supports almost never dropping completion events.
 If a completion event occurs and the CQ ring is full, the kernel stores
 the event internally until such a time that the CQ ring has room for more
 entries. If this overflow condition is entered, attempting to submit more
@@ -226,7 +308,14 @@ IO will fail with the
 .B -EBUSY
 error value, if it can't flush the overflown events to the CQ ring. If this
 happens, the application must reap events from the CQ ring and attempt the
-submit again. Available since kernel 5.5.
+submit again. If the kernel has no free memory to store the event internally
+it will be visible by an increase in the overflow value on the cqring.
+Available since kernel 5.5. Additionally
+.BR io_uring_enter (2)
+will return
+.B -EBADR
+the next time it would otherwise sleep waiting for completions (since kernel 5.19).
+
 .TP
 .B IORING_FEAT_SUBMIT_STABLE
 If this flag is set, applications can be certain that any data for
@@ -337,6 +426,25 @@ If this flag is set, then io_uring supports a variety of features related
 to fixed files and buffers. In particular, it indicates that registered
 buffers can be updated in-place, whereas before the full set would have to
 be unregistered first. Available since kernel 5.13.
+.TP
+.B IORING_FEAT_CQE_SKIP
+If this flag is set, then io_uring supports setting
+.B IOSQE_CQE_SKIP_SUCCESS
+in the submitted SQE, indicating that no CQE should be generated for this
+SQE if it executes normally. If an error happens processing the SQE, a
+CQE with the appropriate error value will still be generated. Available since
+kernel 5.17.
+.TP
+.B IORING_FEAT_LINKED_FILE
+If this flag is set, then io_uring supports sane assignment of files for SQEs
+that have dependencies. For example, if a chain of SQEs are submitted with
+.B IOSQE_IO_LINK,
+then kernels without this flag will prepare the file for each link upfront.
+If a previous link opens a file with a known index, eg if direct descriptors
+are used with open or accept, then file assignment needs to happen post
+execution of that SQE. If this flag is set, then the kernel will defer
+file assignment until execution of a given request is started. Available since
+kernel 5.17.
 
 .PP
 The rest of the fields in the
@@ -486,11 +594,9 @@ or
 .BR io_uring_enter (2)
 system calls.
 
-On error,
-.B -1
-is returned and
+On error, a negative error code is returned. The caller should not rely on
 .I errno
-is set appropriately.
+variable.
 .PP
 .SH ERRORS
 .TP

data/vendor/liburing/man/io_uring_sq_ready.3

@@ -2,24 +2,30 @@
 .\"
 .\" SPDX-License-Identifier: LGPL-2.0-or-later
 .\"
-.TH io_uring_sq_ready "January 25, 2022" "liburing-2.1" "liburing Manual"
+.TH io_uring_sq_ready 3 "January 25, 2022" "liburing-2.1" "liburing Manual"
 .SH NAME
-io_uring_sq_ready - number of unconsumed or unsubmitted entries in the SQ ring
+io_uring_sq_ready \- number of unconsumed or unsubmitted entries in the SQ ring
 .SH SYNOPSIS
 .nf
-.BR "#include <liburing.h>"
+.B #include <liburing.h>
 .PP
-.BI "unsigned io_uring_sq_ready(const struct io_uring *ring)"
+.BI "unsigned io_uring_sq_ready(const struct io_uring *" ring ");"
 .fi
-.PP
 .SH DESCRIPTION
 .PP
-The io_uring_sq_ready() function retuns the number of unconsumed (if SQPOLL) or
-unsubmitted entries that exist in the SQ ring belonging to the
+The
+.BR io_uring_sq_ready (3)
+function returns the number of unconsumed (if SQPOLL) or unsubmitted entries
+that exist in the SQ ring belonging to the
 .I ring
 param.
 
+Usage of this function only applies if the ring has been setup with
+.B IORING_SETUP_SQPOLL,
+where request submissions, and hence consumption from the SQ ring, happens
+through a polling thread.
+
 .SH RETURN VALUE
 Returns the number of unconsumed or unsubmitted entries in the  SQ ring.
 .SH SEE ALSO
-.BR io_uring_cq_ready (3)
+.BR io_uring_cq_ready (3)

data/vendor/liburing/man/io_uring_sq_space_left.3

@@ -2,24 +2,24 @@
 .\"
 .\" SPDX-License-Identifier: LGPL-2.0-or-later
 .\"
-.TH io_uring_sq_space-left "January 25, 2022" "liburing-2.1" "liburing Manual"
+.TH io_uring_sq_space-left 3 "January 25, 2022" "liburing-2.1" "liburing Manual"
 .SH NAME
-io_uring_sq_space_left - free space in the SQ ring
+io_uring_sq_space_left \- free space in the SQ ring
 .SH SYNOPSIS
 .nf
-.BR "#include <liburing.h>"
+.B #include <liburing.h>
 .PP
-.BI "unsigned io_uring_sq_space_left(const struct io_uring *ring)"
+.BI "unsigned io_uring_sq_space_left(const struct io_uring *" ring ");"
 .fi
-.PP
 .SH DESCRIPTION
 .PP
-The io_uring_sq_space_left() function retuns how much space is left in the
-SQ ring belonging to the
+The
+.BR io_uring_sq_space_left (3)
+function returns how much space is left in the SQ ring belonging to the
 .I ring
 param.
 
 .SH RETURN VALUE
-Returns the free space in the SQ ring.
+Returns the number of availables entries in the SQ ring.
 .SH SEE ALSO
-.BR io_uring_sq_ready (3)
+.BR io_uring_sq_ready (3)

data/vendor/liburing/man/io_uring_sqe_set_data.3

@@ -4,27 +4,45 @@
 .\"
 .TH io_uring_sqe_set_data 3 "November 15, 2021" "liburing-2.1" "liburing Manual"
 .SH NAME
-io_uring_sqe_set_data - set user data for submission queue event
+io_uring_sqe_set_data \- set user data for submission queue event
 .SH SYNOPSIS
 .nf
-.BR "#include <liburing.h>"
+.B #include <liburing.h>
 .PP
-.BI "void io_uring_sqe_set_data(struct io_uring_sqe *sqe,"
-.BI "                           void *user_data)"
+.BI "void io_uring_sqe_set_data(struct io_uring_sqe *" sqe ","
+.BI "                           void *" user_data ");"
+.BI "
+.BI "void io_uring_sqe_set_data64(struct io_uring_sqe *" sqe ","
+.BI "                             __u64 " data ");"
 .fi
-.PP
 .SH DESCRIPTION
 .PP
-The io_uring_sqe_set_data() function stores a
+The
+.BR io_uring_sqe_set_data (3)
+function stores a
 .I user_data
 pointer with the submission queue entry
-.I sqe.
+.IR sqe .
+
+The
+.BR io_uring_sqe_set_data64 (3)
+function stores a 64-bit
+.I data
+value with the submission queue entry
+.IR sqe .
 
-After the caller has requested an submission queue entry (SQE) with io_uring_get_sqe(),
-he can associate a data pointer with the SQE. Once the completion arrives, the
-function io_uring_cqe_get_data() can be called to identify the user request.
+After the caller has requested a submission queue entry (SQE) with
+.BR io_uring_get_sqe (3) ,
+they can associate a data pointer or value with the SQE. Once the completion
+arrives, the function
+.BR io_uring_cqe_get_data (3)
+or
+.BR io_uring_cqe_get_data64 (3)
+can be called to retrieve the data pointer or value associated with the
+submitted request.
 
 .SH RETURN VALUE
 None
 .SH SEE ALSO
-.BR io_uring_get_sqe (3),  io_uring_cqe_get_data (3)
+.BR io_uring_get_sqe (3),
+.BR io_uring_cqe_get_data (3)

data/vendor/liburing/man/io_uring_sqe_set_data64.3

@@ -0,0 +1 @@
+io_uring_sqe_set_data.3

data/vendor/liburing/man/io_uring_sqe_set_flags.3

@@ -2,21 +2,22 @@
 .\"
 .\" SPDX-License-Identifier: LGPL-2.0-or-later
 .\"
-.TH io_uring_sqe_set_flags "January 25, 2022" "liburing-2.1" "liburing Manual"
+.TH io_uring_sqe_set_flags 3 "January 25, 2022" "liburing-2.1" "liburing Manual"
 .SH NAME
-io_uring_sqe_set_flags - set flags for submission queue entry
+io_uring_sqe_set_flags \- set flags for submission queue entry
 .SH SYNOPSIS
 .nf
-.BR "#include <liburing.h>"
+.B #include <liburing.h>
 .PP
-.BI "void io_uring_sqe_set_flags(struct io_uring_sqe *sqe,"
-.BI "                            unsigned flags)"
+.BI "void io_uring_sqe_set_flags(struct io_uring_sqe *" sqe ","
+.BI "                            unsigned " flags ");"
 .fi
-.PP
 .SH DESCRIPTION
 .PP
-The io_uring_sqe_set_flags() function allows the caller to change the
-behavior of the submission queue entry by specifying flags. It enables the
+The
+.BR io_uring_sqe_set_flags (3)
+function allows the caller to change the behavior of the submission queue entry
+by specifying flags. It enables the
 .I flags
 belonging to the
 .I sqe
@@ -34,7 +35,10 @@ Normal operation for io_uring is to try and issue an sqe as non-blocking first,
 and if that fails, execute it in an async manner. To support more efficient
 overlapped operation of requests that the application knows/assumes will
 always (or most of the time) block, the application can ask for an sqe to be
-issued async from the start.
+issued async from the start. Note that this flag immediately causes the SQE
+to be offloaded to an async helper thread with no initial non-blocking attempt.
+This may be less efficient and should not be used liberally or without
+understanding the performance and efficiency tradeoffs.
 .TP
 .B IOSQE_IO_LINK
 When this flag is specified, the SQE forms a link with the next SQE in the
@@ -46,15 +50,38 @@ last SQE in a submission has this flag set, it will still terminate the current
 chain. This flag has no effect on previous SQE submissions, nor does it impact
 SQEs that are outside of the chain tail. This means that multiple chains can be
 executing in parallel, or chains and individual SQEs. Only members inside the
-chain are serialized. A chain of SQEs will be broken, if any request in that
+chain are serialized. A chain of SQEs will be broken if any request in that
 chain ends in error.
 .TP
+.B IOSQE_IO_HARDLINK
+Like
+.B IOSQE_IO_LINK ,
+except the links aren't severed if an error or unexpected result occurs.
+.TP
 .B IOSQE_IO_DRAIN
 When this flag is specified, the SQE will not be started before previously
 submitted SQEs have completed, and new SQEs will not be started before this
 one completes.
+.TP
+.B IOSQE_CQE_SKIP_SUCCESS
+Request that no CQE be generated for this request, if it completes successfully.
+This can be useful in cases where the application doesn't need to know when
+a specific request completed, if it completed successfully.
+.TP
+.B IOSQE_BUFFER_SELECT
+If set, and if the request types supports it, select an IO buffer from the
+indicated buffer group. This can be used with requests that read or receive
+data from a file or socket, where buffer selection is deferred until the kernel
+is ready to transfer data, instead of when the IO is originally submitted. The
+application must also set the
+.I buf_group
+field in the SQE, indicating which previously registered buffer group to select
+a buffer from.
 
 .SH RETURN VALUE
 None
 .SH SEE ALSO
-.BR io_uring_submit (3),  io_uring_register(3)
+.BR io_uring_submit (3),
+.BR io_uring_register (3)
+.BR io_uring_register_buffers (3)
+.BR io_uring_register_buf_ring (3)

data/vendor/liburing/man/io_uring_sqring_wait.3

@@ -2,29 +2,33 @@
 .\"
 .\" SPDX-License-Identifier: LGPL-2.0-or-later
 .\"
-.TH io_uring_sqring_wait "January 25, 2022" "liburing-2.1" "liburing Manual"
+.TH io_uring_sqring_wait 3 "January 25, 2022" "liburing-2.1" "liburing Manual"
 .SH NAME
-io_uring_sqring_wait - wait for free space in the SQ ring
+io_uring_sqring_wait \- wait for free space in the SQ ring
 .SH SYNOPSIS
 .nf
-.BR "#include <liburing.h>"
+.B #include <liburing.h>
 .PP
-.BI "int io_uring_sqring_wait(struct io_uring *ring)"
+.BI "int io_uring_sqring_wait(struct io_uring *" ring ");"
 .fi
-.PP
 .SH DESCRIPTION
 .PP
-The function io_uring_sqring_wait() allows the caller to wait for space
-to free up in the SQ ring belonging to the
+The function
+.BR io_uring_sqring_wait (3)
+allows the caller to wait for space to free up in the SQ ring belonging to the
 .I ring
 param, which happens when the kernel side thread
 has consumed one or more entries. If the SQ ring is currently non-full,
 no action is taken.
 
-This feature can only be used when SQPOLL is enabled.
+This feature can only be used when the ring has been setup with
+.B IORING_SETUP_SQPOLL
+and hence is using an offloaded approach to request submissions.
 
 .SH RETURN VALUE
 On success it returns the free space. If the kernel does not support the
 feature, -EINVAL is returned.
 .SH SEE ALSO
-.BR io_uring_submit (3),  io_uring_wait_cqe (3),  io_uring_wait_cqes (3)
+.BR io_uring_submit (3),
+.BR io_uring_wait_cqe (3),
+.BR io_uring_wait_cqes (3)

data/vendor/liburing/man/io_uring_submit.3

@@ -4,26 +4,43 @@
 .\"
 .TH io_uring_submit 3 "November 15, 2021" "liburing-2.1" "liburing Manual"
 .SH NAME
-io_uring_submit - submit requests to the submission queue
-.fi
+io_uring_submit \- submit requests to the submission queue
 .SH SYNOPSIS
 .nf
-.BR "#include <liburing.h>"
-.PP
-.BI "int io_uring_submit(struct io_uring *ring)"
+.B #include <liburing.h>
 .PP
+.BI "int io_uring_submit(struct io_uring *" ring ");"
+.fi
 .SH DESCRIPTION
 .PP
-The io_uring_submit() function submits the next events to the submission
-queue belonging to the
-.I ring.
+The
+.BR io_uring_submit (3)
+function submits the next events to the submission queue belonging to the
+.IR ring .
 
-After the caller retrieves a submission queue entry (SQE) with io_uring_get_sqe(),
-prepares the SQE, it can be submitted with io_uring_submit().
+After the caller retrieves a submission queue entry (SQE) with
+.BR io_uring_get_sqe (3)
+and prepares the SQE using one of the provided helpers, it can be submitted with
+.BR io_uring_submit (3) .
 
 .SH RETURN VALUE
 On success
 .BR io_uring_submit (3)
-returns the number of submitted submission queue entries. On failure it returns -errno.
+returns the number of submitted submission queue entries. On failure it returns
+.BR -errno .
+.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
+valid until completion. Once a request has been submitted, the in-kernel
+state is stable. Very early kernels (5.4 and earlier) required state to be
+stable until the completion occurred. Applications can test for this
+behavior by inspecting the
+.B IORING_FEAT_SUBMIT_STABLE
+flag passed back from
+.BR io_uring_queue_init_params (3).
+In general, the man pages for the individual prep helpers will have a note
+mentioning this fact as well, if required for the given command.
 .SH SEE ALSO
-.BR io_uring_get_sqe (3),  io_uring_submit_and_wait (3), io_uring_submit_and_wait_timeout (3)
+.BR io_uring_get_sqe (3),
+.BR io_uring_submit_and_wait (3),
+.BR io_uring_submit_and_wait_timeout (3)

data/vendor/liburing/man/io_uring_submit_and_get_events.3

@@ -0,0 +1,31 @@
+.\" Copyright (C), 2022  dylany
+.\" You may distribute this file under the terms of the GNU Free
+.\" Documentation License.
+.TH io_uring_submit_and_get_events 3 "September 5, 2022" "liburing-2.3" "liburing Manual"
+.SH NAME
+io_uring_submit_and_get_events \- submit requests to the submission queue and flush completions
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "int io_uring_submit_and_get_events(struct io_uring *" ring ");"
+.fi
+
+.SH DESCRIPTION
+The
+.BR io_uring_submit_and_get_events (3)
+function submits the next events to the submission queue as with
+.BR io_uring_submit (3) .
+After submission it will flush CQEs as with
+.BR io_uring_get_events (3) .
+
+The benefit of this function is that it does both with only one system call.
+
+.SH RETURN VALUE
+On success
+.BR io_uring_submit_and_get_events (3)
+returns the number of submitted submission queue entries. On failure it returns
+.BR -errno .
+.SH SEE ALSO
+.BR io_uring_submit (3),
+.BR io_uring_get_events (3)

data/vendor/liburing/man/io_uring_submit_and_wait.3

@@ -4,31 +4,35 @@
 .\"
 .TH io_uring_submit_and_wait 3 "November 15, 2021" "liburing-2.1" "liburing Manual"
 .SH NAME
-io_uring_submit_and_wait - submit requests to the submission queue and wait for completion
-.fi
+io_uring_submit_and_wait \- submit requests to the submission queue and wait for completion
 .SH SYNOPSIS
 .nf
-.BR "#include <liburing.h>"
+.B #include <liburing.h>
 .PP
-.BI "int io_uring_submit_and_wait(struct io_uring *ring,"
+.BI "int io_uring_submit_and_wait(struct io_uring *" ring ","
+.BI "                             unsigned " wait_nr ");"
 .fi
-.BI "                             unsigned wait_nr)"
-.PP
 .SH DESCRIPTION
 .PP
-The io_uring_submit_and_wait() function submits the next events to the submission
-queue belonging to the
+The
+.BR io_uring_submit_and_wait (3)
+function submits the next requests from the submission queue belonging to the
 .I ring
 and waits for
 .I wait_nr
 completion events.
 
-After the caller retrieves a submission queue entry (SQE) with io_uring_get_sqe(),
-prepares the SQE, it can be submitted with io_uring_submit_and_wait().
+After the caller retrieves a submission queue entry (SQE) with
+.BR io_uring_get_sqe (3)
+and prepares the SQE, it can be submitted with
+.BR io_uring_submit_and_wait (3) .
 
 .SH RETURN VALUE
 On success
 .BR io_uring_submit_and_wait (3)
-returns the number of submitted submission queue entries. On failure it returns -errno.
+returns the number of submitted submission queue entries. On failure it returns
+.BR -errno .
 .SH SEE ALSO
-.BR io_uring_get_sqe (3),  io_uring_submit (3), io_uring_submit_and_wait_timeout (3)
+.BR io_uring_get_sqe (3),
+.BR io_uring_submit (3),
+.BR io_uring_submit_and_wait_timeout (3)

data/vendor/liburing/man/io_uring_submit_and_wait_timeout.3

@@ -4,46 +4,53 @@
 .\"
 .TH io_uring_submit_and_wait_timeout 3 "November 15, 2021" "liburing-2.1" "liburing Manual"
 .SH NAME
-io_uring_submit_and_wait_timeout - submit requests to the submission queue and
+io_uring_submit_and_wait_timeout \- submit requests to the submission queue and
 wait for the completion with timeout
-.fi
 .SH SYNOPSIS
 .nf
-.BR "#include <liburing.h>"
+.B #include <liburing.h>
 .PP
-.BI "int io_uring_submit_and_wait_timeout(struct io_uring *ring,"
-.fi
-.BI "                                     struct io_uring_cqe **cqe_ptr,"
-.fi
-.BI "                                     unsigned wait_nr,"
+.BI "int io_uring_submit_and_wait_timeout(struct io_uring *" ring ","
+.BI "                                     struct io_uring_cqe **" cqe_ptr ","
+.BI "                                     unsigned " wait_nr ","
+.BI "                                     struct __kernel_timespec *" ts ","
+.BI "                                     sigset_t *" sigmask ");"
 .fi
-.BI "                                     struct __kernel_timespec *ts,"
-.fi
-.BI "                                     sigset_t *sigmask)"
-.PP
 .SH DESCRIPTION
 .PP
-The io_uring_submit_and_wait_timeout() function submits the next events to the submission
-queue belonging to the
+The
+.BR io_uring_submit_and_wait_timeout (3)
+function submits the next requests from the submission queue belonging to the
 .I ring
 and waits for
 .I wait_nr
-completion events or until the timeout
+completion events, or until the timeout
 .I ts
-expires.The completion events are stored in the
-.I cqe_ptr array.
-The
+expires. The completion events are stored in the
+.I cqe_ptr
+array. The
 .I sigmask
 specifies the set of signals to block. The prevailing signal mask is restored
 before returning.
 
-After the caller retrieves a submission queue entry (SQE) with io_uring_get_sqe(),
-prepares the SQE, it can be submitted with io_uring_submit_and_wait_timeout().
-
+After the caller retrieves a submission queue entry (SQE) with
+.BR io_uring_get_sqe (3)
+and prepares the SQE, it can be submitted with
+.BR io_uring_submit_and_wait_timeout (3) .
 
 .SH RETURN VALUE
 On success
 .BR io_uring_submit_and_wait_timeout (3)
-returns the number of submitted submission queue entries. On failure it returns -errno.
+returns the number of submitted submission queue entries. On failure it returns
+.BR -errno .
+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_get_sqe (3),  io_uring_submit (3), io_uring_submit_and_wait (3), io_uring_wait_cqe (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)