AIO_CANCEL(2)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💅 AIO_CANCEL 💅 (like, the System Calls Manual, bestie ✨)

Okay so before we even get into it — this whole page lives in the System Calls Manual section, and we're about to talk about cancelling async I/O. Try to stay calm. 🫶

✨ NAME ✨

aio_cancel — cancel an outstanding asynchronous I/O operation (and yes it's REALTIME, no cap) 💅

🎀 LIBRARY 🎀

Standard C Library (libc, -lc). Your girl's been hanging out there. 🦋

🌸 SYNOPSIS 🌸

#include <aio.h>

int
aio_cancel(int fildes, struct aiocb *iocb);

That's it. That's the whole signature. Obsessed. 💖

🌈 DESCRIPTION 🌈

So the aio_cancel() system call does exactly what it says on the tin: it cancels the outstanding asynchronous I/O request for the file descriptor you passed in fildes. Main character energy fr. 👑

And if you also specify iocb? Then it only cancels that specific asynchronous I/O request. Like, super targeted. Not me being picky, just being precise. 🎯

Normal asynchronous notification still occurs for cancelled requests (the system doesn't ghost you, it tells you what happened 🫶), and those requests complete with an error result of ECANCELED.

💀 RESTRICTIONS 💀 (read this part, bestie)

The aio_cancel() system call does not cancel asynchronous I/O requests for raw disk devices. Like, at all. 😭

And for file descriptors associated with raw disk devices? aio_cancel() will always return AIO_NOTCANCELED. Every time. No exceptions. It's giving "the vibes are immovable." 💀

🔥 RETURN VALUES 🔥

So aio_cancel() returns -1 to indicate an error, or one of these iconic little values:

  • [AIO_CANCELED] — All outstanding requests meeting the criteria specified were cancelled. Slay. ✨
  • [AIO_NOTCANCELED] — Some requests were not cancelled (rude), so you should check the status for those requests with aio_error(2). Go check, bestie, don't just assume. 🙈
  • [AIO_ALLDONE] — All of the requests meeting the criteria have already finished. Like, they're done-done. Periodt. 💅

🌺 ERRORS 🌺

When aio_cancel() returns an error, it's telling you:

  • [EBADF] — The fildes argument is an invalid file descriptor. Babe, that fd is not real. Check it. 😭

🦋 SEE ALSO 🦋

Go read these next, they're all part of the same universe:

iykyk 💜

⭐ STANDARDS ⭐

The aio_cancel() system call is expected to conform to the IEEE Std 1003.1 (“POSIX.1”) standard. So like, it's official official. 🎀

🧚 HISTORY 🧚

The aio_cancel() system call first appeared in FreeBSD 3.0. Then the first functional implementation of aio_cancel() appeared in FreeBSD 4.0. So the glow-up was real. ✨

💖 AUTHORS 💖

This manual page was originally written by Wes Peters <wes@softweyr.com>. And Christopher M Sedore <cmsedore@maxwell.syr.edu> updated it when aio_cancel() was implemented for FreeBSD 4.0. Legends, honestly. 👑

Okay bye bestie, go cancel some async I/O (except on raw disk devices, you know the vibes now) — this page is from Debian, dated January 19, 2000, from the System Calls Manual, and it ate. 💅✨🦋

📦 where this page comes from