aio_read(3)

💖 aio_read — asynchronous read 💖

okay bestie, welcome to the aio_read(3) page, from the Library Functions Manual ✨ this one lives in the Real-time library (librt, link with -lrt) and it's literally the async girlboss version of read(2). let's get into it 🫶

---

✨ SYNOPSIS ✨

#include <aio.h>

int aio_read(struct aiocb *aiocbp);

---

🌸 DESCRIPTION 🌸

so basically, aio_read() queues up the I/O request that's described by the buffer that aiocbp points at. it's the asynchronous analog of read(2), no cap. the arguments of this call:

read(fd, buf, count)

correspond in order to the fields aio_fildes, aio_buf, and aio_nbytes of the structure that aiocbp points to. (if you wanna know what the aiocb structure even is, go peek at aio(7) 👀)

the data gets read starting at the absolute position aiocbp->aio_offset, completely regardless of the file offset. and after the call? the value of the file offset is unspecified. like, we don't know her. 🤷♀️

the whole "asynchronous" thing means this call returns the second the request has been enqueued — the read may or may not have completed by the time the call comes back. to test for completion you use aio_error(3). to get the return status of a completed I/O operation you use aio_return(3). and if you want asynchronous notification that the I/O finished, you set aiocbp->aio_sigevent appropriately — full details are in sigevent(3type) 💅

if _POSIX_PRIORITIZED_IO is defined, and this file supports it, then the async operation gets submitted at a priority equal to the priority of the calling process minus aiocbp->aio_reqprio. math queen 🧮

the field aiocbp->aio_lio_opcode is ignored. she's not invited to the party 🙈

and no data is read from a regular file beyond its maximum offset. periodt.

---

🔥 RETURN VALUE 🔥

• on success, 0 is returned ✨
• on error, the request is not enqueued, -1 is returned, and errno gets set to indicate the error.

now if an error only gets detected later, it'll be reported through aio_return(3) (which returns status -1) and aio_error(3) (the error status — literally whatever you would have gotten in errno, like EBADF). sneaky but that's the deal 😭

---

💀 ERRORS 💀

• EAGAIN — out of resources. bestie is tired. 😮‍💨
• EBADF — aio_fildes is not a valid file descriptor open for reading. not it. 🙅♀️
• EINVAL — one or more of aio_offset, aio_reqprio, or aio_nbytes are invalid. vibe check failed 💔
• ENOSYS — aio_read() is not implemented. she does not exist here, i fear 👻
• EOVERFLOW — the file is a regular file, we start reading before end-of-file and want at least one byte, but the starting position is past the maximum offset for this file. that's giving off the map 🗺️💀

---

🎀 ATTRIBUTES 🎀

for an explanation of the terms used in this section, see attributes(7).

• Interface: aio_read()
• Attribute: Thread safety
• Value: MT-Safe ✅

slay, she's thread safe, no notes 💅

---

⭐ STANDARDS ⭐

POSIX.1-2008. iconic behavior, honestly 👑

---

🦋 HISTORY 🦋

• glibc 2.1
• POSIX.1-2001

a true veteran of the game, we love a legacy queen 🌈

---

🌸 NOTES 🌸

okay listen up, this part is important so pay attention bestie:

• it's a good idea to zero out the control block before you use it. do it. 🧼
• the control block must not be changed while the read operation is in progress. hands off. ✋
• the buffer area being read into must not be accessed during the operation — or undefined results may occur. i'm serious, don't touch it 😭
• the memory areas involved must remain valid. keep them alive, hydrate them, whatever 🌊
• simultaneous I/O operations that specify the same aiocb structure produce undefined results. don't share, it's not cute 💀

no cap, these aren't suggestions. undefined results are the "we don't talk about it" of C programming. 🙈

---

✨ EXAMPLES ✨

see aio(7) — she's got the whole demo, iykyk 🧚

---

👑 SEE ALSO 👑

aio_cancel(3), aio_error(3), aio_fsync(3), aio_return(3), aio_suspend(3), aio_write(3), lio_listio(3), aio(7)

---

and that's the whole page, bestie!! 🎀 this one came from Linux man-pages 6.20, dated 2026-02-08, and the original title said aio_read(3) up top with the manual name Library Functions Manual. go queue some reads, stay async, and remember: don't touch the buffer mid-operation 💖✨🫶