| .\" 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 |
| .IR 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: |
| |
| .TP |
| .B 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. Huge pages are supported as well. Note that the entire huge |
| page will be pinned in the kernel, even if only a portion of it is |
| used. |
| |
| 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. |
| .TP |
| .B 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. |
| |
| .TP |
| .B 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). |
| |
| To make use of the registered files, the |
| .B IOSQE_FIXED_FILE |
| flag must be set in the |
| .I flags |
| member of the |
| .IR "struct io_uring_sqe" , |
| and the |
| .I fd |
| member is set to the index of the file in the file descriptor array. |
| |
| Files are automatically unregistered when the io_uring instance is |
| torn down. An application need only unregister if it wishes to |
| register a new set of fds. |
| .TP |
| .B 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 |
| .B IORING_REGISTER_BUFFERS |
| or |
| .B 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 |
| .B IORING_REGISTER_BUFFERS |
| or |
| .B IORING_REGISTER_FILES |
| was specified, but |
| .I nr_args |
| is 0. |
| .TP |
| .B EINVAL |
| .B IORING_REGISTER_BUFFERS |
| was specified, but |
| .I nr_args |
| exceeds |
| .B UIO_MAXIOV |
| .TP |
| .B EINVAL |
| .B IORING_UNREGISTER_BUFFERS |
| or |
| .B IORING_UNREGISTER_FILES |
| was specified, and |
| .I nr_args |
| is non-zero or |
| .I arg |
| is non-NULL. |
| .TP |
| .B EMFILE |
| .B IORING_REGISTER_FILES |
| was specified and |
| .I nr_args |
| exceeds the maximum allowed number of files in a fixed file set. |
| .TP |
| .B EMFILE |
| .B IORING_REGISTER_FILES |
| was specified and adding |
| .I nr_args |
| file references would exceed the maximum allowed number of files the user |
| is allowed to have according to the |
| .B |
| RLIMIT_NOFILE |
| resource limit and the caller does not have |
| .B CAP_SYS_RESOURCE |
| capability. Note that this is a per user limit, not per process. |
| .TP |
| .B ENOMEM |
| Insufficient kernel resources are available, or the caller had a |
| non-zero |
| .B 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 |
| .RB ( CAP_IPC_LOCK ). |
| .TP |
| .B ENXIO |
| .B IORING_UNREGISTER_BUFFERS |
| or |
| .B IORING_UNREGISTER_FILES |
| was specified, but there were no buffers or files registered. |
| .TP |
| .B ENXIO |
| Attempt to register files or buffers on an io_uring instance that is already |
| undergoing file or buffer registration, or is being torn down. |
| .TP |
| .B EOPNOTSUPP |
| User buffers point to file-backed memory. |