summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJens Axboe <axboe@kernel.dk>2022-04-04 14:27:40 -0600
committerJens Axboe <axboe@kernel.dk>2022-04-04 14:27:40 -0600
commitfbd72c3bd426e9284a11840706196d46928142d8 (patch)
tree9631e733d647bbb6be6052b1dae54aeb7a31c1ae
parent215c27ac35d334d6be9c8982b52faf97ff78c26f (diff)
parent30a3c697057e4457aadbd71b282b21a39f578bbd (diff)
downloadliburing-fbd72c3bd426e9284a11840706196d46928142d8.tar.gz
liburing-fbd72c3bd426e9284a11840706196d46928142d8.tar.bz2
Merge branch 'changes-3' of https://github.com/ewyler/liburing
* 'changes-3' of https://github.com/ewyler/liburing: Review and update .3 and .7 man pages
-rw-r--r--man/io_uring.75
-rw-r--r--man/io_uring_cq_advance.38
-rw-r--r--man/io_uring_cqe_seen.38
-rw-r--r--man/io_uring_opcode_supported.32
-rw-r--r--man/io_uring_peek_cqe.32
-rw-r--r--man/io_uring_prep_accept.34
-rw-r--r--man/io_uring_prep_files_update.34
-rw-r--r--man/io_uring_prep_msg_ring.32
-rw-r--r--man/io_uring_prep_provide_buffers.34
-rw-r--r--man/io_uring_prep_read_fixed.39
-rw-r--r--man/io_uring_prep_splice.32
-rw-r--r--man/io_uring_prep_tee.34
-rw-r--r--man/io_uring_prep_timeout.34
-rw-r--r--man/io_uring_prep_timeout_update.32
-rw-r--r--man/io_uring_prep_write.32
-rw-r--r--man/io_uring_prep_write_fixed.38
-rw-r--r--man/io_uring_prep_writev.32
-rw-r--r--man/io_uring_prep_writev2.32
-rw-r--r--man/io_uring_queue_init.36
-rw-r--r--man/io_uring_register_buffers.34
-rw-r--r--man/io_uring_sqe_set_flags.32
-rw-r--r--man/io_uring_submit_and_wait_timeout.32
22 files changed, 45 insertions, 43 deletions
diff --git a/man/io_uring.7 b/man/io_uring.7
index 39865e6..8c71d93 100644
--- a/man/io_uring.7
+++ b/man/io_uring.7
@@ -277,7 +277,8 @@ you need to acquire a submission queue entry (SQE) from the submission
queue (SQ),
fill it up with details of the operation you want to submit and call
.BR io_uring_enter (2).
-If you want to avoid calling
+There are helper functions of the form io_uring_prep_X to enable proper
+setup of the SQE. If you want to avoid calling
.BR io_uring_enter (2),
you have the option of setting up Submission Queue Polling.
.PP
@@ -484,7 +485,7 @@ them to the submission queue. This avoids the
.BR io_uring_enter (2)
call you need to make to tell the kernel to pick SQEs up.
For high-performance applications,
-this means even lesser system call overheads.
+this means even fewer system call overheads.
.SH CONFORMING TO
.B io_uring
is Linux-specific.
diff --git a/man/io_uring_cq_advance.3 b/man/io_uring_cq_advance.3
index c75eaba..5aaf287 100644
--- a/man/io_uring_cq_advance.3
+++ b/man/io_uring_cq_advance.3
@@ -4,12 +4,12 @@
.\"
.TH io_uring_cq_advance 3 "January 25, 2022" "liburing-2.1" "liburing Manual"
.SH NAME
-io_uring_cq_advance - Mark one or more io_uring completion events as processed
+io_uring_cq_advance - Mark one or more io_uring completion events as consumed
.SH SYNOPSIS
.nf
.BR "#include <liburing.h>"
.PP
-.BI "void io_uring_cqe_advance(struct io_uring *" ring ","
+.BI "void io_uring_cq_advance(struct io_uring *" ring ","
.BI " unsigned " nr ");"
.fi
.PP
@@ -19,14 +19,14 @@ The io_uring_cq_advance() function marks
.I nr
IO completions belonging to the
.I ring
-param as processed.
+param as consumed.
After the caller has submitted a request with
.BR io_uring_submit (3),
the application can retrieve the completion with
.BR io_uring_wait_cqe (3),
.BR io_uring_peek_cqe (3),
-or any of the other CQE retrieval helpers, and mark it as processed with
+or any of the other CQE retrieval helpers, and mark it as consumed with
.BR io_uring_cqe_seen (3).
The function
diff --git a/man/io_uring_cqe_seen.3 b/man/io_uring_cqe_seen.3
index dc7f8e4..41d276c 100644
--- a/man/io_uring_cqe_seen.3
+++ b/man/io_uring_cqe_seen.3
@@ -4,7 +4,7 @@
.\"
.TH io_uring_cqe_seen 3 "November 15, 2021" "liburing-2.1" "liburing Manual"
.SH NAME
-io_uring_cqe_seen - Mark io_uring completion event as processed
+io_uring_cqe_seen - Mark io_uring completion event as consumed
.SH SYNOPSIS
.nf
.BR "#include <liburing.h>"
@@ -19,17 +19,17 @@ The io_uring_cqe_seen() function marks the IO completion
.I cqe
belonging to the
.I ring
-param as processed.
+param as consumed.
After the caller has submitted a request with
.BR io_uring_submit (3),
the application can retrieve the completion with
.BR io_uring_wait_cqe (3),
.BR io_uring_peek_cqe (3),
-or any of the other CQE retrieval helpers, and mark it as processed with
+or any of the other CQE retrieval helpers, and mark it as consumed with
.BR io_uring_cqe_seen (3).
-Completions must be marked as completed, so their slot can get reused.
+Completions must be marked as completed so their slot can get reused.
.SH RETURN VALUE
None
.SH SEE ALSO
diff --git a/man/io_uring_opcode_supported.3 b/man/io_uring_opcode_supported.3
index 8afbfc6..293d643 100644
--- a/man/io_uring_opcode_supported.3
+++ b/man/io_uring_opcode_supported.3
@@ -10,7 +10,7 @@ io_uring_opcode_supported - is op code supported?
.BR "#include <liburing.h>"
.PP
.BI "int io_uring_opcode_supported(struct io_uring_probe *" probe ","
-.BI " int " opode ");"
+.BI " int " opcode ");"
.fi
.PP
.SH DESCRIPTION
diff --git a/man/io_uring_peek_cqe.3 b/man/io_uring_peek_cqe.3
index ffd6a60..4c6e507 100644
--- a/man/io_uring_peek_cqe.3
+++ b/man/io_uring_peek_cqe.3
@@ -20,7 +20,7 @@ queue belonging to the
.I ring
param, if one is readily available. On successful return,
.I cqe_ptr
-param is filled with a valud CQE entry.
+param is filled with a valid CQE entry.
This function does not enter the kernel to wait for an event, an event
is only returned if it's already available in the CQ ring.
diff --git a/man/io_uring_prep_accept.3 b/man/io_uring_prep_accept.3
index 970b187..779bcd9 100644
--- a/man/io_uring_prep_accept.3
+++ b/man/io_uring_prep_accept.3
@@ -4,7 +4,7 @@
.\"
.TH io_uring_prep_accept 3 "March 13, 2022" "liburing-2.2" "liburing Manual"
.SH NAME
-io_uring_prep_accept - prepare a accept request
+io_uring_prep_accept - prepare an accept request
.fi
.SH SYNOPSIS
.nf
@@ -41,7 +41,7 @@ and using modifier flags in
For a direct descriptor accept request, the offset is specified by the
.I file_index
argument. Direct descriptors are io_uring private file descriptors. They
-avoid some of the overhead associated with thread shared file tables, and
+avoid some of the overhead associated with thread shared file tables and
can be used in any io_uring request that takes a file descriptor. To do so,
.B IOSQE_FIXED_FILE
must be set in the SQE
diff --git a/man/io_uring_prep_files_update.3 b/man/io_uring_prep_files_update.3
index 0a35e9f..eac1603 100644
--- a/man/io_uring_prep_files_update.3
+++ b/man/io_uring_prep_files_update.3
@@ -29,8 +29,8 @@ in length to update that amount of previously registered files starting at
offset
.I offset.
-One a previously registered file is updated with a new one, the existing
-entry is updated the removed from the table. This operation is equivalent to
+Once a previously registered file is updated with a new one, the existing
+entry is updated and then removed from the table. This operation is equivalent to
first unregistering that entry and then inserting a new one, just bundled into
one combined operation.
diff --git a/man/io_uring_prep_msg_ring.3 b/man/io_uring_prep_msg_ring.3
index 68699cb..a68121f 100644
--- a/man/io_uring_prep_msg_ring.3
+++ b/man/io_uring_prep_msg_ring.3
@@ -10,7 +10,7 @@ io_uring_prep_msg_ring - send a message to another ring
.nf
.BR "#include <liburing.h>"
.PP
-.BI "void io_uring_msg_ring(struct io_uring_sqe *" sqe ","
+.BI "void io_uring_prep_msg_ring(struct io_uring_sqe *" sqe ","
.BI " int " fd ","
.BI " unsigned int " len ","
.BI " __u64 " data ","
diff --git a/man/io_uring_prep_provide_buffers.3 b/man/io_uring_prep_provide_buffers.3
index b18a6d9..bcfe4d8 100644
--- a/man/io_uring_prep_provide_buffers.3
+++ b/man/io_uring_prep_provide_buffers.3
@@ -54,13 +54,13 @@ field.
Different buffer group IDs can be used by the application to have different
sizes or types of buffers available. Once a buffer has been consumed for an
operation, it is no longer known to io_uring. It must be re-provided if so
-desired, or freed by the application if no longer needed.
+desired or freed by the application if no longer needed.
The buffer IDs are internally tracked from
.I bid
and sequentially ascending from that value. If
.B 16
-buffers are provided start with an initial
+buffers are provided and start with an initial
.I bid
of 0, then the buffer IDs will range from
.B 0..15.
diff --git a/man/io_uring_prep_read_fixed.3 b/man/io_uring_prep_read_fixed.3
index 3433c20..2d8dcd9 100644
--- a/man/io_uring_prep_read_fixed.3
+++ b/man/io_uring_prep_read_fixed.3
@@ -33,15 +33,16 @@ at the specified
and with the buffer matching the registered index of
.I buf_index.
-This work just like
+This works just like
.B io_uring_prep_read(3)
-except it requires the user of buffers that have been registered with
-.B io_uring_register_buffers(3). The
+except it requires the use of buffers that have been registered with
+.B io_uring_register_buffers(3).
+The
.I buf
and
.I nbytes
arguments must fall within a region specificed by
-.I buf_index.
+.I buf_index
in the previously registered buffer. The buffer need not be aligned with
the start of the registered buffer.
diff --git a/man/io_uring_prep_splice.3 b/man/io_uring_prep_splice.3
index 6827131..8aea3c1 100644
--- a/man/io_uring_prep_splice.3
+++ b/man/io_uring_prep_splice.3
@@ -17,7 +17,7 @@ io_uring_prep_splice - prepare an splice request
.BI " int " fd_out ","
.BI " int64_t " off_out ","
.BI " unsigned int " nbytes ","
-.BI " int " splice_flags ");"
+.BI " unsigned int " splice_flags ");"
.PP
.SH DESCRIPTION
.PP
diff --git a/man/io_uring_prep_tee.3 b/man/io_uring_prep_tee.3
index 086bc18..8b41a6f 100644
--- a/man/io_uring_prep_tee.3
+++ b/man/io_uring_prep_tee.3
@@ -15,7 +15,7 @@ io_uring_prep_tee - prepare a tee request
.BI " int " fd_in ","
.BI " int " fd_out ","
.BI " unsigned int " nbytes ","
-.BI " int " splice_flags ");"
+.BI " unsigned int " splice_flags ");"
.PP
.SH DESCRIPTION
.PP
@@ -29,7 +29,7 @@ and as output the file descriptor
duplicating
.I nbytes
bytes worth of data.
-.I flags
+.I splice_flags
are modifier flags for the operation. See
.BR tee (2)
for the generic splice flags.
diff --git a/man/io_uring_prep_timeout.3 b/man/io_uring_prep_timeout.3
index fb2a07c..38c4bf5 100644
--- a/man/io_uring_prep_timeout.3
+++ b/man/io_uring_prep_timeout.3
@@ -28,7 +28,7 @@ completion entries. The
.I flags
argument holds modifier flags for the request.
-This request type can either be used as a timeout waking anyone sleeping
+This request type can be used as a timeout waking anyone sleeping
for events on the CQ ring. The
.I flags
argument may contain:
@@ -45,7 +45,7 @@ The boottime clock source should be used.
The realtime clock source should be used.
.TP
.B IORING_TIMEOUT_ETIME_SUCCESS
-Consider an expirted timeout a success in terms of the posted completion.
+Consider an expired timeout a success in terms of the posted completion.
Normally a timeout that triggers would return in a
.B -ETIME
CQE
diff --git a/man/io_uring_prep_timeout_update.3 b/man/io_uring_prep_timeout_update.3
index b35e1f0..a52ba86 100644
--- a/man/io_uring_prep_timeout_update.3
+++ b/man/io_uring_prep_timeout_update.3
@@ -48,7 +48,7 @@ The boottime clock source should be used.
The realtime clock source should be used.
.TP
.B IORING_TIMEOUT_ETIME_SUCCESS
-Consider an expirted timeout a success in terms of the posted completion.
+Consider an expired timeout a success in terms of the posted completion.
Normally a timeout that triggers would return in a
.B -ETIME
CQE
diff --git a/man/io_uring_prep_write.3 b/man/io_uring_prep_write.3
index 817717d..c935f8b 100644
--- a/man/io_uring_prep_write.3
+++ b/man/io_uring_prep_write.3
@@ -36,7 +36,7 @@ incremented by the number of bytes written. See
.BR write (2)
for more details. Note that for an async API, reading and updating the
current file offset may result in unpredictable behavior, unless access
-to the file is serialized. It is not encouraged to use this feature, if it's
+to the file is serialized. It is not encouraged to use this feature if it's
possible to provide the desired IO offset from the application or library.
On files that are not capable of seeking, the offset is ignored.
diff --git a/man/io_uring_prep_write_fixed.3 b/man/io_uring_prep_write_fixed.3
index c9729b4..77143ca 100644
--- a/man/io_uring_prep_write_fixed.3
+++ b/man/io_uring_prep_write_fixed.3
@@ -29,19 +29,19 @@ to start writing
from the buffer
.I buf
at the specified
-.I offset,
+.I offset
and with the buffer matching the registered index of
.I buf_index.
-This work just like
+This works just like
.B io_uring_prep_write(3)
-except it requires the user of buffers that have been registered with
+except it requires the use of buffers that have been registered with
.B io_uring_register_buffers(3). The
.I buf
and
.I nbytes
arguments must fall within a region specificed by
-.I buf_index.
+.I buf_index
in the previously registered buffer. The buffer need not be aligned with
the start of the registered buffer.
diff --git a/man/io_uring_prep_writev.3 b/man/io_uring_prep_writev.3
index 806f4e5..ff1a6d5 100644
--- a/man/io_uring_prep_writev.3
+++ b/man/io_uring_prep_writev.3
@@ -38,7 +38,7 @@ incremented by the number of bytes written. See
.BR write (2)
for more details. Note that for an async API, reading and updating the
current file offset may result in unpredictable behavior, unless access
-to the file is serialized. It is not encouraged to use this feature, if it's
+to the file is serialized. It is not encouraged to use this feature if it's
possible to provide the desired IO offset from the application or library.
On files that are not capable of seeking, the offset is ignored.
diff --git a/man/io_uring_prep_writev2.3 b/man/io_uring_prep_writev2.3
index cceae97..cc646f3 100644
--- a/man/io_uring_prep_writev2.3
+++ b/man/io_uring_prep_writev2.3
@@ -65,7 +65,7 @@ incremented by the number of bytes written. See
.BR write (2)
for more details. Note that for an async API, reading and updating the
current file offset may result in unpredictable behavior, unless access
-to the file is serialized. It is not encouraged to use this feature, if it's
+to the file is serialized. It is not encouraged to use this feature if it's
possible to provide the desired IO offset from the application or library.
On files that are not capable of seeking, the offset is ignored.
diff --git a/man/io_uring_queue_init.3 b/man/io_uring_queue_init.3
index 807d8b4..d2c4d47 100644
--- a/man/io_uring_queue_init.3
+++ b/man/io_uring_queue_init.3
@@ -35,13 +35,13 @@ for the SQ ring. This is adequate for regular file or storage workloads, but
may be too small networked workloads. The SQ ring entries do not impose a limit
on the number of in-flight requests that the ring can support, it merely limits
the number that can be submitted to the kernel in one go (batch). if the CQ
-ring overflows, eg more entries are generated than fits in the ring before the
+ring overflows, e.g. more entries are generated than fits in the ring before the
application can reap them, then the ring enters a CQ ring overflow state. This
is indicated by
.B IORING_SQ_CQ_OVERFLOW
being set in the SQ ring flags. Unless the kernel runs out of available memory,
entries are not dropped, but it is a much slower completion path and will slow
-down request processing. For that reason it should be avoided, and the CQ
+down request processing. For that reason it should be avoided and the CQ
ring sized appropriately for the workload. Setting
.I cq_entries
in
@@ -59,7 +59,7 @@ will point to the shared memory containing the io_uring queues. On failure
is returned.
.I flags
-will be passed through to the io_uring_setup syscall (see
+will be passed through to the io_uring_setup syscall (see
.BR io_uring_setup (2)).
If the
diff --git a/man/io_uring_register_buffers.3 b/man/io_uring_register_buffers.3
index 689de9d..ce5ca4c 100644
--- a/man/io_uring_register_buffers.3
+++ b/man/io_uring_register_buffers.3
@@ -28,8 +28,8 @@ fixed buffers functions.
Registered buffers is an optimization that is useful in conjunction with
.B O_DIRECT
-reads and writes, where maps the specified range into the kernel once when
-the buffer is registered, rather than doing a map and unmap for each IO
+reads and writes, where it maps the specified range into the kernel once when
+the buffer is registered rather than doing a map and unmap for each IO
every time IO is performed to that region. Additionally, it also avoids
manipulating the page reference counts for each IO.
diff --git a/man/io_uring_sqe_set_flags.3 b/man/io_uring_sqe_set_flags.3
index 93a41f3..10ed8d3 100644
--- a/man/io_uring_sqe_set_flags.3
+++ b/man/io_uring_sqe_set_flags.3
@@ -46,7 +46,7 @@ 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_DRAIN
diff --git a/man/io_uring_submit_and_wait_timeout.3 b/man/io_uring_submit_and_wait_timeout.3
index 2fd22ba..299d7b1 100644
--- a/man/io_uring_submit_and_wait_timeout.3
+++ b/man/io_uring_submit_and_wait_timeout.3
@@ -26,7 +26,7 @@ and waits for
.I wait_nr
completion events or until the timeout
.I ts
-expires.The completion events are stored in the
+expires. The completion events are stored in the
.I cqe_ptr array.
The
.I sigmask