1io_uring_register(2) Linux Programmer's Manual io_uring_register(2)
2
6 io_uring_register - register files or user buffers for asynchronous I/O
7
9 #include <liburing.h>
10 int io_uring_register(unsigned int fd, unsigned int opcode,
12 void *arg, unsigned int nr_args);
13
15 The io_uring_register(2) system call registers resources (e.g. user
16 buffers, files, eventfd, personality, restrictions) for use in an
17 io_uring(7) instance referenced by fd. Registering files or user buf‐
18 fers allows the kernel to take long term references to internal data
19 structures or create long term mappings of application memory, greatly
20 reducing per-I/O overhead.
21 fd is the file descriptor returned by a call to io_uring_setup(2). If
23 opcode has the flag IORING_REGISTER_USE_REGISTERED_RING ored into it,
24 fd is instead the index of a registered ring fd.
25 opcode can be one of:
27 IORING_REGISTER_BUFFERS
30 arg points to a struct iovec array of nr_args entries. The buf‐
31 fers associated with the iovecs will be locked in memory and
32 charged against the user's RLIMIT_MEMLOCK resource limit. See
33 getrlimit(2) for more information. Additionally, there is a
34 size limit of 1GiB per buffer. Currently, the buffers must be
35 anonymous, non-file-backed memory, such as that returned by mal‐
36 loc(3) or mmap(2) with the MAP_ANONYMOUS flag set. It is ex‐
37 pected that this limitation will be lifted in the future. Huge
38 pages are supported as well. Note that the entire huge page will
39 be pinned in the kernel, even if only a portion of it is used.
40 After a successful call, the supplied buffers are mapped into
42 the kernel and eligible for I/O. To make use of them, the ap‐
43 plication must specify the IORING_OP_READ_FIXED or IOR‐
44 ING_OP_WRITE_FIXED opcodes in the submission queue entry (see
45 the struct io_uring_sqe definition in io_uring_enter(2)), and
46 set the buf_index field to the desired buffer index. The memory
47 range described by the submission queue entry's addr and len
48 fields must fall within the indexed buffer.
49 It is perfectly valid to setup a large buffer and then only use
51 part of it for an I/O, as long as the range is within the origi‐
52 nally mapped region.
53 An application can increase or decrease the size or number of
55 registered buffers by first unregistering the existing buffers,
56 and then issuing a new call to io_uring_register(2) with the new
57 buffers.