.\" 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
.fi
.SH SYNOPSIS
.nf
.BR "#include <liburing.h>"
.PP
.BI "void io_uring_prep_cancel(struct io_uring_sqe *sqe,"
.BI "                          __u64 user_data,"
.BI "                          int flags)"
.PP
.SH DESCRIPTION
.PP
The io_uring_prep_cancel() function prepares a cancelation request. The
submission queue entry
.I sqe
is prepared to cancel an existing request identified by
.I user_data.
The
.I flags
argument is currently unused.

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.

.SH RETURN VALUE
None
.SH ERRORS
These are the errors that are reported in the CQE
.I res
field. On success,
.B 0
is returned.
.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 SEE ALSO
.BR io_uring_get_sqe (3), io_uring_submit (3)

Add cancelation request man page
Add cancelation request man page

Signed-off-by: Jens Axboe <cd8c6775e60d6f67a6984377324e5290df3d5358@kernel.dk>
