# io_uring_queue_init

## NAME



           io_uring_queue_init - setup io_uring submission and completion
           queues
    


## SYNOPSIS



           **#include <liburing.h>**
    
           **int io_uring_queue_init(unsigned** _entries_**,**
                                   **struct io_uring ***_ring_**,**
                                   **unsigned** _flags_**);**
    
           **int io_uring_queue_init_params(unsigned** _entries_**,**
                                          **struct io_uring ***_ring_**,**
                                          **struct io_uring_params ***_params_**);**
    
           **int io_uring_queue_init_mem(unsigned** _entries_**,**
                                       **struct io_uring ***_ring_**,**
                                       **struct io_uring_params ***_params_**,**
                                       **void ***_buf_**, size_t** _buf_size_**);**
    


## DESCRIPTION



           The io_uring_queue_init(3) function executes the io_uring_setup(2)
           system call to initialize the submission and completion queues in
           the kernel with at least _entries_ entries in the submission queue
           and then maps the resulting file descriptor to memory shared
           between the application and the kernel.
    
           By default, the CQ ring will have twice the number of entries as
           specified by _entries_ for the SQ ring. This is adequate for regular
           file or storage workloads, but may be too small for networked
           workloads. The SQ ring entries do not impose a limit on the number
           of in-flight requests that the ring can support, it merely limits
           the number that can be submitted to the kernel in one go (batch).
           If the CQ ring overflows, e.g. more entries are generated than
           fits in the ring before the application can reap them, then if the
           kernel supports **IORING_FEAT_NODROP** the ring enters a CQ ring
           overflow state. Otherwise it drops the CQEs and increments
           _cq.koverflow_ in _struct io_uring_ with the number of CQEs dropped.
           The overflow state is indicated by **IORING_SQ_CQ_OVERFLOW** being set
           in the SQ ring flags. Unless the kernel runs out of available
           memory, entries are not dropped, but it is a much slower
           completion path and will slow down request processing. For that
           reason it should be avoided and the CQ ring sized appropriately
           for the workload. Setting _cq_entries_ in _struct io_uring_params_
           will tell the kernel to allocate this many entries for the CQ
           ring, independent of the SQ ring size in given in _entries_.  If the
           value isn't a power of 2, it will be rounded up to the nearest
           power of 2.
    
           On success, io_uring_queue_init(3) returns 0 and _ring_ will point
           to the shared memory containing the io_uring queues. On failure
           **-errno** is returned.
    
           _flags_ will be passed through to the io_uring_setup syscall (see
           io_uring_setup(2)).
    
           The io_uring_queue_init_params(3) and io_uring_queue_init_mem(3)
           variants will pass the parameters indicated by _params_ straight
           through to the io_uring_setup(2) system call.
    
           The io_uring_queue_init_mem(3) variant uses the provided _buf_ with
           associated size _buf_size_ as the memory for the ring, using the
           **IORING_SETUP_NO_MMAP** flag to io_uring_setup(2).  The buffer passed
           to io_uring_queue_init_mem(3) must be page size aligned on the
           host, and must already be zeroed.  Typically, the caller should
           allocate a huge page and pass that in to
           io_uring_queue_init_mem(3).  Pages allocated by mmap are already
           zeroed.  io_uring_queue_init_mem(3) returns the number of bytes
           used from the provided buffer, so that the app can reuse the
           buffer with the returned offset to put more rings in the same huge
           page.
    
           On success, the resources held by _ring_ should be released via a
           corresponding call to io_uring_queue_exit(3).
    


## RETURN VALUE



           io_uring_queue_init(3) and io_uring_queue_init_params(3) return 0
           on success and **-errno** on failure.
    
           io_uring_queue_init_mem(3) returns the number of bytes used from
           the provided buffer on success, and **-errno** on failure.
    


* * *