diff options
| -rw-r--r-- | man/io_uring_register.2 | 197 |
1 files changed, 197 insertions, 0 deletions
diff --git a/man/io_uring_register.2 b/man/io_uring_register.2 new file mode 100644 index 0000000..168d600 --- /dev/null +++ b/man/io_uring_register.2 @@ -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. |