io_uring_prep_cancel(3)

💖 io_uring_prep_cancel — bestie edition 💖

okay so this one lives in the liburing manual, and it's all about telling the kernel "hey. stop that. cancel that thing." 🛑

---

✨ NAME ✨

io_uring_prep_cancel — get a cancelation request ready to go ✨

---

🌸 SYNOPSIS 🌸

#include <liburing.h>

void io_uring_prep_cancel64(struct io_uring_sqe *sqe,
                            __u64 user_data,
                            int flags);

void io_uring_prep_cancel(struct io_uring_sqe *sqe,
                          const void *user_data,
                          int flags);

void io_uring_prep_cancel_fd(struct io_uring_sqe *sqe,
                          int fd,
                          unsigned int flags);

---

🦋 DESCRIPTION 🦋

io_uring_prep_cancel(3) sets up a cancelation request, bestie. It takes the submission queue entry sqe and preps it to cancel an existing request — and it finds that request by its user_data. Wanna know about the flags arg? Scroll down, it's all there 💅

io_uring_prep_cancel64(3) is literally the same as io_uring_prep_cancel(3), except it takes a 64-bit integer instead of a pointer type. that's it. that's the diff. 👑

So what happens: the cancelation request goes looking for the request you already issued, matching on user_data, and cancels it. And where does that identifier come from? It's whatever the previously issued request put in its user_data field in the SQE. iykyk 🫶

Then there's io_uring_prep_cancel_fd(3), which preps a cancelation request too — the sqe gets set up to cancel an existing request that used the file descriptor fd. The flags argument? Again, see below 🌈

This cancelation request hunts down the previously issued request that used fd as its file descriptor, and cancels it. periodt.

By default, only the first request matching the criteria gets canceled. Wanna change that? Pass any of these bad boys in the flags:

• IORING_ASYNC_CANCEL_ALL — cancel all the requests that match the criteria, not just the first one found. Available since 5.19. it's giving "no leftovers" 💅
• IORING_ASYNC_CANCEL_FD — match based on the file descriptor used in the original request instead of the user_data. This is the one io_uring_prep_cancel_fd(3) sets up for you. Available since 5.19.
• IORING_ASYNC_CANCEL_FD_FIXED — set this together with IORING_ASYNC_CANCEL_FD, and it means the file descriptor you're handing over is a direct descriptor, not a normal file descriptor. Available since 6.0.
• IORING_ASYNC_CANCEL_ANY — match any request in the ring, no matter the user_data or file descriptor. Basically "cancel whatever's pending in here, idc". Available since 5.19.
• IORING_ASYNC_CANCEL_USERDATA — match a request based on the user data field set in the original request. This is the default lookup key when you haven't specified any other key matching. Available since 6.6.
• IORING_ASYNC_CANCEL_OP — use the original request opcode as the matching key. You set that requested opcode in the sqe len field, after using one of the generic cancel preparation helpers. Available since 6.6.

---

🎀 RETURN VALUE 🎀

None. nothing. zero. it's a prep function, she just preps 💅

---

💀 ERRORS 💀

These are the errors that show up in the CQE res field. Here's the tea:

• If you didn't use any flags to cancel multiple requests, then 0 is returned on success.
• If you did use flags to match multiple requests, then a positive value comes back, telling you how many requests were found and canceled. slay.

Now the actual errors:

• -ENOENT — that request identified by user_data could not be located 😭. Maybe it already completed before you even issued the cancelation request, or maybe you used an invalid identifier. either way, she's not there.
• -EINVAL — one of the fields you set in the SQE was invalid. 🙈
• -EALREADY — the request's execution state has already progressed far enough that cancelation just isn't possible anymore. This normally means it'll complete shortly — either successfully, or interrupted because of the cancelation. it's giving "too late bestie" ⏳

---

🌟 NOTES 🌟

Okay this part is important, so listen up 👑

Even though 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 you targeted will already have been posted by the time submission returns. 💖

For -EALREADY though? It may take a bit of time to do so. In that case, the caller must wait for the canceled request to post its completion event. no skipping this step, fr fr 🫡

---

🔥 SEE ALSO 🔥

io_uring_prep_poll_remove(3), io_uring_get_sqe(3), io_uring_submit(3)

---

and that's the whole page, bestie 🧚✨ this one shipped as liburing-2.2, dated March 12, 2022 — go forth and cancel responsibly, ily 💜🌸