.\" Copyright (C) 2019 Jens Axboe .\" 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 " .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.