io_uring_prep_cancel - prepare a cancelation request
#include <liburing.h>
void io_uring_prep_cancel64(struct io_uring_sqe *sqe,
__u64 user_data,
int flags);
void io_uring_prep_cancel(struct io_uring_sqe *sqe,
void *user_data,
int flags);
void io_uring_prep_cancel_fd(struct io_uring_sqe *sqe,
int fd,
int flags);
The
io_uring_prep_cancel(3) function prepares a cancelation request. The
submission queue entry
sqe is prepared to cancel an existing request
identified by
user_data. For the
flags argument, see below.
is identical to
io_uring_prep_cancel(3), except it takes a 64-bit integer rather
than a pointer type.
The cancelation request will attempt to find the previously issued request
identified by
user_data and cancel it. The identifier is what the
previously issued request has in their
user_data field in the SQE.
The
io_uring_prep_cancel_fd(3) function prepares a cancelation request.
The submission queue entry
sqe is prepared to cancel an existing
request that used the file descriptor
fd. For the
flags
argument, see below.
The cancelation request will attempt to find the previously issued request that
used
fd as the file descriptor and cancel it.
By default, the first request matching the criteria given will be canceled. This
can be modified with any of the following flags passed in:
- IORING_ASYNC_CANCEL_ALL
- Cancel all requests that match the given criteria, rather
than just canceling the first one found. Available since 5.19.
- IORING_ASYNC_CANCEL_FD
- Match based on the file descriptor used in the original
request rather than the user_data. This is what
io_uring_prep_cancel_fd(3) sets up. Available since 5.19.
- IORING_ASYNC_CANCEL_ANY
- Match any request in the ring, regardless of user_data or
file descriptor. Can be used to cancel any pending request in the ring.
Available since 5.19.
None
These are the errors that are reported in the CQE
res field. If no flags
are used to cancel multiple requests,
0 is returned on success. If
flags are used to match multiple requests, then a positive value is returned
indicating how many requests were found and canceled.
- -ENOENT
- The request identified by user_data could not be
located. This could be because it completed before the cancelation request
was issued, or if an invalid identifier is used.
- -EINVAL
- One of the fields set in the SQE was invalid.
- -EALREADY
- The execution state of the request has progressed far
enough that cancelation is no longer possible. This should normally mean
that it will complete shortly, either successfully, or interrupted due to
the cancelation.
Although the cancelation request uses async request syntax, the kernel side of
the cancelation is always run synchronously. It is guaranteed that a CQE is
always generated by the time the cancel request has been submitted. If the
cancelation is successful, the completion for the request targeted for
cancelation will have been posted by the time submission returns. For
-EALREADY it may take a bit of time to do so. For this case, the caller
must wait for the canceled request to post its completion event.
io_uring_prep_poll_remove(3),
io_uring_get_sqe(3),
io_uring_submit(3)