AIO_READ(2)

✨ AIO_READ(2) ✨

okay bestie, welcome to the aio_read page in the System Calls Manual 💖 this is the "read from a file but make it asynchronous (REALTIME)" girlie, and she's iconic.

---

🌸 LIBRARY 🌸

Standard C Library (libc, -lc) — she lives in libc, obviously.

---

🎀 SYNOPSIS 🎀

#include <aio.h>

int
aio_read(struct aiocb *iocb);

---

💅 DESCRIPTION 💅

so the aio_read() system call lets the calling process read iocb->aio_nbytes from the descriptor iocb->aio_fildes, starting at the offset iocb->aio_offset, straight into the buffer pointed to by iocb->aio_buf. slay.

and here's the main character bit: the call returns immediately after the read request gets enqueued to the descriptor. so the read may or may not have actually finished by the time the call returns. it's giving "submitted my assignment, idk if it's graded yet" 😭

if _POSIX_PRIORITIZED_IO is defined, and the descriptor supports it, then the enqueued operation is submitted at a priority equal to that of the calling process minus iocb->aio_reqprio. math but make it ✨priority✨.

the iocb->aio_lio_opcode argument? yeah, the aio_read() system call ignores it entirely. not her business, not her problem 💀

you can keep using that iocb pointer afterwards as an argument to aio_return() and aio_error() to figure out the return or error status of the enqueued operation while it's still in progress. so useful, so thoughtful 🫶

if the request could not be enqueued (usually bc the arguments were invalid), then the call just returns without having enqueued anything. no harm, no foul.

⚠️ if the request is successfully enqueued, the value of iocb->aio_offset can be modified during the request as context — so that value must NOT be referenced after the request is enqueued. let it go, bestie.

the iocb->aio_sigevent structure can be used to request notification of the operation's completion, as described over in aio(4) 🔔

---

🦋 RESTRICTIONS 🦋

• The Asynchronous I/O Control Block structure pointed to by iocb and the buffer that the iocb->aio_buf member of that structure references must remain valid until the operation has completed. no early exits, they gotta stay for the whole show.
• The asynchronous I/O control buffer iocb should be zeroed before the aio_read() call, so you don't pass bogus context information to the kernel. zero it out, babe, it's the vibe ✨
• Modifications of the Asynchronous I/O Control Block structure or the buffer contents are not allowed while the request is queued. hands off 🙈
• If the file offset in iocb->aio_offset is past the offset maximum for iocb->aio_fildes, then no I/O will occur. nothing. nada. it's giving ghosted 💀

---

⭐ RETURN VALUES ⭐

The aio_read() function returns the value 0 if successful. otherwise, the value -1 is returned and the global variable errno is set to indicate the error. classic.

---

🍓 DIAGNOSTICS 🍓

None. literally nothing. silence. 🤐

---

💜 ERRORS 💜

The aio_read() system call will fail if:

• [EAGAIN] — The request was not queued because of system resource limitations. she's booked and busy, no room.
• [EINVAL] — The asynchronous notification method in iocb->aio_sigevent.sigev_notify is invalid or not supported.
• [EOPNOTSUPP] — Asynchronous read operations on the file descriptor iocb->aio_fildes are unsafe and unsafe asynchronous I/O operations are disabled.

---

the following conditions may be detected synchronously when the aio_read() system call is made, or asynchronously, at any time thereafter. so like, whenever. if they get detected at call time, aio_read() returns -1 and sets errno appropriately; otherwise you must call the aio_return() system call (which will return -1) and you must call aio_error() to determine the actual value that would have been returned in errno.

• [EBADF] — The iocb->aio_fildes argument is invalid.
• [EINVAL] — The offset iocb->aio_offset is not valid, the priority specified by iocb->aio_reqprio is not a valid priority, or the number of bytes specified by iocb->aio_nbytes is not valid.
• [EOVERFLOW] — The file is a regular file, iocb->aio_nbytes is greater than zero, the starting offset in iocb->aio_offset is before the end of the file, but is at or beyond the iocb->aio_fildes offset maximum.

---

if the request is successfully enqueued but subsequently gets cancelled or an error occurs, then the value returned by the aio_return() system call is per the read(2) system call, and the value returned by the aio_error() system call is either one of the error returns from the read(2) system call, or one of these:

• [EBADF] — The iocb->aio_fildes argument is invalid for reading.
• [ECANCELED] — The request was explicitly cancelled via a call to aio_cancel().
• [EINVAL] — The offset iocb->aio_offset would be invalid.

---

🌈 SEE ALSO 🌈

aio_cancel(2), aio_error(2), aio_return(2), aio_suspend(2), aio_waitcomplete(2), aio_write(2), sigevent(3), siginfo(3), aio(4)

go read those too, they're the friend group 💖

---

👑 STANDARDS 👑

The aio_read() system call is expected to conform to the IEEE Std 1003.1 (“POSIX.1”) standard. certified, no cap ✨

---

🧚 HISTORY 🧚

The aio_read() system call first appeared in FreeBSD 3.0. she's been around, she's a legend 🫶

---

🎀 AUTHORS 🎀

This manual page was written by Terry Lambert <terry@whistle.com>. thank you for your service, king 👑

---

💀 BUGS 💀

Invalid information in iocb->_aiocb_private may confuse the kernel. so like... don't do that. the kernel is sensitive 🙈

---

and that's the whole page bestie, you ate 💅 this one's from the Debian crew, dated August 19, 2016 — mwah, historic ✨