--- name: "io_uring_queue_init" section: "3" platform: "linux" package: "liburing" version: "2.15-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/io_uring_queue_init" --- # io\_uring\_queue\_init(3) setup io\_uring submission and completion queues ## NAME io\_uring\_queue\_init - setup io\_uring submission and completion queues ## SYNOPSIS ``` #include ``` **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)](/io_uring_queue_init/3.md) function executes the [**io\_uring\_setup**(2)](/io_uring_setup/2.md) 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)](/io_uring_queue_init/3.md) 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)](/io_uring_setup/2.md)). The [**io\_uring\_queue\_init\_params**(3)](/io_uring_queue_init_params/3.md) and [**io\_uring\_queue\_init\_mem**(3)](/io_uring_queue_init_mem/3.md) variants will pass the parameters indicated by *params* straight through to the [**io\_uring\_setup**(2)](/io_uring_setup/2.md) system call. The [**io\_uring\_queue\_init\_mem**(3)](/io_uring_queue_init_mem/3.md) 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)](/io_uring_setup/2.md). The buffer passed to [**io\_uring\_queue\_init\_mem**(3)](/io_uring_queue_init_mem/3.md) 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)](/io_uring_queue_init_mem/3.md). Pages allocated by mmap are already zeroed. [**io\_uring\_queue\_init\_mem**(3)](/io_uring_queue_init_mem/3.md) 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)](/io_uring_queue_exit/3.md). ## RETURN VALUE [**io\_uring\_queue\_init**(3)](/io_uring_queue_init/3.md) and [**io\_uring\_queue\_init\_params**(3)](/io_uring_queue_init_params/3.md) return 0 on success and **-errno** on failure. A return value of **-ENOMEM** indicates there is not enough locked memory available to hold the specified number of entries. Reduce the number of entries, or call [**setrlimit**(2)](/setrlimit/2.md) to increase the maximum number of bytes of memory that may be locked into RAM. Be aware that calling [**io\_uring\_queue\_init**(3)](/io_uring_queue_init/3.md) and [**io\_uring\_queue\_exit**(3)](/io_uring_queue_exit/3.md) in a loop will temporarily lock a lot of memory, because [**io\_uring\_queue\_exit**(3)](/io_uring_queue_exit/3.md) does some of its accounting asynchronously. [**io\_uring\_queue\_init\_mem**(3)](/io_uring_queue_init_mem/3.md) returns the number of bytes used from the provided buffer on success, and **-errno** on failure. ## SEE ALSO [**io\_uring\_setup**(2)](/io_uring_setup/2.md), [**io\_uring\_register\_ring\_fd**(3)](/io_uring_register_ring_fd/3.md), [**mmap**(2)](/mmap/2.md), [**io\_uring\_queue\_exit**(3)](/io_uring_queue_exit/3.md)