Io_Uring

Creates a ring of at least entries submission entries. params goes in (flags, and the CPU and idle time of an SQPOLL thread) and comes back filled in: the real sizes, features and the offsets to map. Returns the ring's file descriptor.

Submits to_submit entries and/or waits for min_complete completions, depending on flags (IORING_ENTER_*). argument is a signal mask, or an io_uring_getevents_arg with IORING_ENTER_EXT_ARG, and argument_bytes its size (8 for a mask).

Registers resources with the ring (IORING_REGISTER_*, see io_uring_register_op).

Creates a ring of at least entries submission entries (a power of two, the kernel rounds up) and maps it. flags are IORING_SETUP_* flags. Returns 0, or the negative errno of the failing step: -ENOSYS where the kernel has no io_uring, -EPERM where policy forbids it (a seccomp filter, kernel.io_uring_disabled), -ENOMEM when the locked-memory limit of an old kernel is too small. IORING_SETUP_NO_MMAP, SQE_MIXED, CQE_MIXED and SQ_REWIND change the memory layout in ways this type does not follow: they return -EINVAL; drive such rings with the system calls directly.

ring_init with every parameter: params goes in (flags, cq_entries with IORING_SETUP_CQSIZE, the SQPOLL thread's CPU and idle time, wq_fd with ATTACH_WQ) and comes back as the kernel filled it in.

Unmaps the ring and closes its descriptor. Safe on a ring that was never initialized or already closed. Pending operations are dropped by the kernel.

The next free submission entry, zeroed, or null when the submission queue is full (submit, then ask again). Fill it in (prep_rw, prep_nop or by hand), set user_data, and call submit. With IORING_SETUP_SQE128 the entry is 128 bytes: cast it to io_uring_sqe128.

Entries handed out by get_sqe and not yet submitted.

Publishes the entries handed out so far, so the kernel can see them, and returns how many it has not yet taken. Does not enter the kernel; submit does.

Publishes the pending entries and tells the kernel about them. Returns how many it took, or a negative errno (-EBUSY: completions are backed up, reap some first; -EAGAIN: out of resources).

submit, then sleeps until at least wait_for completions are ready.

Completions ready to be consumed.

The oldest unconsumed completion in cqe, without waiting: returns 0, or -EAGAIN when there is none. The pointer stays valid until cqe_seen. A ring that only produces completions when it enters the kernel (DEFER_TASKRUN, IOPOLL, or one with overflowed completions) is entered once to collect them.

Waits until a completion is ready and returns it in cqe (see peek_cqe). Submitted entries must have been passed to submit first. Returns 0 or a negative errno.

wait_cqe with a limit: returns -ETIME when no completion arrived within nanoseconds. Needs IORING_FEAT_EXT_ARG (Linux 5.11); returns -EOPNOTSUPP without it.

Marks cqe, the one peek_cqe or wait_cqe returned, as consumed, handing its slot back to the kernel. The pointer must not be used afterwards.

Consumes count completions at once (each CQE32 counts as one).

The buffer id of a completion that used a provided buffer (IORING_CQE_F_BUFFER).

Sets the fields most operations share: read, write, accept, send, recv... address and length describe the buffer, offset the file position (or the operation's second argument).

The 80 bytes of command data of a 128-byte entry (IORING_SETUP_SQE128), at offset 48.

Asks the kernel which operations it supports (IORING_REGISTER_PROBE, Linux 5.6). Returns 0, or -EINVAL on an older kernel, where only the original operations exist.

A 32-byte completion, as a ring created with IORING_SETUP_CQE32 delivers. Cast the *io_uring_cqe that peek_cqe and wait_cqe give you to this; extra is the 16 bytes the operation filled in.

A 128-byte submission entry, as a ring created with IORING_SETUP_SQE128 hands out. The first 64 bytes are an ordinary io_uring_sqe; sqe_command gives the 80 bytes of command data from offset 48.

Which opcodes the running kernel supports.

The three io_uring system calls. Each returns what the kernel returns: 0 or more on success and a negative errno on failure, never -1 with an errno to read afterwards. The numbers are the same on every Linux CPU that has io_uring (x86-64 and arm64 share the generic range).

errno values this module returns or tests for. They match on every Linux CPU.