aio_suspend(3)

💤 aio_suspend(3) — wait for asynchronous I/O operation or timeout

okay bestie, this one lives in the Library Functions Manual (section 3), so you know it's a library call 💅

---

📚 LIBRARY

Real-time library — link it with librt, so -lrt on your compile line 🎀

---

✨ SYNOPSIS

#include <aio.h>

int aio_suspend(int n;
                const struct aiocb *const aiocb_list[n], int n,
                const struct timespec *restrict timeout);

(yes the synopsis is built different, we don't question it, we just vibe 😭)

---

🌸 DESCRIPTION

so aio_suspend() basically puts your calling thread in timeout mode 🛌 — it suspends the calling thread until one of these things happens:

• one or more of the async I/O requests in the list aiocb_list has completed ✅
• a signal gets delivered 📬
• timeout is not NULL and the time interval you specified has officially passed ⏰ (want the deets on the timespec struct? go see nanosleep(2))

The n argument tells you how many items are chillin' in aiocb_list. Every single item in that list pointed to by aiocb_list has to be either NULL (in which case it's just ignored, lowkey irrelevant, we move on 🙈) or a pointer to a control block where I/O was started using aio_read(3), aio_write(3), or lio_listio(3). Want the whole aiocb structure explained? That's aio(7), babes.

If CLOCK_MONOTONIC is supported, that's the clock used to measure the timeout interval — peep clock_gettime(2) for that.

---

🫶 RETURN VALUE

• if the function comes back because one of the I/O requests in aiocb_list finished? you get 0 — slay ✨
• otherwise you get -1, and errno is set to tell you what went wrong 💀

---

😭 ERRORS

• EAGAIN — the call hit the timeout before any of the indicated operations had completed. it literally just ran out of time bestie ⏳
• EINTR — the call got ended by a signal (possibly the completion signal of one of the operations you were waiting on, which is so ironic ngl); see signal(7)
• ENOSYS — aio_suspend() is not implemented. it's giving "we don't do that here" 🙈

---

💅 ATTRIBUTES

for what all these terms even mean, check attributes(7).

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

---

👑 STANDARDS

POSIX.1-2008.

---

🦋 HISTORY

glibc 2.1. Also POSIX.1-2001.

And a lil note: POSIX doesn't specify the parameters to be restrict — that part is specific to glibc, so don't go thinking every lib does it 💖

---

🍓 NOTES

• wanna poll? you absolutely can — just pass a non-NULL timeout that specifies a zero time interval 🔁
• if one or more of the async I/O ops in aiocb_list has already completed by the time you call aio_suspend(), the call returns immediately. no waiting, no drama, instant 📸
• to figure out which I/O operations actually completed after a successful return from aio_suspend(), use aio_error(3) to scan through the list of aiocb structures pointed to by aiocb_list 🔍

---

💀 BUGS

The glibc implementation of aio_suspend() is not async-signal-safe, which is in violation of the requirements of POSIX.1. so yeah. that's a thing. be careful out there 🚩

---

🌈 SEE ALSO

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

---

mwah, that's the whole page 💜 this lil masterpiece came from Linux man-pages 6.20, dated 2026-02-08 — and with that, aio_suspend(3) is a wrap, periodt ✨🎀🫶