4a700b7e35
This also includes a couple of whitespace cleanups. Most man pages don't leave spaces between directives. Signed-off-by: Jeff Moyer <jmoyer@redhat.com> Signed-off-by: Jens Axboe <axboe@kernel.dk>
198 lines
4.6 KiB
Groff
198 lines
4.6 KiB
Groff
.\" 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
|
|
.TP
|
|
.B EBADF
|
|
One or more fds in the
|
|
.I fd
|
|
array are invalid.
|
|
.TP
|
|
.B EBUSY
|
|
.BR IORING_REGISTER_BUFFERS
|
|
or
|
|
.BR IORING_REGISTER_FILES
|
|
was specified, but there were already buffers or files registered.
|
|
.TP
|
|
.B EFAULT
|
|
buffer is outside of the process' accessible address space, or
|
|
.I iov_len
|
|
is greater than 1GiB.
|
|
.TP
|
|
.B EINVAL
|
|
.BR IORING_REGISTER_BUFFERS
|
|
or
|
|
.BR IORING_REGISTER_FILES
|
|
was specified, but
|
|
.I nr_args
|
|
is 0.
|
|
.TP
|
|
.B EINVAL
|
|
.BR IORING_REGISTER_BUFFERS
|
|
was specified, but
|
|
.I nr_args
|
|
exceeds
|
|
.BR UIO_MAXIOV
|
|
.TP
|
|
.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.
|
|
.TP
|
|
.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
|
|
).
|
|
.TP
|
|
.B ENXIO
|
|
.BR IORING_UNREGISTER_BUFFERS
|
|
or
|
|
.BR IORING_UNREGISTER_FILES
|
|
was specified, but there were no buffers or files registered.
|
|
.TP
|
|
.B EOPNOTSUPP
|
|
User buffers point to file-backed memory.
|