man: add a man page for io_uring_register
Initial content was taken from the kernel commits (Jens Axboe). Signed-off-by: Jeff Moyer <jmoyer@redhat.com> Signed-off-by: Jens Axboe <axboe@kernel.dk>
This commit is contained in:
Jeff Moyer
197
man/io_uring_register.2
Normal file
197
man/io_uring_register.2
Normal file
@@ -0,0 +1,197 @@
|
||||
.\" Copyright (C) 2019 Jens Axboe <axboe@kernel.dk>
|
||||
.\" Copyright (C) 2019 Red Hat, Inc.
|
||||
.\"
|
||||
.\" %%%LICENSE_START(LGPL_V2.1)
|
||||
.\" This file is distributed according to the GNU Lesser General Public License.
|
||||
.\" %%%LICENSE_END
|
||||
.\"
|
||||
.TH IO_URING_REGISTER 2 2019-01-17 "Linux" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
io_uring_register \- register files or user buffers for asynchronous I/O
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
.BR "#include <linux/io_uring.h>"
|
||||
.PP
|
||||
.BI "int io_uring_register(unsigned int " fd ", unsigned int " opcode ,
|
||||
.BI " void *" arg ", unsigned int " nr_args)
|
||||
.fi
|
||||
.PP
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
|
||||
The
|
||||
.BR io_uring_register ()
|
||||
system call registers user buffers or files for use in an
|
||||
.BR io_uring (7)
|
||||
instance referenced by
|
||||
.I fd.
|
||||
Registering files or user buffers allows the kernel to take long term
|
||||
references to internal data structures or create long term mappings of
|
||||
application memory, greatly reducing per-I/O overhead.
|
||||
|
||||
.I fd
|
||||
is the file descriptor returned by a call to
|
||||
.BR io_uring_setup (2).
|
||||
.I opcode
|
||||
can be one of:
|
||||
|
||||
.BR IORING_REGISTER_BUFFERS
|
||||
|
||||
.I arg
|
||||
points to a
|
||||
.I struct iovec
|
||||
array of
|
||||
.I nr_args
|
||||
entries. The buffers associated with the iovecs will be locked in
|
||||
memory and charged against the user's
|
||||
.B RLIMIT_MEMLOCK resource limit. See
|
||||
.BR getrlimit (2)
|
||||
for more information. Additionally, there is a size limit of 1GiB per
|
||||
buffer. Currently, the buffers must be anonymous, non-file-backed
|
||||
memory, such as that returned by
|
||||
.BR malloc (3)
|
||||
or
|
||||
.BR mmap (2)
|
||||
with the
|
||||
.B MAP_ANONYMOUS
|
||||
flag set. It is expected that this limitation will be lifted in the
|
||||
future.
|
||||
|
||||
After a successful call, the supplied buffers are mapped into the
|
||||
kernel and eligible for I/O. To make use of them, the application
|
||||
must specify the
|
||||
.B IORING_OP_READ_FIXED
|
||||
or
|
||||
.B IORING_OP_WRITE_FIXED
|
||||
opcodes in the submission queue entry (see the
|
||||
.I struct io_uring_sqe
|
||||
definition in
|
||||
.BR io_uring_enter (2)),
|
||||
and set the
|
||||
.I buf_index
|
||||
field to the desired buffer index. The memory range described by the
|
||||
submission queue entry's
|
||||
.I addr
|
||||
and
|
||||
.I len
|
||||
fields must fall within the indexed buffer.
|
||||
|
||||
It is perfectly valid to setup a large buffer and then only use part
|
||||
of it for an I/O, as long as the range is within the originally mapped
|
||||
region.
|
||||
|
||||
An application can increase or decrease the size or number of
|
||||
registered buffers by first unregistering the existing buffers, and
|
||||
then issuing a new call to
|
||||
.BR io_uring_register ()
|
||||
with the new buffers.
|
||||
|
||||
An application need not unregister buffers explicitly before shutting
|
||||
down the io_uring instance.
|
||||
|
||||
.BR IORING_UNREGISTER_BUFFERS
|
||||
|
||||
This operation takes no argument, and
|
||||
.I arg
|
||||
must be passed as NULL. All previously registered buffers associated
|
||||
with the io_uring instance will be released.
|
||||
|
||||
.BR IORING_REGISTER_FILES
|
||||
|
||||
Register files for I/O.
|
||||
.I arg
|
||||
contains a pointer to an array of
|
||||
.I nr_args
|
||||
file descriptors (signed 32 bit integers).
|
||||
|
||||
When used, the application must set
|
||||
.B IOSQE_FIXED_FILE
|
||||
in the
|
||||
.I flags
|
||||
member of the
|
||||
.I struct io_uring_sqe.
|
||||
Then,
|
||||
.I fd
|
||||
is set to the index of the buffer in the array supplied to
|
||||
.B IORING_REGISTER_FILES.
|
||||
|
||||
Files are automatically unregistered when the io_uring instance is
|
||||
torn down. An application need only unregister if it wishes to
|
||||
register a few set of fds.
|
||||
|
||||
.BR IORING_UNREGISTER_FILES
|
||||
|
||||
This operation requires no argument, and
|
||||
.I arg
|
||||
must be passed as NULL. All previously registered files associated
|
||||
with the io_uring instance will be unregistered.
|
||||
|
||||
.SH RETURN VALUE
|
||||
|
||||
On success,
|
||||
.BR io_uring_register ()
|
||||
returns 0. On error, -1 is returned, and
|
||||
.I errno
|
||||
is set accordingly.
|
||||
|
||||
.SH ERRORS
|
||||
|
||||
.B EINVAL
|
||||
.BR IORING_REGISTER_BUFFERS
|
||||
or
|
||||
.BR IORING_REGISTER_FILES
|
||||
was specified, but
|
||||
.I nr_args
|
||||
is 0.
|
||||
|
||||
.B EINVAL
|
||||
.BR IORING_REGISTER_BUFFERS
|
||||
was specified, but
|
||||
.I nr_args
|
||||
exceeds
|
||||
.BR UIO_MAXIOV
|
||||
|
||||
.B EINVAL
|
||||
.BR IORING_UNREGISTER_BUFFERS
|
||||
or
|
||||
.BR IORING_UNREGISTER_FILES
|
||||
was specified, and
|
||||
.I nr_args
|
||||
is non-zero or
|
||||
.I arg
|
||||
is non-NULL.
|
||||
|
||||
.B ENXIO
|
||||
.BR IORING_UNREGISTER_BUFFERS
|
||||
or
|
||||
.BR IORING_UNREGISTER_FILES
|
||||
was specified, but there were no buffers or files registered.
|
||||
|
||||
.B EBUSY
|
||||
.BR IORING_REGISTER_BUFFERS
|
||||
or
|
||||
.BR IORING_REGISTER_FILES
|
||||
was specified, but there were already buffers or files registered.
|
||||
|
||||
.B ENOMEM
|
||||
Insufficient kernel resources are available, or the caller had a
|
||||
non-zero
|
||||
.BR RLIMIT_MEMLOCK
|
||||
soft resource limit, but tried to lock more memory than the limit
|
||||
permitted. This limit is not enforced if the process is privileged
|
||||
(
|
||||
.BR CAP_IPC_LOCK
|
||||
).
|
||||
|
||||
.B EBADF
|
||||
One or more fds in the
|
||||
.I fd
|
||||
array are invalid.
|
||||
|
||||
.B EFAULT
|
||||
buffer is outside of the process' accessible address space, or
|
||||
.I iov_len
|
||||
is greater than 1GiB.
|
||||
|
||||
.B EOPNOTSUPP
|
||||
User buffers point to file-backed memory.
|
||||
Reference in New Issue
Block a user