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 An application can temporarily disable notifications, coming
119 through the registered eventfd, by setting the IOR‐
120 ING_CQ_EVENTFD_DISABLED bit in the flags field of the CQ ring.
121 Available since 5.8.
122 IORING_REGISTER_EVENTFD_ASYNC
125 This works just like IORING_REGISTER_EVENTFD , except notifica‐
126 tions are only posted for events that complete in an async man‐
127 ner. This means that events that complete inline while being
128 submitted do not trigger a notification event. The arguments
129 supplied are the same as for IORING_REGISTER_EVENTFD. Available
130 since 5.6.
131 IORING_UNREGISTER_EVENTFD
134 Unregister an eventfd file descriptor to stop notifications.
135 Since only one eventfd descriptor is currently supported, this
136 operation takes no argument, and arg must be passed as NULL and
137 nr_args must be zero. Available since 5.2.
138 IORING_REGISTER_PROBE
141 This operation returns a structure, io_uring_probe, which con‐
142 tains information about the opcodes supported by io_uring on the
143 running kernel. arg must contain a pointer to a struct
144 io_uring_probe, and nr_args must contain the size of the ops
145 array in that probe struct. The ops array is of the type
146 io_uring_probe_op, which holds the value of the opcode and a
147 flags field. If the flags field has IO_URING_OP_SUPPORTED set,
148 then this opcode is supported on the running kernel. Available
149 since 5.6.
150 IORING_REGISTER_PERSONALITY
153 This operation registers credentials of the running application
154 with io_uring, and returns an id associated with these creden‐
155 tials. Applications wishing to share a ring between separate
156 users/processes can pass in this credential id in the sqe per‐
157 sonality field. If set, that particular sqe will be issued with
158 these credentials. Must be invoked with arg set to NULL and
159 nr_args set to zero. Available since 5.6.
160 IORING_UNREGISTER_PERSONALITY
163 This operation unregisters a previously registered personality
164 with io_uring. nr_args must be set to the id in question, and
165 arg must be set to NULL. Available since 5.6.
166
169 On success, io_uring_register() returns 0. On error, -1 is returned,
170 and errno is set accordingly.
171
174 EBADF One or more fds in the fd array are invalid.
175 EBUSY IORING_REGISTER_BUFFERS or IORING_REGISTER_FILES was specified,
177 but there were already buffers or files registered.
178 EFAULT buffer is outside of the process' accessible address space, or
180 iov_len is greater than 1GiB.
181 EINVAL IORING_REGISTER_BUFFERS or IORING_REGISTER_FILES was specified,
183 but nr_args is 0.
184 EINVAL IORING_REGISTER_BUFFERS was specified, but nr_args exceeds
186 UIO_MAXIOV
187 EINVAL IORING_UNREGISTER_BUFFERS or IORING_UNREGISTER_FILES was speci‐
189 fied, and nr_args is non-zero or arg is non-NULL.
190 EMFILE IORING_REGISTER_FILES was specified and nr_args exceeds the max‐
192 imum allowed number of files in a fixed file set.
193 EMFILE IORING_REGISTER_FILES was specified and adding nr_args file ref‐
195 erences would exceed the maximum allowed number of files the
196 user is allowed to have according to the RLIMIT_NOFILE resource
197 limit and the caller does not have CAP_SYS_RESOURCE capability.
198 Note that this is a per user limit, not per process.
199 ENOMEM Insufficient kernel resources are available, or the caller had a
201 non-zero RLIMIT_MEMLOCK soft resource limit, but tried to lock
202 more memory than the limit permitted. This limit is not
203 enforced if the process is privileged (CAP_IPC_LOCK).
204 ENXIO IORING_UNREGISTER_BUFFERS or IORING_UNREGISTER_FILES was speci‐
206 fied, but there were no buffers or files registered.
207 ENXIO Attempt to register files or buffers on an io_uring instance
209 that is already undergoing file or buffer registration, or is
210 being torn down.
211 EOPNOTSUPP
213 User buffers point to file-backed memory.
214Linux 2019-01-17 IO_URING_REGISTER(2)