1io_uring_prep_cancel(3) liburing Manual io_uring_prep_cancel(3)
2
6 io_uring_prep_cancel - prepare a cancelation request
7
9 #include <liburing.h>
10 void io_uring_prep_cancel64(struct io_uring_sqe *sqe,
12 __u64 user_data,
13 int flags);
14 void io_uring_prep_cancel(struct io_uring_sqe *sqe,
16 void *user_data,
17 int flags);
18 void io_uring_prep_cancel_fd(struct io_uring_sqe *sqe,
20 int fd,
21 int flags);
22
24 The io_uring_prep_cancel(3) function prepares a cancelation request.
25 The submission queue entry sqe is prepared to cancel an existing re‐
26 quest identified by user_data. For the flags argument, see below.
27 io_uring_prep_cancel64(3) is identical to io_uring_prep_cancel(3), ex‐
29 cept it takes a 64-bit integer rather than a pointer type.
30 The cancelation request will attempt to find the previously issued re‐
32 quest identified by user_data and cancel it. The identifier is what the
33 previously issued request has in their user_data field in the SQE.
34 The io_uring_prep_cancel_fd(3) function prepares a cancelation request.
36 The submission queue entry sqe is prepared to cancel an existing re‐
37 quest that used the file descriptor fd. For the flags argument, see
38 below.
39 The cancelation request will attempt to find the previously issued re‐
41 quest that used fd as the file descriptor and cancel it.
42 By default, the first request matching the criteria given will be can‐
44 celed. This can be modified with any of the following flags passed in:
45 IORING_ASYNC_CANCEL_ALL
47 Cancel all requests that match the given criteria, rather than
48 just canceling the first one found. Available since 5.19.
49 IORING_ASYNC_CANCEL_FD
51 Match based on the file descriptor used in the original request
52 rather than the user_data. This is what io_uring_prep_can‐
53 cel_fd(3) sets up. Available since 5.19.
54 IORING_ASYNC_CANCEL_ANY
56 Match any request in the ring, regardless of user_data or file
57 descriptor. Can be used to cancel any pending request in the
58 ring. Available since 5.19.
59
61 None
62
64 These are the errors that are reported in the CQE res field. If no
65 flags are used to cancel multiple requests, 0 is returned on success.
66 If flags are used to match multiple requests, then a positive value is
67 returned indicating how many requests were found and canceled.
68 -ENOENT
70 The request identified by user_data could not be located. This
71 could be because it completed before the cancelation request was
72 issued, or if an invalid identifier is used.
73 -EINVAL
75 One of the fields set in the SQE was invalid.
76 -EALREADY
78 The execution state of the request has progressed far enough
79 that cancelation is no longer possible. This should normally
80 mean that it will complete shortly, either successfully, or in‐
81 terrupted due to the cancelation.
82
84 Although the cancelation request uses async request syntax, the kernel
85 side of the cancelation is always run synchronously. It is guaranteed
86 that a CQE is always generated by the time the cancel request has been
87 submitted. If the cancelation is successful, the completion for the re‐
88 quest targeted for cancelation will have been posted by the time sub‐
89 mission returns. For -EALREADY it may take a bit of time to do so. For
90 this case, the caller must wait for the canceled request to post its
91 completion event.
92
94 io_uring_prep_poll_remove(3), io_uring_get_sqe(3), io_uring_submit(3)
95liburing-2.2 March 12, 2022 io_uring_prep_cancel(3)