# io_uring_register

## NAME



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


## SYNOPSIS



           **#include <liburing.h>**
    
           **int io_uring_register(unsigned int** _fd_**, unsigned int** _opcode_**,**
                                 **void ***_arg_**, unsigned int** _nr_args_**);**
    


## DESCRIPTION



           The io_uring_register(2) system call registers resources (e.g.
           user buffers, files, eventfd, personality, restrictions) for use
           in an io_uring(7) instance referenced by _fd_.  Registering files or
           user buffers allows the kernel to take long term references to
           internal data structures or create long term mappings of
           application memory, greatly reducing per-I/O overhead.
    
           _fd_ is the file descriptor returned by a call to io_uring_setup(2).
           If _opcode_ has the flag **IORING_REGISTER_USE_REGISTERED_RING** ored
           into it, _fd_ is instead the index of a registered ring fd.
    
           _opcode_ can be one of:
    
           **IORING_REGISTER_BUFFERS**
                  _arg_ points to a _struct iovec_ array of _nr_args_ entries.  The
                  buffers associated with the iovecs will be locked in memory
                  and charged against the user's **RLIMIT_MEMLOCK** resource
                  limit.  See getrlimit(2) for more information.
                  Additionally, there is a size limit of 1GiB per buffer.
                  Currently, the buffers must be anonymous, non-file-backed
                  memory, such as that returned by malloc(3) or mmap(2) with
                  the **MAP_ANONYMOUS** flag set.  It is expected that this
                  limitation will be lifted in the future. Huge pages are
                  supported as well. Note that the entire huge page will be
                  pinned in the kernel, even if only a portion of it is used.
    
                  After a successful call, the supplied buffers are mapped
                  into the kernel and eligible for I/O.  To make use of them,
                  the application must specify the **IORING_OP_READ_FIXED** or
                  **IORING_OP_WRITE_FIXED** opcodes in the submission queue entry
                  (see the _struct io_uring_sqe_ definition in
                  io_uring_enter(2)), and set the _buf_index_ field to the
                  desired buffer index.  The memory range described by the
                  submission queue entry's _addr_ and _len_ fields must fall
                  within the indexed buffer.
    
                  It is perfectly valid to setup a large buffer and then only
                  use part of it for an I/O, as long as the range is within
                  the originally mapped region.
    
                  An application can increase or decrease the size or number
                  of registered buffers by first unregistering the existing
                  buffers, and then issuing a new call to
                  io_uring_register(2) with the new buffers.
    
                  Note that before 5.13 registering buffers would wait for
                  the ring to idle.  If the application currently has
                  requests in-flight, the registration will wait for those to
                  finish before proceeding.
    
                  An application need not unregister buffers explicitly
                  before shutting down the io_uring instance. Note, however,
                  that shutdown processing may run asynchronously within the
                  kernel. As a result, it is not guaranteed that pages are
                  immediately unpinned in this case. Available since 5.1.
    
           **IORING_REGISTER_BUFFERS2**
                  Register buffers for I/O. Similar to
                  **IORING_REGISTER_BUFFERS** but aims to have a more extensible
                  ABI.
    
                  _arg_ points to a _struct io_uring_rsrc_register_ , and _nr_args_
                  should be set to the number of bytes in the structure.
    
                      struct io_uring_rsrc_register {
                          __u32 nr;
                          __u32 flags;
                          __u64 resv2;
                          __aligned_u64 data;
                          __aligned_u64 tags;
                      };
    
                  The _data_ field contains a pointer to a _struct iovec_ array
                  of _nr_ entries.  The _tags_ field should either be 0, then
                  tagging is disabled, or point to an array of _nr_ "tags"
                  (unsigned 64 bit integers). If a tag is zero, then tagging
                  for this particular resource (a buffer in this case) is
                  disabled. Otherwise, after the resource had been
                  unregistered and it's not used anymore, a CQE will be
                  posted with _user_data_ set to the specified tag and all
                  other fields zeroed.
    
                  The _flags_ field supports the following flags:
    
                      **IORING_RSRC_REGISTER_SPARSE** If set, io_uring will
                      register _nr_ empty buffers, which need to be updated
                      before use. When this flag is set, _data_ and _tags_ must
                      be NULL. Available since 5.19.
    
                  Note that resource updates, e.g.
                  **IORING_REGISTER_BUFFERS_UPDATE** , don't necessarily
                  deallocate resources by the time it returns, but they might
                  be held alive until all requests using it complete.
    
                  Available since 5.13.
    
           **IORING_REGISTER_BUFFERS_UPDATE**
                  Updates registered buffers with new ones, either turning a
                  sparse entry into a real one, or replacing an existing
                  entry.
    
                  _arg_ must contain a pointer to a _struct_
                  _io_uring_rsrc_update2_ , which contains an offset on which to
                  start the update, and an array of _struct iovec_.  _tags_
                  points to an array of tags.  _nr_ must contain the number of
                  descriptors in the passed in arrays.  See
                  **IORING_REGISTER_BUFFERS2** for the resource tagging
                  description.
    
                   struct io_uring_rsrc_update2 {
                       __u32 offset;
                       __u32 resv;
                       __aligned_u64 data;
                       __aligned_u64 tags;
                       __u32 nr;
                       __u32 resv2;
                   };
    
                   Available since 5.13.
    
           **IORING_UNREGISTER_BUFFERS**
                  This operation takes no argument, and _arg_ must be passed as
                  NULL.  All previously registered buffers associated with
                  the io_uring instance will be released synchronously.
                  Available since 5.1.
    
           **IORING_REGISTER_FILES**
                  Register files for I/O.  _arg_ contains a pointer to an array
                  of _nr_args_ file descriptors (signed 32 bit integers).
    
                  To make use of the registered files, the **IOSQE_FIXED_FILE**
                  flag must be set in the _flags_ member of the _struct_
                  _io_uring_sqe_ , and the _fd_ member is set to the index of the
                  file in the file descriptor array.
    
                  The file set may be sparse, meaning that the **fd** field in
                  the array may be set to **-1**.  See
                  **IORING_REGISTER_FILES_UPDATE** for how to update files in
                  place.
    
                  Note that before 5.13 registering files would wait for the
                  ring to idle.  If the application currently has requests
                  in-flight, the registration will wait for those to finish
                  before proceeding. See **IORING_REGISTER_FILES_UPDATE** for how
                  to update an existing set without that limitation.
    
                  Files are automatically unregistered when the io_uring
                  instance is torn down. An application needs only unregister
                  if it wishes to register a new set of fds. Available since
                  5.1.
    
           **IORING_REGISTER_FILES2**
                  Register files for I/O. Similar to **IORING_REGISTER_FILES**.
    
                  _arg_ points to a _struct io_uring_rsrc_register_ , and _nr_args_
                  should be set to the number of bytes in the structure.
    
                  The _data_ field contains a pointer to an array of _nr_ file
                  descriptors (signed 32 bit integers).  _tags_ field should
                  either be 0 or or point to an array of _nr_ "tags" (unsigned
                  64 bit integers). See **IORING_REGISTER_BUFFERS2** for more
                  info on resource tagging.
    
                  Note that resource updates, e.g.
                  **IORING_REGISTER_FILES_UPDATE** , don't necessarily deallocate
                  resources, they might be held until all requests using that
                  resource complete.
    
                  Available since 5.13.
    
           **IORING_REGISTER_FILES_UPDATE**
                  This operation replaces existing files in the registered
                  file set with new ones, either turning a sparse entry (one
                  where fd is equal to **-1**) into a real one, removing an
                  existing entry (new one is set to **-1**), or replacing an
                  existing entry with a new existing entry.
    
                  _arg_ must contain a pointer to a _struct_
                  _io_uring_rsrc_update_ , which contains an offset on which to
                  start the update, and an array of file descriptors to use
                  for the update.  _nr_args_ must contain the number of
                  descriptors in the passed in array. Available since 5.5.
    
                  File descriptors can be skipped if they are set to
                  **IORING_REGISTER_FILES_SKIP**.  Skipping an fd will not touch
                  the file associated with the previous fd at that index.
                  Available since 5.12.
    
           **IORING_REGISTER_FILES_UPDATE2**
                  Similar to **IORING_REGISTER_FILES_UPDATE** , replaces existing
                  files in the registered file set with new ones, either
                  turning a sparse entry (one where fd is equal to **-1**) into a
                  real one, removing an existing entry (new one is set to
                  **-1**), or replacing an existing entry with a new existing
                  entry.
    
                  _arg_ must contain a pointer to a _struct_
                  _io_uring_rsrc_update2_ , which contains an offset on which to
                  start the update, and an array of file descriptors to use
                  for the update stored in _data_.  _tags_ points to an array of
                  tags.  _nr_ must contain the number of descriptors in the
                  passed in arrays.  See **IORING_REGISTER_BUFFERS2** for the
                  resource tagging description.
    
                  Available since 5.13.
    
           **IORING_UNREGISTER_FILES**
                  This operation requires no argument, and _arg_ must be passed
                  as NULL.  All previously registered files associated with
                  the io_uring instance will be unregistered. Available since
                  5.1.
    
           **IORING_REGISTER_EVENTFD**
                  It's possible to use eventfd(2) to get notified of
                  completion events on an io_uring instance. If this is
                  desired, an eventfd file descriptor can be registered
                  through this operation.  _arg_ must contain a pointer to the
                  eventfd file descriptor, and _nr_args_ must be 1. Note that
                  while io_uring generally takes care to avoid spurious
                  events, they can occur. Similarly, batched completions of
                  CQEs may only trigger a single eventfd notification even if
                  multiple CQEs are posted. The application should make no
                  assumptions on number of events being available having a
                  direct correlation to eventfd notifications posted. An
                  eventfd notification must thus only be treated as a hint to
                  check the CQ ring for completions. Available since 5.2.
    
                  An application can temporarily disable notifications,
                  coming through the registered eventfd, by setting the
                  **IORING_CQ_EVENTFD_DISABLED** bit in the _flags_ field of the CQ
                  ring.  Available since 5.8.
    
           **IORING_REGISTER_EVENTFD_ASYNC**
                  This works just like **IORING_REGISTER_EVENTFD** , except
                  notifications are only posted for events that complete in
                  an async manner. This means that events that complete
                  inline while being submitted do not trigger a notification
                  event. The arguments supplied are the same as for
                  **IORING_REGISTER_EVENTFD**.  Available since 5.6.
    
           **IORING_UNREGISTER_EVENTFD**
                  Unregister an eventfd file descriptor to stop
                  notifications. Since only one eventfd descriptor is
                  currently supported, this operation takes no argument, and
                  _arg_ must be passed as NULL and _nr_args_ must be zero.
                  Available since 5.2.
    
           **IORING_REGISTER_PROBE**
                  This operation returns a structure, io_uring_probe, which
                  contains information about the opcodes supported by
                  io_uring on the running kernel.  _arg_ must contain a pointer
                  to a struct io_uring_probe, and _nr_args_ must contain the
                  size of the ops array in that probe struct. The ops array
                  is of the type io_uring_probe_op, which holds the value of
                  the opcode and a flags field. If the flags field has
                  **IO_URING_OP_SUPPORTED** set, then this opcode is supported on
                  the running kernel. Available since 5.6.
    
           **IORING_REGISTER_PERSONALITY**
                  This operation registers credentials of the running
                  application with io_uring, and returns an id associated
                  with these credentials. Applications wishing to share a
                  ring between separate users/processes can pass in this
                  credential id in the sqe **personality** field. If set, that
                  particular sqe will be issued with these credentials. Must
                  be invoked with _arg_ set to NULL and _nr_args_ set to zero.
                  Available since 5.6.
    
           **IORING_UNREGISTER_PERSONALITY**
                  This operation unregisters a previously registered
                  personality with io_uring.  _nr_args_ must be set to the id
                  in question, and _arg_ must be set to NULL. Available since
                  5.6.
    
           **IORING_REGISTER_ENABLE_RINGS**
                  This operation enables an io_uring ring started in a
                  disabled state (**IORING_SETUP_R_DISABLED** was specified in
                  the call to io_uring_setup(2)).  While the io_uring ring is
                  disabled, submissions are not allowed and registrations are
                  not restricted.
    
                  After the execution of this operation, the io_uring ring is
                  enabled: submissions and registration are allowed, but they
                  will be validated following the registered restrictions (if
                  any).  This operation takes no argument, must be invoked
                  with _arg_ set to NULL and _nr_args_ set to zero. Available
                  since 5.10.
    
           **IORING_REGISTER_RESTRICTIONS**
                  _arg_ points to a _struct io_uring_restriction_ array of
                  _nr_args_ entries.
    
                  With an entry it is possible to allow an
                  io_uring_register(2) _opcode_ , or specify which _opcode_ and
                  _flags_ of the submission queue entry are allowed, or require
                  certain _flags_ to be specified (these flags must be set on
                  each submission queue entry).
    
                  All the restrictions must be submitted with a single
                  io_uring_register(2) call and they are handled as an
                  allowlist (opcodes and flags not registered, are not
                  allowed).
    
                  Restrictions can be registered only if the io_uring ring
                  started in a disabled state (**IORING_SETUP_R_DISABLED** must
                  be specified in the call to io_uring_setup(2)).
    
                  Available since 5.10.
    
           **IORING_REGISTER_IOWQ_AFF**
                  By default, async workers created by io_uring will inherit
                  the CPU mask of its parent. This is usually all the CPUs in
                  the system, unless the parent is being run with a limited
                  set. If this isn't the desired outcome, the application may
                  explicitly tell io_uring what CPUs the async workers may
                  run on.  _arg_ must point to a **cpu_set_t** mask, and _nr_args_
                  the byte size of that mask.
    
                  Available since 5.14.
    
           **IORING_UNREGISTER_IOWQ_AFF**
                  Undoes a CPU mask previously set with
                  **IORING_REGISTER_IOWQ_AFF**.  Must not have _arg_ or _nr_args_
                  set.
    
                  Available since 5.14.
    
           **IORING_REGISTER_IOWQ_MAX_WORKERS**
                  By default, io_uring limits the unbounded workers created
                  to the maximum processor count set by _RLIMIT_NPROC_ and the
                  bounded workers is a function of the SQ ring size and the
                  number of CPUs in the system. Sometimes this can be
                  excessive (or too little, for bounded), and this command
                  provides a way to change the count per ring (per NUMA node)
                  instead.
    
                  _arg_ must be set to an _unsigned int_ pointer to an array of
                  two values, with the values in the array being set to the
                  maximum count of workers per NUMA node. Index 0 holds the
                  bounded worker count, and index 1 holds the unbounded
                  worker count. On successful return, the passed in array
                  will contain the previous maximum values for each type. If
                  the count being passed in is 0, then this command returns
                  the current maximum values and doesn't modify the current
                  setting.  _nr_args_ must be set to 2, as the command takes
                  two values.
    
                  Available since 5.15.
    
           **IORING_REGISTER_RING_FDS**
                  Whenever io_uring_enter(2) is called to submit request or
                  wait for completions, the kernel must grab a reference to
                  the file descriptor. If the application using io_uring is
                  threaded, the file table is marked as shared, and the
                  reference grab and put of the file descriptor count is more
                  expensive than it is for a non-threaded application.
    
                  Similarly to how io_uring allows registration of files,
                  this allow registration of the ring file descriptor itself.
                  This reduces the overhead of the io_uring_enter(2) system
                  call.
    
                  _arg_ must be set to a pointer to an array of type _struct_
                  _io_uring_rsrc_update_ of _nr_args_ number of entries. The **data**
                  field of this struct must contain an io_uring file
                  descriptor, and the **offset** field can be either **-1** or an
                  explicit offset desired for the registered file descriptor
                  value. If **-1** is used, then upon successful return of this
                  system call, the field will contain the value of the
                  registered file descriptor to be used for future
                  io_uring_enter(2) system calls.
    
                  On successful completion of this request, the returned
                  descriptors may be used instead of the real file descriptor
                  for io_uring_enter(2), provided that
                  **IORING_ENTER_REGISTERED_RING** is set in the _flags_ for the
                  system call. This flag tells the kernel that a registered
                  descriptor is used rather than a real file descriptor.
    
                  Each thread or process using a ring must register the file
                  descriptor directly by issuing this request.
    
                  The maximum number of supported registered ring descriptors
                  is currently limited to **16.**
    
                  Available since 5.18.
    
           **IORING_UNREGISTER_RING_FDS**
                  Unregister descriptors previously registered with
                  **IORING_REGISTER_RING_FDS**.
    
                  _arg_ must be set to a pointer to an array of type _struct_
                  _io_uring_rsrc_update_ of _nr_args_ number of entries. Only the
                  **offset** field should be set in the structure, containing the
                  registered file descriptor offset previously returned from
                  **IORING_REGISTER_RING_FDS** that the application wishes to
                  unregister.
    
                  Note that this isn't done automatically on ring exit, if
                  the thread or task that previously registered a ring file
                  descriptor isn't exiting. It is recommended to manually
                  unregister any previously registered ring descriptors if
                  the ring is closed and the task persists. This will free up
                  a registration slot, making it available for future use.
    
                  Available since 5.18.
    
           **IORING_REGISTER_PBUF_RING**
                  Registers a shared buffer ring to be used with provided
                  buffers. This is a newer alternative to using
                  **IORING_OP_PROVIDE_BUFFERS** which is more efficient, to be
                  used with request types that support the
                  **IOSQE_BUFFER_SELECT** flag.
    
                  The _arg_ argument must be filled in with the appropriate
                  information. It looks as follows:
    
                       struct io_uring_buf_reg {
                           __u64 ring_addr;
                           __u32 ring_entries;
                           __u16 bgid;
                           __u16 pad;
                           __u64 resv[3];
                       };
    
                   The _ring_addr_ field must contain the address to the memory
                   allocated to fit this ring.  The memory must be page
                   aligned and hence allocated appropriately using eg
                   posix_memalign(3) or similar. The size of the ring is the
                   product of _ring_entries_ and the size of _struct_
                   _io_uring_buf_.  _ring_entries_ is the desired size of the
                   ring, and must be a power-of-2 in size. The maximum size
                   allowed is 2^15 (32768).  _bgid_ is the buffer group ID
                   associated with this ring. SQEs that select a buffer have
                   a buffer group associated with them in their _buf_group_
                   field, and the associated CQEs will have
                   **IORING_CQE_F_BUFFER** set in their _flags_ member, which will
                   also contain the specific ID of the buffer selected. The
                   rest of the fields are reserved and must be cleared to
                   zero.
    
                   _nr_args_ must be set to 1.
    
                   Also see io_uring_register_buf_ring(3) for more details.
                   Available since 5.19.
    
           **IORING_UNREGISTER_PBUF_RING**
                  Unregister a previously registered provided buffer ring.
                  _arg_ must be set to the address of a struct
                  io_uring_buf_reg, with just the _bgid_ field set to the
                  buffer group ID of the previously registered provided
                  buffer group.  _nr_args_ must be set to 1. Also see
                  **IORING_REGISTER_PBUF_RING**.
    
                  Available since 5.19.
    
           **IORING_REGISTER_SYNC_CANCEL**
                  Performs a synchronous cancelation request, which works in
                  a similar fashion to **IORING_OP_ASYNC_CANCEL** except it
                  completes inline. This can be useful for scenarios where
                  cancelations should happen synchronously, rather than
                  needing to issue an SQE and wait for completion of that
                  specific CQE.
    
                  _arg_ must be set to a pointer to a struct
                  io_uring_sync_cancel_reg structure, with the details filled
                  in for what request(s) to target for cancelation. See
                  io_uring_register_sync_cancel(3) for details on that. The
                  return values are the same, except they are passed back
                  synchronously rather than through the CQE _res_ field.
                  _nr_args_ must be set to 1.
    
                  Available since 6.0.
    
           **IORING_REGISTER_FILE_ALLOC_RANGE**
                  sets the allowable range for fixed file index allocations
                  within the kernel. When requests that can instantiate a new
                  fixed file are used with **IORING_FILE_INDEX_ALLOC** , the
                  application is asking the kernel to allocate a new fixed
                  file descriptor rather than pass in a specific value for
                  one. By default, the kernel will pick any available fixed
                  file descriptor within the range available.  This
                  effectively allows the application to set aside a range
                  just for dynamic allocations, with the remainder being used
                  for specific values.
    
                  _nr_args_ must be set to 1 and _arg_ must be set to a pointer
                  to a struct io_uring_file_index_range:
    
                       struct io_uring_file_index_range {
                           __u32 off;
                           __u32 len;
                           __u64 resv;
                       };
    
                   with _off_ being set to the starting value for the range,
                   and _len_ being set to the number of descriptors. The
                   reserved _resv_ field must be cleared to zero.
    
                   The application must have registered a file table first.
    
                   Available since 6.0.
    
           **IORING_REGISTER_PBUF_STATUS**
                  Can be used to retrieve the current head of a ringbuffer
                  provided earlier via **IORING_REGISTER_PBUF_RING**.  _arg_ must
                  point to a
    
                       struct io_uring_buf_status {
                            __u32     buf_group;     /* input */
                            __u32     head;          /* output */
                            __u32     resv[8];
                       };
    
                   of which _arg- >buf_group_ should contain the buffer group ID
                   for the buffer ring in question, _nr_args_ should be set to
                   1 and _arg- >resv_ should be zeroed out.  The current head of
                   the ringbuffer will be returned in _arg- >head_.
    
                   Available since 6.8.
    
           **IORING_REGISTER_NAPI**
                  Registers a napi instance with the io_uring instance of _fd_.
                  _arg_ should point to a
    
                       struct io_uring_napi {
                            __u32     busy_poll_to;
                            __u8 prefer_busy_poll;
                            __u8 pad[3];
                            __u64     resv;
                       };
    
                   in which _arg- >busy_poll_to_ should contain the busy poll
                   timeout in micro seconds and _arg- >prefer_busy_poll_ should
                   specify whether busy polling should be used rather than
                   IRQs.  _nr_args_ should be set to 1 and _arg- >pad_ and
                   _arg- >resv_ should be zeroed out.  On successful return the
                   _io_uring_napi_ struct pointed to by _arg_ will contain the
                   previously used settings.  Must be used with a ring
                   initially created with **IORING_SETUP_IOPOLL**.
    
                   Available since 6.9.
    
           **IORING_UNREGISTER_NAPI**
                  Unregisters a napi instance previously registered via
                  **IORING_REGISTER_NAPI** to the io_uring instance of _fd_.  _arg_
                  should point to a _struct io_uring_napi_.  On successful
                  return the _io_uring_napi_ struct pointed to by _arg_ will
                  contain the previously used settings.
    
                  Available since 6.9.
    
           **IORING_REGISTER_CLOCK**
                  Specifies which clock id io_uring will use for timers while
                  waiting for completion events with **IORING_ENTER_GETEVENTS**.
                  It's only effective if the timeout argument in _struct_
                  _io_uring_getevents_arg_ is passed, ignored otherwise.  When
                  used in conjunction with **IORING_ENTER_ABS_TIMER** , interprets
                  the timeout argument as absolute time of the specified
                  clock.
    
                  The default clock is **CLOCK_MONOTONIC**.
    
                  Available since 6.12 and supports **CLOCK_MONOTONIC** and
                  **CLOCK_BOOTTIME**.
    
           **IORING_REGISTER_CLONE_BUFFERS**
                  Supports cloning buffers from a source ring to a
                  destination ring, duplicating previously registered buffers
                  from source to destination.  _arg_ must be set to a pointer
                  to a _struct io_uring_clone_buffers_ and _nr_args_ must be set
                  to **1 .**_struct io_uring_buf_reg_ looks as follows:
    
                       struct io_uring_clone_buffers {
                           __u32 src_fd;
                           __u32 flags;
                           __u32 src_off;
                           __u32 dst_off;
                           __u32 nr;
                           __u32 pad[3];
                       };
    
                  where
                  _src_fd_ indicates the fd of the source ring, _flags_ are
                  modifier flags for the operation, _src_off_ indicates the
                  offset from where to start the cloning from the source
                  ring, _dst_off_ indicates the offset from where to start the
                  cloning into the destination ring, and _nr_ indicates the
                  number of buffers to clone at the given offsets.  _pad_ must
                  be zero filled.  Kernel 6.12 added support for full range
                  cloning, where _src_off_ , _dst_off_ , and _nr_ must all be set to
                  0, indicating cloning of the entire table in source to
                  destination. Kernel 6.13 added support for specifying the
                  offsets and how many buffers to clone. Additionally, it
                  added support for cloning into a previously registered
                  table in the destination as well, 6.12 would fail that
                  operation with **-EBUSY** if attempted. To replace existing
                  nodes, or clone into an existing table,
                  **IORING_REGISTER_DST_REPLACE** must be set in the _flags_
                  member.
    
           **IORING_REGISTER_SEND_MSG_RING**
                  Supports sending of the equivalent of a **IORING_OP_MSG_RING**
                  request, but without having a source ring available. Takes
                  a pointer to a _struct_ io_uring_sqe which must be prepared
                  with io_uring_prep_msg_ring(3) before being submitted. Only
                  supports **IORING_MSG_DATA** type of requests. Available since
                  kernel 6.13.
    
           **IORING_REGISTER_RESIZE_RINGS**
                  Supports resizing the SQ and CQ rings. Takes a pointer to a
                  _struct_ io_uring_params as the argument, where _sq_entries_ and
                  _cq_entries_ may be set to the desired values. Only supports
                  a limited set of flags set in the _struct_ io_uring_params
                  argument, notably **IORING_SETUP_CQSIZE** and
                  **IORING_SETUP_CLAMP** to modify the CQ ring sizing. See
                  io_uring_resize_rings(3) for details. Note that while
                  liburing takes care of the ring unmap and mapping for a
                  resize operation, manual users of this register syscall
                  must perform those operations, similarly to when a new ring
                  is created. The _struct_ io_uring_params structure will get
                  the necessary offsets copied back upon successful
                  completion of this system call, which can be used to memory
                  map the ring just like how a new ring would've been mapped.
                  Available since kernel 6.13.
    
           **IORING_REGISTER_MEM_REGION**
                  Supports registering multiple purposes memory regions,
                  avoiding unnecessary copying in of
                  _struct_ io_uring_getevents_arg for wait operations that
                  specify a timeout or minimum timeout. Takes a pointer to a
                  _struct_ io_uring_mem_region_reg structure, which looks as
                  follows:
    
                       struct io_uring_mem_region_reg {
                           __u64 region_uptr;
                           __u64 flags;
                           __u64 __resv[2];
                       };
    
                  where
                  _region_uptr_ must be set to the region being registered as
                  memory regions, _flags_ specifies modifier flags (must
                  currently be **IORING_MEM_REGION_REG_WAIT_ARG ). The pad**
                  **fields must all be cleared to 0 .** Each memory regions
                  looks as follows:
    
                       struct io_uring_region_desc {
                           __u64 user_addr;
                           __u64 size;
                           __u32 flags;
                           __u32 id;
                           __u64 mmap_offset;
                           __u64 __resv[4];
                       };
    
                  where
                  _user_addr_ points to userspace memory mappings, _size_ is the
                  size of userspace memory. Current supported userspace
                  memory regions looks as follows:
    
                       struct io_uring_reg_wait {
                           struct __kernel_timespec ts;
                           __u32                    min_wait_usec;
                           __u32                    flags;
                           __u64                    sigmask;
                           __u32                    sigmask_sz;
                           __u32                    pad[3];
                           __u64                    pad2[2];
                       };
    
                  where
                  _ts_ holds the timeout information for this region _flags_
                  holds information about the timeout region, _sigmask_ is a
                  pointer to a signal mask, if used, and _sigmask_sz_ is the
                  size of that signal mask. The pad fields must all be
                  cleared to **0 .** Currently the only valid flag is
                  **IORING_REG_WAIT_TS ,** which, if set, says that the values in
                  _ts_ are valid and should be used for a timeout operation.
                  The _user_addr_ field of _struct_ io_uring_region_desc must be
                  set to an address of _struct_ io_uring_reg_wait members, an up
                  to a page size can be mapped. At the size of 64 bytes per
                  region, that allows at least 64 individual regions on a 4k
                  page size system.  The offsets of these regions are used
                  for an io_uring_enter(2) system call, with the first one
                  being 0, second one 1, and so forth. After registration of
                  the wait regions, io_uring_enter(2) may be used with the
                  enter flag of **IORING_ENTER_EXT_ARG_REG and an** _argp_ set to
                  the wait region offset, rather than a pointer to a
                  _struct_ io_uring_getevent_arg structure. If used with
                  **IORING_ENTER_GETEVENTS ,** then the wait operation will use
                  the information in the registered wait region rather than
                  needing a io_uring_getevent_arg structure copied for each
                  operation. For high frequency waits, this can save
                  considerable CPU cycles.  Note: once a region has been
                  registered, it cannot get unregistered. It lives for the
                  life of the ring. Individual wait region offset may be
                  modified before any io_uring_enter(2) system call.
                  Available since kernel 6.13.
    


## RETURN VALUE



           On success, io_uring_register(2) returns either 0 or a positive
           value, depending on the _opcode_ used.  On error, a negative error
           value is returned. The caller should not rely on the _errno_
           variable.
    


## ERRORS



           **EACCES** The _opcode_ field is not allowed due to registered
                  restrictions.
    
           **EBADF** One or more fds in the _fd_ array are invalid.
    
           **EBADFD IORING_REGISTER_ENABLE_RINGS** or
                  **IORING_REGISTER_RESTRICTIONS** was specified, but the
                  io_uring ring is not disabled.
    
           **EBUSY  IORING_REGISTER_BUFFERS** or **IORING_REGISTER_FILES** or
                  **IORING_REGISTER_RESTRICTIONS** was specified, but there were
                  already buffers, files, or restrictions registered.
    
           **EEXIST** The thread performing the registration is invalid.
    
           **EFAULT** buffer is outside of the process' accessible address space,
                  or _iov_len_ is greater than 1GiB.
    
           **EINVAL IORING_REGISTER_BUFFERS** or **IORING_REGISTER_FILES** was
                  specified, but _nr_args_ is 0.
    
           **EINVAL IORING_REGISTER_BUFFERS** was specified, but _nr_args_ exceeds
                  **UIO_MAXIOV**
    
           **EINVAL IORING_UNREGISTER_BUFFERS** or **IORING_UNREGISTER_FILES** was
                  specified, and _nr_args_ is non-zero or _arg_ is non-NULL.
    
           **EINVAL IORING_REGISTER_RESTRICTIONS** was specified, but _nr_args_
                  exceeds the maximum allowed number of restrictions or
                  restriction _opcode_ is invalid.
    
           **EMFILE IORING_REGISTER_FILES** was specified and _nr_args_ exceeds the
                  maximum allowed number of files in a fixed file set.
    
           **EMFILE IORING_REGISTER_FILES** was specified and adding _nr_args_ file
                  references would exceed the maximum allowed number of files
                  the user is allowed to have according to the **RLIMIT_NOFILE**
                  resource limit and the caller does not have
                  **CAP_SYS_RESOURCE** capability. Note that this is a per user
                  limit, not per process.
    
           **ENOMEM** Insufficient kernel resources are available, or the caller
                  had a non-zero **RLIMIT_MEMLOCK** soft resource limit, but
                  tried to lock more memory than the limit permitted.  This
                  limit is not enforced if the process is privileged
                  (**CAP_IPC_LOCK**).
    
           **ENXIO  IORING_UNREGISTER_BUFFERS** or **IORING_UNREGISTER_FILES** was
                  specified, but there were no buffers or files registered.
    
           **ENXIO** Attempt to register files or buffers on an io_uring
                  instance that is already undergoing file or buffer
                  registration, or is being torn down.
    
           **EOPNOTSUPP**
                  User buffers point to file-backed memory.
    
           **EFAULT** User buffers point to file-backed memory (newer kernels).
    
           **ENOENT IORING_REGISTER_PBUF_STATUS** was specified, but _buf_group_
                  did not refer to a currently valid buffer group.
    
           **EINVAL IORING_REGISTER_PBUF_STATUS** was specified, but the valid
                  buffer group specified by _buf_group_ did not refer to a
                  buffer group registered via **IORING_REGISTER_PBUF_RING**.
    
           **EINVAL IORING_REGISTER_NAPI** was specified, but the ring associated
                  with _fd_ has not been created with **IORING_SETUP_IOPOLL**.
    


* * *