diff options
| -rw-r--r-- | man/io_uring_enter.2 | 133 |
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. |