summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--man/io_uring_enter.2133
1 files changed, 71 insertions, 62 deletions
diff --git a/man/io_uring_enter.2 b/man/io_uring_enter.2
index 4e0ab4f..344d212 100644
--- a/man/io_uring_enter.2
+++ b/man/io_uring_enter.2
@@ -14,7 +14,7 @@ io_uring_enter \- initiate and/or complete asynchronous I/O
.PP
.BI "int io_uring_enter(unsigned int " fd ", unsigned int " to_submit ,
.BI " unsigned int " min_complete ", unsigned int " flags ,
-.BI " sigset_t *" sig);
+.BI " sigset_t *" sig );
.fi
.PP
.SH DESCRIPTION
@@ -22,20 +22,20 @@ io_uring_enter \- initiate and/or complete asynchronous I/O
.BR io_uring_enter ()
is used to initiate and complete I/O using the shared submission and
completion queues setup by a call to
-.BR io_uring_setup(2).
+.BR io_uring_setup (2).
A single call can both submit new I/O and wait for completions of I/O
initiated by this call or previous calls to
.BR io_uring_enter ().
.I fd
is the file descriptor returned by
-.BR io_uring_setup(2).
+.BR io_uring_setup (2).
.I to_submit
specifies the number of I/Os to submit from the submission queue. If
the
.B IORING_ENTER_GETEVENTS
bit is set in
-.I flags,
+.IR flags ,
then the system call will attempt to wait for
.I min_complete
event completions before returning. If the io_uring instance was
@@ -69,15 +69,16 @@ private copy of it.
.I sig
is a pointer to a signal mask (see
-.BR sigprocmask (2)); if
+.BR sigprocmask (2));
+if
.I sig
is not NULL,
.BR io_uring_enter ()
first replaces the current signal mask by the one pointed to by
-.I sig,
+.IR sig ,
then waits for events to become available in the completion queue, and
then restores the original signal mask. The following
-.BI io_uring_enter ()
+.BR io_uring_enter ()
call:
.PP
.in +4n
@@ -138,30 +139,30 @@ The
.I opcode
describes the operation to be performed. It can be one of:
.TP
-.BR IORING_OP_NOP
+.B IORING_OP_NOP
Do not perform any I/O. This is useful for testing the performance of
the io_uring implementation itself.
.TP
-.BR IORING_OP_READV
+.B IORING_OP_READV
.TP
-.BR IORING_OP_WRITEV
+.B IORING_OP_WRITEV
Vectored read and write operations, similar to
-.BR preadv2(2)
+.BR preadv2 (2)
and
-.BR pwritev2(2).
+.BR pwritev2 (2).
.TP
-.BR IORING_OP_READ_FIXED
+.B IORING_OP_READ_FIXED
.TP
-.BR IORING_OP_WRITE_FIXED
+.B IORING_OP_WRITE_FIXED
Read from or write to pre-mapped buffers. See
-.BR io_uring_register(2)
+.BR io_uring_register (2)
for details on how to setup a context for fixed reads and writes.
.TP
-.BR IORING_OP_FSYNC
+.B IORING_OP_FSYNC
File sync. See also
-.BR fsync(2).
+.BR fsync (2).
Note that, while I/O is initiated in the order in which it appears in
the submission queue, completions are unordered. For example, an
application which places a write I/O followed by an fsync in the
@@ -171,23 +172,23 @@ the write is issued to the storage. The same is also true for
previously issued writes that have not completed prior to the fsync.
.TP
-.BR IORING_OP_POLL_ADD
+.B IORING_OP_POLL_ADD
Poll the
.I fd
specified in the submission queue entry for the events
specified in the
.I poll_events
field. Unlike poll or epoll without
-.B EPOLLONESHOT,
+.BR EPOLLONESHOT ,
this interface always works in one shot mode. That is, once the poll
operation is completed, it will have to be resubmitted.
.TP
-.BR IORING_OP_POLL_REMOVE
+.B IORING_OP_POLL_REMOVE
Remove an existing poll request. If found, the
.I res
field of the
-.I struct io_uring_cqe
+.I "struct io_uring_cqe"
will contain 0. If not found,
.I res
will contain
@@ -203,12 +204,12 @@ When this flag is specified,
is an index into the files array registered with the io_uring instance (see the
.B IORING_REGISTER_FILES
section of the
-.BR io_uring_register(2)
+.BR io_uring_register (2)
man page).
.I ioprio
specifies the I/O priority. See
-.BR ioprio_get(2)
+.BR ioprio_get (2)
for a description of Linux I/O priorities.
.I fd
@@ -218,7 +219,7 @@ performed, with the exception noted above.
If the operation is one of
.B IORING_OP_READ_FIXED
or
-.B IORING_OP_WRITE_FIXED,
+.BR IORING_OP_WRITE_FIXED ,
.I addr
and
.I len
@@ -227,17 +228,17 @@ must fall within the buffer located at
in the fixed buffer array. If the operation is either
.B IORING_OP_READV
or
-.B IORING_OP_WRITEV,
+.BR IORING_OP_WRITEV ,
then
.I addr
points to an iovec array of
.I len
entries.
-.I rw_flags,
+.IR rw_flags ,
specified for read and write operations, contains a bitwise OR of
per-I/O flags, as described in the
-.BR preadv2(2)
+.BR preadv2 (2)
man page.
The
@@ -249,13 +250,13 @@ to provide data sync only semantics. See the descriptions of
and
.B O_DSYNC
in the
-.BR open(2)
+.BR open (2)
manual page for more information.
The bits that may be set in
.I poll_events
are defined in \fI<poll.h>\fP, and documented in
-.BR poll(2).
+.BR poll (2).
.I user_data
is an application-supplied value that will be copied into
@@ -267,8 +268,9 @@ buffers were registered
Once the submission queue entry is initialized, I/O is submitted by
placing the index of the submission queue entry into the tail of the
submission queue. After one or more indexes are added to the queue,
-and the queue tail is advanced, the io_uring_enter(2) system call can
-be invoked to initiate the I/O.
+and the queue tail is advanced, the
+.BR io_uring_enter (2)
+system call can be invoked to initiate the I/O.
Completions use the following data structure:
.PP
@@ -296,9 +298,9 @@ is the operation-specific result.
.PP
For read and write opcodes, the
return values match those documented in the
-.BR preadv2(2)
+.BR preadv2 (2)
and
-.BR pwritev2(2)
+.BR pwritev2 (2)
man pages.
Return codes for the io_uring-specific opcodes are documented in the
description of the opcodes above.
@@ -319,21 +321,21 @@ is set appropriately.
.PP
.SH ERRORS
.TP
-.BR EAGAIN
+.B EAGAIN
The kernel was unable to allocate memory for the request.
.TP
-.BR EBADF
+.B EBADF
The
.I fd
field in the submission queue entry is invalid, or the
.B IOSQE_FIXED_FILE
flag was set in the submission queue entry, but no files were registered
-with the io_uring instance
+with the io_uring instance.
.TP
-.BR EFAULT
+.B EFAULT
buffer is outside of the process' accessible address space
.TP
-.BR EFAULT
+.B EFAULT
.B IORING_OP_READ_FIXED
or
.B IORING_OP_WRITE_FIXED
@@ -346,55 +348,60 @@ by
and
.I len
does not fit within the buffer registered at
-.I buf_index
+.IR buf_index .
.TP
-.BR EINVAL
+.B EINVAL
The
.I index
member of the submission queue entry is invalid.
.TP
-.BR EINVAL
-the
+.B EINVAL
+The
.I flags
field or
.I opcode
-in a submission queue entry is invalid
+in a submission queue entry is invalid.
.TP
-.BR EINVAL
+.B EINVAL
.B IORING_OP_NOP
was specified in the submission queue entry, but the io_uring context
-was setup for polling (
-.B IORING_SETUP_IOPOLL
-was specified in the call to io_uring_setup)
+was setup for polling
+.RB ( IORING_SETUP_IOPOLL
+was specified in the call to io_uring_setup).
.TP
-.BR EINVAL
+.B EINVAL
.B IORING_OP_READV
or
.B IORING_OP_WRITEV
was specified in the submission queue entry, but the io_uring instance
has fixed buffers registered.
.TP
-.BR EINVAL
+.B EINVAL
.B IORING_OP_READ_FIXED
or
.B IORING_OP_WRITE_FIXED
was specified in the submission queue entry, and the
.I buf_index
-is invalid
+is invalid.
.TP
-.BR EINVAL
-.B IORING_OP_READV, IORING_OP_WRITEV, IORING_OP_READ_FIXED,
+.B EINVAL
+.BR IORING_OP_READV ,
+.BR IORING_OP_WRITEV ,
+.BR IORING_OP_READ_FIXED ,
.B IORING_OP_WRITE_FIXED
or
.B IORING_OP_FSYNC
was specified in the submission queue entry, but the io_uring instance
was configured for IOPOLLing, or any of
-.I addr, ioprio, off, len,
+.IR addr ,
+.IR ioprio ,
+.IR off ,
+.IR len ,
or
.I buf_index
was set in the submission queue entry.
.TP
-.BR EINVAL
+.B EINVAL
.B IORING_OP_POLL_ADD
or
.B IORING_OP_POLL_REMOVE
@@ -402,14 +409,16 @@ was specified in the
.I opcode
field of the submission queue entry, but the io_uring instance was
configured for busy-wait polling
-.B (IORING_SETUP_IOPOLL),
+.RB ( IORING_SETUP_IOPOLL ),
or any of
-.I ioprio, off, len
+.IR ioprio ,
+.IR off ,
+.IR len ,
or
.I buf_index
was non-zero in the submission queue entry.
.TP
-.BR EINVAL
+.B EINVAL
.B IORING_OP_POLL_ADD
was specified in the
.I opcode
@@ -417,13 +426,13 @@ field of the submission queue entry, and the
.I addr
field was non-zero.
.TP
-.BR ENXIO
-the io_uring instance is in the process of being torn down
+.B ENXIO
+The io_uring instance is in the process of being torn down.
.TP
-.BR EOPNOTSUPP
+.B EOPNOTSUPP
.I fd
-does not refer to an io_uring instance
+does not refer to an io_uring instance.
.TP
-.BR EOPNOTSUPP
+.B EOPNOTSUPP
.I opcode
is valid, but not supported by this kernel.