uring

Issue the equivalent of an accept4(2) system call.

See also accept4(2) for the general description of the related system call.

If the file_index field is set to a positive number, the file won't be installed into the normal file table as usual but will be placed into the fixed file table at index file_index - 1. In this case, instead of returning a file descriptor, the result will contain either 0 on success or an error. If the index points to a valid empty slot, the installation is guaranteed to not fail. If there is already a file in the slot, it will be replaced, similar to IORING_OP_FILES_UPDATE. Please note that only uring has access to such files and no other syscall can use them. See IOSQE_FIXED_FILE and IORING_REGISTER_FILES.

Available since 5.5.

Attempt to cancel an already issued request.

The request is identified by it's user data.

The cancelation request will complete with one of the following results codes.

If found, the res field of the cqe will contain 0. If not found, res will contain -ENOENT.

If found and attempted canceled, the res field will contain -EALREADY. In this case, the request may or may not terminate. In general, requests that are interruptible (like socket IO) will get canceled, while disk IO requests cannot be canceled if already started.

Available since 5.5.

Issues the equivalent of the bind(2) system call.

Available since 6.11.

Issue the equivalent of a close(2) system call.

See also close(2) for the general description of the related system call.

Available since 5.6.

If the file_index field is set to a positive number, this command can be used to close files that were direct opened through IORING_OP_OPENAT, IORING_OP_OPENAT2, or IORING_OP_ACCEPT using the uring specific direct descriptors. Note that only one of the descriptor fields may be set. The direct close feature is available since the 5.15 kernel, where direct descriptors were introduced.

Issue the equivalent of a connect(2) system call.

See also connect(2) for the general description of the related system call.

Available since 5.5.

Copies as many CQEs as are ready, and that can fit into the destination cqes slice. If none are available, enters into the kernel to wait for at most wait_nr CQEs. Returns the number of CQEs copied, advancing the CQ ring. Provides all the wait/peek methods found in liburing, but with batching and a single method. TODO: allow for timeout.

For advanced use cases only that implement custom completion queue methods. Matches the implementation of cq_advance() in liburing.

Returns the number of completion queue entries in the completion queue (yet to consume).

For advanced use cases only that implement custom completion queue methods. If you use copy_cqes() or copy_cqe() you must not call cqe_seen() or cq_advance(). Must be called exactly once after a zero-copy CQE has been processed by your application. Not idempotent, calling more than once will result in other CQEs being lost. Matches the implementation of cqe_seen() in liburing.

Add, remove or modify entries in the interest list of epoll(7).

See epoll_ctl(2) for details of the system call.

Available since 5.6.

This command is an alternative to using IORING_REGISTER_FILES_UPDATE which then works in an async fashion, like the rest of the uring commands.

Note that the array of file descriptors pointed to in addr must remain valid until this operation has completed.

Available since 5.6.

Sync internal state with kernel ring state on the submission queue side. Returns the number of all pending events in the submission queue. Rationale is to determine that an enter call is needed.

File sync. See also fsync(2).

Optionally off and len can be used to specify a range within the file to be synced rather than syncing the entire file, which is the default behavior.

Note that, while I/O is initiated in the order in which it appears in the submission queue, completions are unordered. For example, an application which places a write I/O followed by an fsync in the submission queue cannot expect the fsync to apply to the write. The two operations execute in parallel, so the fsync may complete before the write is issued to the storage. The same is also true for previously issued writes that have not completed prior to the fsync. To enforce ordering one may utilize linked SQEs, IOSQE_IO_DRAIN or wait for the arrival of CQEs of requests which have to be ordered before a given request before submitting its SQE.

Returns a pointer to a vacant submission queue entry, or nil if the submission queue is full. NOTE: extra is so you can make sure there is space for related entries, defaults to 1 so a link timeout op can always be added after another.

Initialize and setup an uring, entries must be a power of 2 between 1 and 4096.

Adds a link timeout operation.

You need to set linux.IOSQE_IO_LINK to flags of the target operation and then call this method right after the target operation. See https://lwn.net/Articles/803932/ for detail.

If the dependent request finishes before the linked timeout, the timeout is canceled. If the timeout finishes before the dependent request, the dependent request will be canceled.

The completion event result of the link_timeout will be -ETIME if the timeout finishes before the dependent request (in this case, the completion event result of the dependent request will be -ECANCELED), or -EALREADY if the dependent request finishes before the linked timeout.

Available since 5.5.

Issues the equivalent of the listen(2) system call.

fd must contain the file descriptor of the socket and addr must contain the backlog parameter, i.e. the maximum amount of pending queued connections.

Available since 6.11.

Issue the equivalent of a madvise(2) system call.

See also madvise(2) for the general description of the related system call.

Available since 5.6.

Do not perform any I/O. This is useful for testing the performance of the uring implementation itself.

Issue the equivalent of a openat(2) system call.

See also openat(2) for the general description of the related system call.

Available since 5.6.

If the file_index is set to a positive number, the file won't be installed into the normal file table as usual but will be placed into the fixed file table at index file_index - 1. In this case, instead of returning a file descriptor, the result will contain either 0 on success or an error. If the index points to a valid empty slot, the installation is guaranteed to not fail. If there is already a file in the slot, it will be replaced, similar to IORING_OP_FILES_UPDATE. Please note that only uring has access to such files and no other syscall can use them. See IOSQE_FIXED_FILE and IORING_REGISTER_FILES.

Available since 5.15.

Poll the fd specified in the submission queue entry for the events specified in the poll_events field.

Unlike poll or epoll without EPOLLONESHOT, by default this interface always works in one shot mode. That is, once the poll operation is completed, it will have to be resubmitted.

If IORING_POLL_ADD_MULTI is set in the SQE len field, then the poll will work in multi shot mode instead. That means it'll repatedly trigger when the requested event becomes true, and hence multiple CQEs can be generated from this single SQE. The CQE flags field will have IORING_CQE_F_MORE set on completion if the application should expect further CQE entries from the original request. If this flag isn't set on completion, then the poll request has been terminated and no further events will be generated. This mode is available since 5.13.

This command works like an async poll(2) and the completion event result is the returned mask of events.

Without IORING_POLL_ADD_MULTI and the initial poll operation with IORING_POLL_ADD_MULTI the operation is level triggered, i.e. if there is data ready or events pending etc. at the time of submission a corresponding CQE will be posted. Potential further completions beyond the first caused by a IORING_POLL_ADD_MULTI are edge triggered.

Remove an existing poll request.

If found, the res field of the struct io_uring_cqe will contain 0. If not found, res will contain -ENOENT, or -EALREADY if the poll request was in the process of completing already.

Update the events of an existing poll request.

The request will update an existing poll request with the mask of events passed in with this request. The lookup is based on the user_data field of the original SQE submitted.

Updating an existing poll is available since 5.13.

Update the user data of an existing poll request.

The request will update the user_data of an existing poll request based on the value passed.

Updating an existing poll is available since 5.13.

Issue the equivalent of a pread(2) system call.

If offset is set to -1 , the offset will use (and advance) the file position, like the read(2) system calls. These are non-vectored versions of the IORING_OP_READV and IORING_OP_WRITEV opcodes. See also read(2) for the general description of the related system call.

Available since 5.6.

Vectored read operation, see also readv(2).

Works just like send, but receives instead of sends.

poll_first: If set, uring will assume the socket is currently empty and attempting to receive data will be unsuccessful. For this case, uring will arm internal poll and trigger a receive of the data when the socket has data to be read. This initial receive attempt can be wasteful for the case where the socket is expected to be empty, setting this flag will bypass the initial receive attempt and go straight to arming poll. If poll does indicate that data is ready to be received, the operation will proceed.

Available since 5.6.

Works just like sendmsg, but receives instead of sends.

poll_first: If set, uring will assume the socket is currently empty and attempting to receive data will be unsuccessful. For this case, uring will arm internal poll and trigger a receive of the data when the socket has data to be read. This initial receive attempt can be wasteful for the case where the socket is expected to be empty, setting this flag will bypass the initial receive attempt and go straight to arming poll. If poll does indicate that data is ready to be received, the operation will proceed.

Available since 5.3.

Issue the equivalent of a send(2) system call.

See also send(2) for the general description of the related system call.

poll_first: If set, uring will assume the socket is currently full and attempting to send data will be unsuccessful. For this case, uring will arm internal poll and trigger a send of the data when there is enough space available. This initial send attempt can be wasteful for the case where the socket is expected to be full, setting this flag will bypass the initial send attempt and go straight to arming poll. If poll does indicate that data can be sent, the operation will proceed.

Available since 5.6.

Issue the equivalent of a sendmsg(2) system call.

See also sendmsg(2) for the general description of the related system call.

poll_first: if set, uring will assume the socket is currently full and attempting to send data will be unsuccessful. For this case, uring will arm internal poll and trigger a send of the data when there is enough space available. This initial send attempt can be wasteful for the case where the socket is expected to be full, setting this flag will bypass the initial send attempt and go straight to arming poll. If poll does indicate that data can be sent, the operation will proceed.

Available since 5.3.

Issue the equivalent of a shutdown(2) system call.

Available since 5.11.

Issue the equivalent of a socket(2) system call.

See also socket(2) for the general description of the related system call.

Available since 5.19.

If the file_index field is set to a positive number, the file won't be installed into the normal file table as usual but will be placed into the fixed file table at index file_index - 1. In this case, instead of returning a file descriptor, the result will contain either 0 on success or an error. If the index points to a valid empty slot, the installation is guaranteed to not fail. If there is already a file in the slot, it will be replaced, similar to IORING_OP_FILES_UPDATE. Please note that only uring has access to such files and no other syscall can use them. See IOSQE_FIXED_FILE and IORING_REGISTER_FILES.

Issue the equivalent of a splice(2) system call.

A sentinel value of -1 is used to pass the equivalent of a NULL for the offsets to splice(2).

Please note that one of the file descriptors must refer to a pipe. See also splice(2) for the general description of the related system call.

Available since 5.7.

Returns the number of submission queue entries in the submission queue.

Returns true if we are not using an SQ thread (thus nobody submits but us), or if IORING_SQ_NEED_WAKEUP is set and the SQ thread must be explicitly awakened. For the latter case, we set the SQ thread wakeup flag. Matches the implementation of sq_ring_needs_enter() in liburing.

Issue the equivalent of a statx(2) system call.

See also statx(2) for the general description of the related system call.

Available since 5.6.

Submits the submission queue entries acquired via get_sqe(). Returns the number of entries submitted. Optionally wait for a number of events by setting wait_nr, and/or set a maximum wait time by setting timeout.

Issue the equivalent of a tee(2) system call.

Please note that both of the file descriptors must refer to a pipe. See also tee(2) for the general description of the related system call.

Available since 5.8.

Register a timeout operation.

The timeout will complete when either the timeout expires, or after the specified number of events complete (if count is greater than 0).

flags may be 0 for a relative timeout, or IORING_TIMEOUT_ABS for an absolute timeout.

The completion event result will be -ETIME if the timeout completed through expiration, 0 if the timeout completed after the specified number of events, or -ECANCELED if the timeout was removed before it expired.

uring timeouts use the CLOCK.MONOTONIC clock source.

Rmove an existing timeout operation.

The timeout is identified by it's user_data.

The completion event result will be 0 if the timeout was found and cancelled successfully, -EBUSY if the timeout was found but expiration was already in progress, or -ENOENT if the timeout was not found.

Issue the equivalent of a pwrite(2) system call.

If offset is set to -1 , the offset will use (and advance) the file position, like the read(2) system calls. These are non-vectored versions of the IORING_OP_READV and IORING_OP_WRITEV opcodes. See also write(2) for the general description of the related system call.

Available since 5.6.

Vectored write operation, see also writev(2).