| .\" 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) |