io_cancel(2)

✨ io_cancel(2) — the "never mind, bestie" of async I/O ✨

okay SO. welcome to io_cancel(2), straight out of the Linux System Calls Manual. this is the page you read when you've submitted async I/O and then had a change of heart 💅

---

🎀 NAME 🎀

io_cancel — cancel an outstanding asynchronous I/O operation

like... you literally just changed your mind and you need the kernel to hear you out 🫶

---

📚 LIBRARY 📚

Standard C library (libc, -lc)

yes bestie, it's -lc, the classic. you know her, you love her 💖

---

🌸 SYNOPSIS 🌸

#include <linux/aio_abi.h>    /* Definition of needed types */
#include <sys/syscall.h>      /* Definition of SYS_* constants */
#include <unistd.h>

int syscall(SYS_io_cancel, aio_context_t ctx_id, struct iocb *iocb,
            struct io_event *result);

okay so notice how it's syscall(SYS_io_cancel, ...) and not just io_cancel(...)?? that's on purpose!! that's the whole plot twist — scroll down to VERSIONS for the tea ☕

---

👑 DESCRIPTION 👑

Note: you probably want to use the io_getevents(3) wrapper function provided by libaio; see VERSIONS.

fr fr. that's the note. i'm not hiding it from you.

so here's the vibe: io_cancel() attempts to cancel an asynchronous I/O operation that you previously submitted with io_submit(2). 🦋

• the iocb argument describes the operation that's getting canceled (so like, which one did you want to walk back?)
• the ctx_id argument is the AIO context that the operation was submitted to (so like, which world does that operation live in?)

and then here's the slay part: if the operation is successfully canceled, the event will be copied into the memory pointed to by result without being placed into the completion queue. ✨

so it doesn't get queued up as a completion — it gets handed straight to result instead. no queue, no waiting, just a little direct deposit into your memory. that's iconic behavior.

---

💀 RETURN VALUE 💀

• on success, io_cancel() returns 0 🎉
• on error, -1 is returned, and errno is set to indicate the error 😭

---

🔥 ERRORS 🔥

here's the whole drama list, no skips:

• EAGAIN — the iocb specified was not canceled. yeah. she said no. 🙈
• EFAULT — one of the data structures points to invalid data. bad pointer energy fr.
• EINVAL — the AIO context specified by ctx_id is invalid.
• ENOSYS — io_cancel() is not implemented on this architecture. it's giving "not available in your region" 💀

---

🌈 VERSIONS 🌈

okay so this is the part you've been waiting for!! libaio provides a wrapper function with the same name, but different prototype and return value. 👀

same name, different personality. that's highkey confusing, i know.

You probably want to use that wrapper. 👑 — and that's the actual advice, not just me being cute. the wrapper is the one with the different prototype and the different return value, and it's the one you want.

---

⭐ STANDARDS ⭐

Linux. that's it. she's Linux-only. no POSIX passport, no portability passport. periodt. 💅

---

🕰️ HISTORY 🕰️

Linux 2.5.

throwback!! old money!! she's been around 🎀

---

🫶 SEE ALSO 🫶

• io_destroy(2)
• io_getevents(2)
• io_setup(2)
• io_submit(2)
• io_cancel(3)
• aio(7)

go read her sisters, they're all part of the same friend group 🦋✨

---

okay that's the page!! this was io_cancel(2) from Linux man-pages 6.20, and the whole thing was dated 2026-04-11 — yes bestie, fresh, current, iconic, no cap. go cancel your outstanding async I/O responsibly, and remember: if you wanted the wrapper, it's the wrapper. 💖🌸💅