io_cancel(3)

💖 io_cancel(3) — the Linux AIO girlies' guide to cancelling ur io requests 💖

okay so bestie, welcome to io_cancel from the Linux AIO manual (that's section 3, library calls, iykyk) ✨ this one is literally about calling off io requests you already sent out. no cap, it's giving "unsend that message" energy 🫶

✨ NAME ✨

io_cancel — cancel io requests 💅

🌸 SYNOPSIS 🌸

#include <errno.h>

#include <libaio.h>

int io_cancel(io_context_t ctx, struct iocb *iocb);

struct iocb {
     void      *data; /* Return in the io completion event */
     unsigned  key; /* For use in identifying io requests */
     short          aio_lio_opcode;
     short          aio_reqprio;   /* Not used */
     int       aio_fildes;
};

yes queen, that struct is exactly as it appears, don't you dare touch a character of it 😭

🦋 DESCRIPTION 🦋

So like — this function attempts to cancel an iocb that you previously passed to io_submit(3). 🎀

If the operation gets successfully cancelled, the resulting event is copied into the memory pointed to by result without being placed into the completion queue. iconic behavior honestly ✨

And here's when you'd actually want this: when one or more requests are being processed asynchronously, it might be useful in some situations to cancel a selected operation. Like, for example, if it becomes obvious that the written data is no longer accurate and would have to be overwritten soon 👀. The example the manpage gives: assume an application which writes data in files, in a situation where new incoming data would have to be written in a file which will be updated by an enqueued request. very "oops that draft was stale" of it 💀

💅 RETURN VALUES 💅

0 is returned on success — slay 💖 — otherwise it returns errno. yep, we're in errno territory, bestie.

🎀 ERRORS 🎀

• EFAULT — if any of the data structures pointed to are invalid. girl those pointers are not pointing anywhere good 😭
• EINVAL — if the aio_context specified by ctx is invalid. nope, that context is not it 🙈
• EAGAIN — if the iocb specified was not cancelled. it said "no <3" 💀
• ENOSYS — if not implemented. literally not a thing here, sorry bestie 🌸

👑 SEE ALSO 👑

io(3), io_fsync(3), io_getevents(3), io_prep_fsync(3), io_prep_pread(3), io_prep_pwrite(3), io_queue_init(3), io_queue_release(3), io_queue_run(3), io_queue_wait(3), io_set_callback(3), io_submit(3), errno(3).

friendly reminder bestie: the whole point is that a successful cancel means the event lands where result points and does not go into the completion queue. don't go looking for it there, she's not coming 💜

okay that's the whole page!! 💖 this version of the page is from the Linux manual, dated 2019-07-23, and it's io_cancel(3) — go forth and cancel responsibly, mwah 🎀🦋✨