LIO_LISTIO(2)

💖 LIO_LISTIO(2) 💖

okay bestie, welcome to lio_listio(2) — it's a system call, it lives in the System Calls Manual, and it is literally the group-chat of I/O: you hand it a whole list of requests and it sends them all at once. no cap. 🫶

---

✨ NAME ✨

lio_listio — list directed I/O (REALTIME)

🎀 LIBRARY 🎀

Standard C Library (libc, -lc)

🌸 SYNOPSIS 🌸

#include <aio.h>

int
lio_listio(int mode, struct aiocb * const list[], int nent,
    struct sigevent *sig);

🦋 DESCRIPTION 🦋

So the way that lio_listio() works is it kicks off a whole list of I/O requests in one single function call. iconic behavior honestly. the list argument is an array of pointers to aiocb structures, and each one describes one operation you want done — and there are nent elements in that array. elements that are NULL? ignored, they're not even invited to the party. 💅

The aio_lio_opcode field of each aiocb is what tells you which operation is happening. the supported ops are:

• LIO_READ — read data as if by a call to aio_read(2). 🍓
• LIO_NOP — no operation. (the "seen at 3am, no reply" of opcodes.)
• LIO_WRITE — write data as if by a call to aio_write(2). ✨

Now, the mode argument changes the whole vibe:

• if mode is LIO_WAIT, lio_listio() does not return until every single requested operation is done. it's giving "I'll wait, but not happily."
• if mode is LIO_NOWAIT, then sig can be used to ask for asynchronous notification once all the operations have completed. and if sig is NULL, no notification gets sent at all. ghosted, basically. 💀

🌈 for SIGEV_KEVENT notifications 🌈

the posted kevent is gonna contain:

• ident — list
• filter — EVFILT_LIO
• udata — the value stored in sig->sigev_value

🌟 for SIGEV_SIGNO and SIGEV_THREAD_ID notifications 🌟

the info for the queued signal is gonna include SI_ASYNCIO in the si_code field, plus the value stored in sig->sigev_value sitting in the si_value field. periodt.

💜 for SIGEV_THREAD notifications 💜

the value stored in sig->sigev_value gets passed to the sig->sigev_notify_function, exactly as described in sigevent(3).

🚨 okay this part matters: the order in which the requests are carried out is not specified. in particular, there is no guarantee that they'll be executed in the order 0, 1, ..., nent-1. so don't you dare assume they run in order, bestie, that's not the vibe at all.

🔥 RETURN VALUES 🔥

• if mode is LIO_WAIT, lio_listio() returns 0 if the operations completed successfully — otherwise -1.
• if mode is LIO_NOWAIT, lio_listio() returns 0 if the operations were successfully queued — otherwise -1.

💅 ERRORS 💅

lio_listio() will fail if:

• [EAGAIN] — there are not enough resources to enqueue the requests. 😭
• [EAGAIN] — the request would cause the system-wide limit {AIO_MAX} to be exceeded.
• [EINVAL] — the mode argument is neither LIO_WAIT nor LIO_NOWAIT, or nent is greater than {AIO_LISTIO_MAX}.
• [EINVAL] — the asynchronous notification method in sig->sigev_notify is invalid or not supported.
• [EINTR] — a signal interrupted the system call before it could be completed. rude.
• [EIO] — one or more requests failed.

And on top of all that, lio_listio() may fail for any of the reasons listed for aio_read(2) and aio_write(2). so check those pages too, bestie, iykyk.

⚠️ big one: if lio_listio() succeeds, or fails with an error code of EAGAIN, EINTR, or EIO, some of the requests may have already been initiated. so the caller should check the error status of each aiocb structure individually by calling aio_error(2). don't skip this, fr fr. 🙈

👑 SEE ALSO 👑

aio_error(2), aio_read(2), aio_write(2), read(2), write(2), sigevent(3), siginfo(3), aio(4)

⭐ STANDARDS ⭐

The lio_listio() function is expected to conform to IEEE Std 1003.1-2001 (“POSIX.1”). slay.

🧚 HISTORY 🧚

The lio_listio() system call first appeared in FreeBSD 3.0. a true elder icon. 💖

---

and that's the whole page, bestie!! this one's from Debian, dated Dec 7, 2019, and it's the LIO_LISTIO(2) page — go forth and queue your I/O lists responsibly. mwah. 💅✨🎀