1IO_URING_REGISTER(2)       Linux Programmer's Manual      IO_URING_REGISTER(2)
2
3
4

NAME

6       io_uring_register - register files or user buffers for asynchronous I/O
7

SYNOPSIS

9       #include <linux/io_uring.h>
10
11       int io_uring_register(unsigned int fd, unsigned int opcode,
12                             void *arg, unsigned int nr_args);
13

DESCRIPTION

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
22       fd is the file descriptor returned by a call to io_uring_setup(2).  op‐
23       code can be one of:
24
25
26       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
38              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
47              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
51              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
56              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
60              An application need not  unregister  buffers  explicitly  before
61              shutting down the io_uring instance. Available since 5.1.
62
63
64       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
69
70       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
74              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
79              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
83              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
89              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
93
94       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
101              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
107              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
111
112
113       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
118
119       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
126              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
131
132       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
140
141       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
147
148       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
159
160       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
169
170       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
175
176       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
182              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
188
189       IORING_REGISTER_RESTRICTIONS
190              arg points to a struct io_uring_restriction array of nr_args en‐
191              tries.
192
193              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
198              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
202              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
206              Available since 5.10.
207
208

RETURN VALUE

210       On  success,  io_uring_register() returns 0.  On error, -1 is returned,
211       and errno is set accordingly.
212
213

ERRORS

215       EACCES The opcode field is not allowed due to registered restrictions.
216
217       EBADF  One or more fds in the fd array are invalid.
218
219       EBADFD IORING_REGISTER_ENABLE_RINGS or IORING_REGISTER_RESTRICTIONS was
220              specified, but the io_uring ring is not disabled.
221
222       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
226       EFAULT buffer  is  outside of the process' accessible address space, or
227              iov_len is greater than 1GiB.
228
229       EINVAL IORING_REGISTER_BUFFERS or IORING_REGISTER_FILES was  specified,
230              but nr_args is 0.
231
232       EINVAL IORING_REGISTER_BUFFERS   was  specified,  but  nr_args  exceeds
233              UIO_MAXIOV
234
235       EINVAL IORING_UNREGISTER_BUFFERS or IORING_UNREGISTER_FILES was  speci‐
236              fied, and nr_args is non-zero or arg is non-NULL.
237
238       EINVAL IORING_REGISTER_RESTRICTIONS  was specified, but nr_args exceeds
239              the maximum allowed number of restrictions or restriction opcode
240              is invalid.
241
242       EMFILE IORING_REGISTER_FILES was specified and nr_args exceeds the max‐
243              imum allowed number of files in a fixed file set.
244
245       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
251       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
256       ENXIO  IORING_UNREGISTER_BUFFERS  or IORING_UNREGISTER_FILES was speci‐
257              fied, but there were no buffers or files registered.
258
259       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
263       EOPNOTSUPP
264              User buffers point to file-backed memory.
265
266
267
268Linux                             2019-01-17              IO_URING_REGISTER(2)
Impressum