119 lines
3.8 KiB
Groff
119 lines
3.8 KiB
Groff
.\" 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_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)
|