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 <linux/io_uring.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() system call registers user buffers or files for
16 use in an io_uring(7) instance referenced by fd. Registering files or
17 user buffers allows the kernel to take long term references to internal
18 data structures or create long term mappings of application memory,
19 greatly reducing per-I/O overhead.
20 fd is the file descriptor returned by a call to io_uring_setup(2).
22 opcode can be one of:
23 IORING_REGISTER_BUFFERS
26 arg points to a struct iovec array of nr_args entries. The buf‐
27 fers associated with the iovecs will be locked in memory and
28 charged against the user's RLIMIT_MEMLOCK resource limit. See
29 getrlimit(2) for more information. Additionally, there is a
30 size limit of 1GiB per buffer. Currently, the buffers must be
31 anonymous, non-file-backed memory, such as that returned by mal‐
32 loc(3) or mmap(2) with the MAP_ANONYMOUS flag set. It is
33 expected that this limitation will be lifted in the future. Huge
34 pages are supported as well. Note that the entire huge page will
35 be pinned in the kernel, even if only a portion of it is used.
36 After a successful call, the supplied buffers are mapped into
38 the kernel and eligible for I/O. To make use of them, the
39 application must specify the IORING_OP_READ_FIXED or IOR‐
40 ING_OP_WRITE_FIXED opcodes in the submission queue entry (see
41 the struct io_uring_sqe definition in io_uring_enter(2)), and
42 set the buf_index field to the desired buffer index. The memory
43 range described by the submission queue entry's addr and len
44 fields must fall within the indexed buffer.
45 It is perfectly valid to setup a large buffer and then only use
47 part of it for an I/O, as long as the range is within the origi‐
48 nally mapped region.
49 An application can increase or decrease the size or number of
51 registered buffers by first unregistering the existing buffers,
52 and then issuing a new call to io_uring_register() with the new
53 buffers.
54 Note that registering buffers will wait for the ring to idle. If
56 the application currently has requests in-flight, the registra‐
57 tion will wait for those to finish before proceeding.
58 An application need not unregister buffers explicitly before
60 shutting down the io_uring instance. Available since 5.1.
61 IORING_UNREGISTER_BUFFERS
64 This operation takes no argument, and arg must be passed as
65 NULL. All previously registered buffers associated with the
66 io_uring instance will be released. Available since 5.1.
67 IORING_REGISTER_FILES
70 Register files for I/O. arg contains a pointer to an array of
71 nr_args file descriptors (signed 32 bit integers).
72 To make use of the registered files, the IOSQE_FIXED_FILE flag
74 must be set in the flags member of the struct io_uring_sqe, and
75 the fd member is set to the index of the file in the file
76 descriptor array.
77 The file set may be sparse, meaning that the fd field in the
79 array may be set to -1. See IORING_REGISTER_FILES_UPDATE for
80 how to update files in place.
81 Note that registering files will wait for the ring to idle. If
83 the application currently has requests in-flight, the registra‐
84 tion will wait for those to finish before proceeding. See IOR‐
85 ING_REGISTER_FILES_UPDATE for how to update an existing set
86 without that limitation.
87 Files are automatically unregistered when the io_uring instance
89 is torn down. An application need only unregister if it wishes
90 to register a new set of fds. Available since 5.1.
91 IORING_REGISTER_FILES_UPDATE
94 This operation replaces existing files in the registered file
95 set with new ones, either turning a sparse entry (one where fd
96 is equal to -1) into a real one, removing an existing entry (new
97 one is set to -1), or replacing an existing entry with a new
98 existing entry. arg must contain a pointer to a struct
99 io_uring_files_update, which contains an offset on which to
100 start the update, and an array of file descriptors to use for
101 the update. nr_args must contain the number of descriptors in
102 the passed in array. Available since 5.5.
103 IORING_UNREGISTER_FILES
106 This operation requires no argument, and arg must be passed as
107 NULL. All previously registered files associated with the
108 io_uring instance will be unregistered. Available since 5.1.
109 IORING_REGISTER_EVENTFD
112 It's possible to use eventfd(2) to get notified of completion
113 events on an io_uring instance. If this is desired, an eventfd
114 file descriptor can be registered through this operation. arg
115 must contain a pointer to the eventfd file descriptor, and
116 nr_args must be 1. Available since 5.2.
117 IORING_REGISTER_EVENTFD_ASYNC
120 This works just like IORING_REGISTER_EVENTFD , except notifica‐
121 tions are only posted for events that complete in an async man‐
122 ner. This means that events that complete inline while being
123 submitted do not trigger a notification event. The arguments
124 supplied are the same as for IORING_REGISTER_EVENTFD. Available
125 since 5.6.
126 IORING_UNREGISTER_EVENTFD
129 Unregister an eventfd file descriptor to stop notifications.
130 Since only one eventfd descriptor is currently supported, this
131 operation takes no argument, and arg must be passed as NULL and
132 nr_args must be zero. Available since 5.2.
133 IORING_REGISTER_PROBE
136 This operation returns a structure, io_uring_probe, which con‐
137 tains information about the opcodes supported by io_uring on the
138 running kernel. arg must contain a pointer to a struct
139 io_uring_probe, and nr_args must contain the size of the ops
140 array in that probe struct. The ops array is of the type
141 io_uring_probe_op, which holds the value of the opcode and a
142 flags field. If the flags field has IO_URING_OP_SUPPORTED set,
143 then this opcode is supported on the running kernel. Available
144 since 5.6.
145 IORING_REGISTER_PERSONALITY
148 This operation registers credentials of the running application
149 with io_uring, and returns an id associated with these creden‐
150 tials. Applications wishing to share a ring between separate
151 users/processes can pass in this credential id in the sqe per‐
152 sonality field. If set, that particular sqe will be issued with
153 these credentials. Must be invoked with arg set to NULL and
154 nr_args set to zero. Available since 5.6.
155 IORING_UNREGISTER_PERSONALITY
158 This operation unregisters a previously registered personality
159 with io_uring. nr_args must be set to the id in question, and
160 arg must be set to NULL. Available since 5.6.
161
164 On success, io_uring_register() returns 0. On error, -1 is returned,
165 and errno is set accordingly.
166
169 EBADF One or more fds in the fd array are invalid.
170 EBUSY IORING_REGISTER_BUFFERS or IORING_REGISTER_FILES was specified,
172 but there were already buffers or files registered.
173 EFAULT buffer is outside of the process' accessible address space, or
175 iov_len is greater than 1GiB.
176 EINVAL IORING_REGISTER_BUFFERS or IORING_REGISTER_FILES was specified,
178 but nr_args is 0.
179 EINVAL IORING_REGISTER_BUFFERS was specified, but nr_args exceeds
181 UIO_MAXIOV
182 EINVAL IORING_UNREGISTER_BUFFERS or IORING_UNREGISTER_FILES was speci‐
184 fied, and nr_args is non-zero or arg is non-NULL.
185 EMFILE IORING_REGISTER_FILES was specified and nr_args exceeds the max‐
187 imum allowed number of files in a fixed file set.
188 EMFILE IORING_REGISTER_FILES was specified and adding nr_args file ref‐
190 erences would exceed the maximum allowed number of files the
191 user is allowed to have according to the RLIMIT_NOFILE resource
192 limit and the caller does not have CAP_SYS_RESOURCE capability.
193 Note that this is a per user limit, not per process.
194 ENOMEM Insufficient kernel resources are available, or the caller had a
196 non-zero RLIMIT_MEMLOCK soft resource limit, but tried to lock
197 more memory than the limit permitted. This limit is not
198 enforced if the process is privileged (CAP_IPC_LOCK).
199 ENXIO IORING_UNREGISTER_BUFFERS or IORING_UNREGISTER_FILES was speci‐
201 fied, but there were no buffers or files registered.
202 ENXIO Attempt to register files or buffers on an io_uring instance
204 that is already undergoing file or buffer registration, or is
205 being torn down.
206 EOPNOTSUPP
208 User buffers point to file-backed memory.
209Linux 2019-01-17 IO_URING_REGISTER(2)