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 resources (e.g. user buf‐
16 fers, files, eventfd, personality, restrictions) for use in an io_ur‐
17 ing(7) instance referenced by fd. Registering files or user buffers
18 allows the kernel to take long term references to internal data struc‐
19 tures or create long term mappings of application memory, greatly re‐
20 ducing per-I/O overhead.
21 fd is the file descriptor returned by a call to io_uring_setup(2). op‐
23 code can be one of:
24 IORING_REGISTER_BUFFERS
27 arg points to a struct iovec array of nr_args entries. The buf‐
28 fers associated with the iovecs will be locked in memory and
29 charged against the user's RLIMIT_MEMLOCK resource limit. See
30 getrlimit(2) for more information. Additionally, there is a
31 size limit of 1GiB per buffer. Currently, the buffers must be
32 anonymous, non-file-backed memory, such as that returned by mal‐
33 loc(3) or mmap(2) with the MAP_ANONYMOUS flag set. It is ex‐
34 pected that this limitation will be lifted in the future. Huge
35 pages are supported as well. Note that the entire huge page will
36 be pinned in the kernel, even if only a portion of it is used.
37 After a successful call, the supplied buffers are mapped into
39 the kernel and eligible for I/O. To make use of them, the ap‐
40 plication must specify the IORING_OP_READ_FIXED or IOR‐
41 ING_OP_WRITE_FIXED opcodes in the submission queue entry (see
42 the struct io_uring_sqe definition in io_uring_enter(2)), and
43 set the buf_index field to the desired buffer index. The memory
44 range described by the submission queue entry's addr and len
45 fields must fall within the indexed buffer.
46 It is perfectly valid to setup a large buffer and then only use
48 part of it for an I/O, as long as the range is within the origi‐
49 nally mapped region.
50 An application can increase or decrease the size or number of
52 registered buffers by first unregistering the existing buffers,
53 and then issuing a new call to io_uring_register() with the new
54 buffers.
55 Note that registering buffers will wait for the ring to idle. If
57 the application currently has requests in-flight, the registra‐
58 tion will wait for those to finish before proceeding.
59 An application need not unregister buffers explicitly before
61 shutting down the io_uring instance. Available since 5.1.
62 IORING_UNREGISTER_BUFFERS
65 This operation takes no argument, and arg must be passed as
66 NULL. All previously registered buffers associated with the
67 io_uring instance will be released. Available since 5.1.
68 IORING_REGISTER_FILES
71 Register files for I/O. arg contains a pointer to an array of
72 nr_args file descriptors (signed 32 bit integers).
73 To make use of the registered files, the IOSQE_FIXED_FILE flag
75 must be set in the flags member of the struct io_uring_sqe, and
76 the fd member is set to the index of the file in the file de‐
77 scriptor array.
78 The file set may be sparse, meaning that the fd field in the ar‐
80 ray may be set to -1. See IORING_REGISTER_FILES_UPDATE for how
81 to update files in place.
82 Note that registering files will wait for the ring to idle. If
84 the application currently has requests in-flight, the registra‐
85 tion will wait for those to finish before proceeding. See IOR‐
86 ING_REGISTER_FILES_UPDATE for how to update an existing set
87 without that limitation.
88 Files are automatically unregistered when the io_uring instance
90 is torn down. An application need only unregister if it wishes
91 to register a new set of fds. Available since 5.1.
92 IORING_REGISTER_FILES_UPDATE
95 This operation replaces existing files in the registered file
96 set with new ones, either turning a sparse entry (one where fd
97 is equal to -1) into a real one, removing an existing entry (new
98 one is set to -1), or replacing an existing entry with a new ex‐
99 isting entry.
100 arg must contain a pointer to a struct io_uring_files_update,
102 which contains an offset on which to start the update, and an
103 array of file descriptors to use for the update. nr_args must
104 contain the number of descriptors in the passed in array. Avail‐
105 able since 5.5.
106 File descriptors can be skipped if they are set to IORING_REGIS‐
108 TER_FILES_SKIP. Skipping an fd will not touch the file associ‐
109 ated with the previous fd at that index. Available since 5.12.
110 IORING_UNREGISTER_FILES
114 This operation requires no argument, and arg must be passed as
115 NULL. All previously registered files associated with the
116 io_uring instance will be unregistered. Available since 5.1.
117 IORING_REGISTER_EVENTFD
120 It's possible to use eventfd(2) to get notified of completion
121 events on an io_uring instance. If this is desired, an eventfd
122 file descriptor can be registered through this operation. arg
123 must contain a pointer to the eventfd file descriptor, and
124 nr_args must be 1. Available since 5.2.
125 An application can temporarily disable notifications, coming
127 through the registered eventfd, by setting the IOR‐
128 ING_CQ_EVENTFD_DISABLED bit in the flags field of the CQ ring.
129 Available since 5.8.
130 IORING_REGISTER_EVENTFD_ASYNC
133 This works just like IORING_REGISTER_EVENTFD , except notifica‐
134 tions are only posted for events that complete in an async man‐
135 ner. This means that events that complete inline while being
136 submitted do not trigger a notification event. The arguments
137 supplied are the same as for IORING_REGISTER_EVENTFD. Available
138 since 5.6.
139 IORING_UNREGISTER_EVENTFD
142 Unregister an eventfd file descriptor to stop notifications.
143 Since only one eventfd descriptor is currently supported, this
144 operation takes no argument, and arg must be passed as NULL and
145 nr_args must be zero. Available since 5.2.
146 IORING_REGISTER_PROBE
149 This operation returns a structure, io_uring_probe, which con‐
150 tains information about the opcodes supported by io_uring on the
151 running kernel. arg must contain a pointer to a struct io_ur‐
152 ing_probe, and nr_args must contain the size of the ops array in
153 that probe struct. The ops array is of the type io_ur‐
154 ing_probe_op, which holds the value of the opcode and a flags
155 field. If the flags field has IO_URING_OP_SUPPORTED set, then
156 this opcode is supported on the running kernel. Available since
157 5.6.
158 IORING_REGISTER_PERSONALITY
161 This operation registers credentials of the running application
162 with io_uring, and returns an id associated with these creden‐
163 tials. Applications wishing to share a ring between separate
164 users/processes can pass in this credential id in the sqe per‐
165 sonality field. If set, that particular sqe will be issued with
166 these credentials. Must be invoked with arg set to NULL and
167 nr_args set to zero. Available since 5.6.
168 IORING_UNREGISTER_PERSONALITY
171 This operation unregisters a previously registered personality
172 with io_uring. nr_args must be set to the id in question, and
173 arg must be set to NULL. Available since 5.6.
174 IORING_REGISTER_ENABLE_RINGS
177 This operation enables an io_uring ring started in a disabled
178 state (IORING_SETUP_R_DISABLED was specified in the call to
179 io_uring_setup(2)). While the io_uring ring is disabled, sub‐
180 missions are not allowed and registrations are not restricted.
181 After the execution of this operation, the io_uring ring is en‐
183 abled: submissions and registration are allowed, but they will
184 be validated following the registered restrictions (if any).
185 This operation takes no argument, must be invoked with arg set
186 to NULL and nr_args set to zero. Available since 5.10.
187 IORING_REGISTER_RESTRICTIONS
190 arg points to a struct io_uring_restriction array of nr_args en‐
191 tries.
192 With an entry it is possible to allow an io_uring_register() op‐
194 code, or specify which opcode and flags of the submission queue
195 entry are allowed, or require certain flags to be specified
196 (these flags must be set on each submission queue entry).
197 All the restrictions must be submitted with a single io_ur‐
199 ing_register() call and they are handled as an allowlist (op‐
200 codes and flags not registered, are not allowed).
201 Restrictions can be registered only if the io_uring ring started
203 in a disabled state (IORING_SETUP_R_DISABLED must be specified
204 in the call to io_uring_setup(2)).
205 Available since 5.10.
207
210 On success, io_uring_register() returns 0. On error, -1 is returned,
211 and errno is set accordingly.
212
215 EACCES The opcode field is not allowed due to registered restrictions.
216 EBADF One or more fds in the fd array are invalid.
218 EBADFD IORING_REGISTER_ENABLE_RINGS or IORING_REGISTER_RESTRICTIONS was
220 specified, but the io_uring ring is not disabled.
221 EBUSY IORING_REGISTER_BUFFERS or IORING_REGISTER_FILES or IORING_REG‐
223 ISTER_RESTRICTIONS was specified, but there were already buf‐
224 fers, files, or restrictions registered.
225 EFAULT buffer is outside of the process' accessible address space, or
227 iov_len is greater than 1GiB.
228 EINVAL IORING_REGISTER_BUFFERS or IORING_REGISTER_FILES was specified,
230 but nr_args is 0.
231 EINVAL IORING_REGISTER_BUFFERS was specified, but nr_args exceeds
233 UIO_MAXIOV
234 EINVAL IORING_UNREGISTER_BUFFERS or IORING_UNREGISTER_FILES was speci‐
236 fied, and nr_args is non-zero or arg is non-NULL.
237 EINVAL IORING_REGISTER_RESTRICTIONS was specified, but nr_args exceeds
239 the maximum allowed number of restrictions or restriction opcode
240 is invalid.
241 EMFILE IORING_REGISTER_FILES was specified and nr_args exceeds the max‐
243 imum allowed number of files in a fixed file set.
244 EMFILE IORING_REGISTER_FILES was specified and adding nr_args file ref‐
246 erences would exceed the maximum allowed number of files the
247 user is allowed to have according to the RLIMIT_NOFILE resource
248 limit and the caller does not have CAP_SYS_RESOURCE capability.
249 Note that this is a per user limit, not per process.
250 ENOMEM Insufficient kernel resources are available, or the caller had a
252 non-zero RLIMIT_MEMLOCK soft resource limit, but tried to lock
253 more memory than the limit permitted. This limit is not en‐
254 forced if the process is privileged (CAP_IPC_LOCK).
255 ENXIO IORING_UNREGISTER_BUFFERS or IORING_UNREGISTER_FILES was speci‐
257 fied, but there were no buffers or files registered.
258 ENXIO Attempt to register files or buffers on an io_uring instance
260 that is already undergoing file or buffer registration, or is
261 being torn down.
262 EOPNOTSUPP
264 User buffers point to file-backed memory.
265Linux 2019-01-17 IO_URING_REGISTER(2)