1 files changed, 118 insertions, 0 deletions
diff --git a/man/io_uring_prep_cancel.3 b/man/io_uring_prep_cancel.3
new file mode 100644
index 0000000..3c9f2df
--- /dev/null
+++ b/man/io_uring_prep_cancel.3
@@ -0,0 +1,118 @@
+.\" 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)