lio_listio(3)

✨ lio_listio — initiate a list of I/O requests ✨

okay bestie, so lio_listio(3) is a library function and it lives in the Real-time library — that's librt, so you link it with -lrt. 💖

---

🎀 SYNOPSIS 🎀

#include <aio.h>

int lio_listio(int n;
               int mode,
               struct aiocb *restrict const aiocb_list[restrict n],
               int n, struct sigevent *restrict sevp);

---

🌸 DESCRIPTION 🌸

So basically, lio_listio() kicks off a whole list of I/O operations — the ones described by the array aiocb_list. Like, an entire group chat of I/O requests, all at once. 💅

The mode argument (yes, the manpage calls it "the mode operation", we move) takes one of these values:

• LIO_WAIT — the call just... blocks. Sits there. Stays seated until every single operation is done. And the sevp argument? Ignored. Not even looked at. 🙈
• LIO_NOWAIT — the I/O operations get queued up for processing and the call returns immediately, no waiting around, we are booked and busy. Then when all of the I/O operations complete, asynchronous notification occurs, exactly as specified by the sevp argument — go check sigevent(3type) for the deets. And if sevp is NULL, then no asynchronous notification happens at all. Silence. Nothing. 🦋

The aiocb_list argument is an array of pointers to aiocb structures that describe the I/O operations. And heads up: these operations are executed in an unspecified order — so do not come for me about ordering, it's giving chaos and that's on purpose. The n argument says how big the aiocb_list array is. And null pointers in aiocb_list? Ignored. Not our problem, we skip right past them. ✨

Now, inside each control block in aiocb_list, there's a field called aio_lio_opcode and it tells you which I/O operation to initiate, like this:

• LIO_READ — initiate a read operation. It gets queued exactly like a call to aio_read(3) with this control block. 📖
• LIO_WRITE — initiate a write operation. It gets queued exactly like a call to aio_write(3) with this control block. ✍️
• LIO_NOP — ignore this control block entirely. Nothing to see here, moving on. 💀

All the other fields in each control block mean the same things they mean for aio_read(3) and aio_write(3). And the aio_sigevent fields of each control block can be used to specify notifications for the individual I/O operations — see sigevent(7) for that. 👑

---

🔥 RETURN VALUE 🔥

If mode is LIO_NOWAIT, lio_listio() returns 0 when all the I/O operations are successfully queued. Otherwise it returns -1, and errno gets set to tell you what went wrong. 😭

If mode is LIO_WAIT, lio_listio() returns 0 when all of the I/O operations have completed successfully. Otherwise, again, -1 is returned and errno is set to indicate the error.

⚠️ Now listen, this part matters: the return status from lio_listio() gives you info only about the call itself, not about the individual I/O operations. One or more of the I/O operations may fail, and that does not stop the other operations from completing. So if you wanna know the status of the individual operations in aiocb_list, use aio_error(3). And once an operation has completed, you get its return status with aio_return(3). Individual I/O operations can fail for all the reasons described over in aio_read(3) and aio_write(3). fr fr. 🫶

---

💀 ERRORS 💀

lio_listio() may fail for these reasons:

• EAGAIN — out of resources. 😵
• EAGAIN — the number of I/O operations specified by n would blow past the limit AIO_MAX. (yes it's listed twice, both are real, don't @ me)
• EINTR — mode was LIO_WAIT and a signal got caught before all the I/O operations completed; see signal(7). And the drama? This may even be one of the signals used for asynchronous I/O completion notification. 😭
• EINVAL — mode is invalid, or n exceeds the limit AIO_LISTIO_MAX. 🚫
• EIO — one or more of the operations specified by aiocb_list failed. The application can check the status of each operation using aio_return(3). 📋

⚠️ Important caveat time: if lio_listio() fails with the error EAGAIN, EINTR, or EIO, then some of the operations in aiocb_list may have been initiated. If lio_listio() fails for any other reason, then none of the I/O operations has been initiated. So like, know which one you're in. 👀

---

⭐ ATTRIBUTES ⭐

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

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

(That's your vibe check passed: it's thread-safe, slay. 👑)

---

🌈 STANDARDS 🌈

POSIX.1-2008. periodt.

---

🦋 HISTORY 🦋

• glibc 2.1.
• POSIX.1-2001.

we stan a legacy icon. 💜

---

💅 NOTES 💅

• It is a good idea to zero out the control blocks before use. do it. please. 🙏
• The control blocks must not be changed while the I/O operations are in progress. hands off, bestie. ✋
• The buffer areas being read into or written from must not be accessed during the operations, or undefined results may occur. Do not touch. Do not look at it. Do not think about it. 💀
• The memory areas involved must remain valid. keep them alive, keep them valid. 🌸
• Simultaneous I/O operations specifying the same aiocb structure produce undefined results. Just don't. 🙈

---

🎀 SEE ALSO 🎀

• aio_cancel(3)
• aio_error(3)
• aio_fsync(3)
• aio_return(3)
• aio_suspend(3)
• aio_write(3)
• aio(7)

---

and that's the whole page, babe 💖 this came from Linux man-pages 6.20, dated 2026-02-08, and it's the lio_listio(3) manual — go forth and queue your I/O, you've got this. 🫶✨