diff options
Diffstat (limited to 'man/io_uring_prep_cancel.3')
-rw-r--r-- | man/io_uring_prep_cancel.3 | 118 |
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) |