# io_uring_setup_reg_wait

## NAME



           io_uring_setup_reg_wait - Sets up and registers fixed wait regions
    


## SYNOPSIS



           **#include <liburing.h>**
    
           **struct io_uring_reg_wait *io_uring_setup_reg_wait(struct io_uring ***_ring_**,**
                                                             **unsigned** _nentries_**,**
                                                             **int ***_err_**);**
    


## DESCRIPTION



           The io_uring_setup_reg_wait(3) function allocates and registers a
           fixed wait region of _nentries_ entries. Upon successful return, the
           function returns a non-NULL pointer. On error, it returns **NULL** and
           fills in _err_ with the error value.
    
           A registered wait region is a contiguous range of
           _struct_ io_uring_reg_wait _,_ which look 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_ is the wait related information for this wait,
           _min_wait_usec_ is the minimum wait period (for a two-stage wait),
           if set to non-zero, _flags_ tells the kernel about the wait region,
           _sigmask_ is a pointer to a signal mask, if used, and _sigmask_sz_ is
           the size of the signal mask, if used.
    
           Currently the only valid flag is **IORING_REG_WAIT_TS ,** which, if
           set, indicates that the value in _ts_ is valid and should be used
           for the wait operation.
    
           A signal mask is used for the wait, if _sigmask_ is set to a valid,
           non-zero, pointer value. If used, _sigmask_sz_ must also be set.
    
           Each of the wait regions are indicated by the offset of the
           structure. The first wait region is index **0 ,** the next is index **1**
           **,** and so forth, up to the registered number of regions set by
           _nentries._
    
           The wait regions may be modified by an application at any time
           before calling **io_uring_submit_and_reg_wait**(3).  If modified while
           a wait region for that given offset is currently in use by the
           kernel, the results are undefined - the kernel may see the new
           value in time to use it, or it may not.
    
           The main purpose of registered wait regions and the associated
           submit-and-wait helpers is to reduce the overhead of a wait
           operation. A normal wait for events with a timeout will pass in a
           _struct_ io_uring_getevents_arg which will need to be copied for each
           wait. For high frequency wait operations, this adds noticeable
           overhead for each wait. With registered wait regions, no such
           copying needs to take place for each wait.
    
           Once a wait region has been setup, it persists for the life time
           of the ring.  It's currently not possible to unregister or resize
           a wait region.  Additionally, a wait region may currently only use
           a single page of memory.  On a 4k page size system, this means an
           application is limited to **64** wait regions. That should be enough,
           as each wait index may be modified as needed. With at least 64
           indices available, hopefully applications can just use the
           appropriately setup wait region for each specific type of wait,
           with different indices having different wait settings.
    
           While a region cannot get unregistered from the kernel, once a
           ring has been closed, the application may free the associated
           memory by calling io_uring_free_reg_wait(3).  An application may
           also do this before closing a ring, but then wait regions may no
           longer be modified by the application.
    
           Available since kernel 6.13.
    


## RETURN VALUE



           On success io_uring_setup_reg_wait(3) returns a pointer to the
           start of the wait regions. On failure, it returns **NULL** and sets
           _err_ to the appropriate **-errno** value.
    


* * *