Prepare a cancelation request
# DESCRIPTION
The [io_uring_prep_cancel] 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.
[io_uring_prep_cancel64] is identical to
[io_uring_prep_cancel]**,** 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] 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] sets up.
Available since 5.19.
**IORING_ASYNC_CANCEL_FD_FIXED**\
Set in conjunction with **IORING_ASYNC_CANCEL_FD ,** indicating that the
file descriptor given is a direct descriptor rather than a normal file
descriptor. Available since 6.0.
**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.
**IORING_ASYNC_CANCEL_USERDATA**\
Match request based on the user data field set in the original request.
This is the default lookup key, if no other key matching has been
specified. Available since 6.6.
**IORING_ASYNC_CANCEL_OP**\
Use the original request opcode as the matching key. The opcopde
requested must be set in the sqe *len* field after using one of the
generic cancel preparation helpers. Available since 6.6.
# RETURN VALUE
None
# ERRORS
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.
# NOTES
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.
# SEE ALSO
[io_uring_prep_poll_remove], [io_uring_get_sqe],
[io_uring_submit]