.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
.\"
.\" SPDX-License-Identifier: LGPL-2.0-or-later
.\"
.TH io_uring_prep_cancel 3 "March 12, 2022" "liburing-2.2" "liburing Manual"
.SH NAME
io_uring_prep_cancel \- prepare a cancelation request
.SH SYNOPSIS
.nf
.B #include <liburing.h>
.PP
.BI "void io_uring_prep_cancel64(struct io_uring_sqe *" sqe ","
.BI "                            __u64 " user_data ","
.BI "                            int " flags ");"
.PP
.BI "void io_uring_prep_cancel(struct io_uring_sqe *" sqe ","
.BI "                          void *" user_data ","
.BI "                          int " flags ");"
.PP
.BI "void io_uring_prep_cancel_fd(struct io_uring_sqe *" sqe ","
.BI "                          int " fd ","
.BI "                          int " flags ");"
.fi
.SH DESCRIPTION
.PP
The
.BR io_uring_prep_cancel (3)
function prepares a cancelation request. The submission queue entry
.I sqe
is prepared to cancel an existing request identified by
.IR user_data .
For the
.I flags
argument, see below.

.BR io_uring_prep_cancel64 (3)
is identical to
.BR 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
.I user_data
and cancel it. The identifier is what the previously issued request has in
their
.I user_data
field in the SQE.

The
.BR io_uring_prep_cancel_fd (3)
function prepares a cancelation request. The submission queue entry
.I sqe
is prepared to cancel an existing request that used the file descriptor
.IR fd .
For the
.I flags
argument, see below.

The cancelation request will attempt to find the previously issued request
that used
.I 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:
.TP
.B IORING_ASYNC_CANCEL_ALL
Cancel all requests that match the given criteria, rather than just canceling
the first one found. Available since 5.19.
.TP
.B IORING_ASYNC_CANCEL_FD
Match based on the file descriptor used in the original request rather than
the user_data. This is what
.BR io_uring_prep_cancel_fd (3)
sets up. Available since 5.19.
.TP
.B IORING_ASYNC_CANCEL_FD_FIXED
Set in conjunction with
.B IORING_ASYNC_CANCEL_FD ,
indicating that the file descriptor given is a direct descriptor rather than
a normal file descriptor. Available since 6.0.
.TP
.B 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.
.P

.SH RETURN VALUE
None
.SH ERRORS
These are the errors that are reported in the CQE
.I res
field. If no flags are used to cancel multiple requests,
.B 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.
.TP
.B -ENOENT
The request identified by
.I 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.
.TP
.B -EINVAL
One of the fields set in the SQE was invalid.
.TP
.B -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.
.SH 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
.B -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.
.SH SEE ALSO
.BR io_uring_prep_poll_remove (3),
.BR io_uring_get_sqe (3),
.BR io_uring_submit (3)