aio_write(3)

✨ aio_write(3) — the "write but make it async" icon ✨

okay bestie, so this is a page from the Library Functions Manual and it's about aio_write(3) — literally the async glow-up of write(2). iykyk. let's get into it 💅

🌸 LIBRARY 🌸

Real-time library — link it with -lrt if you want in on this. 🫶

🦋 SYNOPSIS 🦋

#include <aio.h>

int aio_write(struct aiocb *aiocbp);

💖 DESCRIPTION 💖

so what aio_write() does is it queues up the I/O request described by the buffer that aiocbp points to. it's fr fr the asynchronous analog of write(2) — same energy, just not blocking your whole vibe while it happens.

the args of a write(2) call like

write(fd, buf, count)

line up (in order 🎯) with the fields aio_fildes, aio_buf, and aio_nbytes of the struct that aiocbp points at. (if you're like "bestie what even is the aiocb structure", go read aio(7), it's got the whole rundown.)

---

okay now here's where the positioning tea gets spilled ☕ :

• if O_APPEND is not set, the data gets written starting at the absolute position aiocbp->aio_offset — and it does NOT care about the file offset, periodt.
• if O_APPEND is set, the data goes to the end of the file, in the same order as the aio_write() calls were made. 🎀

and after the call? the value of the file offset is unspecified. don't ask, it's giving mysterious. 💀

---

"The asynchronous" means this call returns as soon as the request has been enqueued — the write may or may not have actually completed by the time it comes back to you. shocking, i know. 😭

to check if it's done, you test it with aio_error(3). to get the return status of a completed I/O operation, use aio_return(3). and if you want the I/O completion to ping you, set aiocbp->aio_sigevent appropriately — the details live in sigevent(3type). 🔔

If _POSIX_PRIORITIZED_IO is defined, and the file supports it, then the async operation gets submitted at a priority equal to that of the calling process minus aiocbp->aio_reqprio. math girlies rise 🧚

lowkey important: the field aiocbp->aio_lio_opcode is ignored. she said "not today." 🙈

and no data is written to a regular file beyond its maximum offset. that's a hard boundary, bestie. 👑

💜 RETURN VALUE 💜

• on success → 0 is returned. slay. ✨
• on error → the request is not enqueued, -1 is returned, and errno gets set to tell you what went wrong.
• if an error only shows up later, it gets reported via aio_return(3) (returns status -1) and aio_error(3) (error status — whatever you would have gotten in errno, like EBADF). so the drama comes in two acts, okay? 😭

🎀 ERRORS 🎀

• EAGAIN — out of resources. the vibes are depleted. 💀
• EBADF — aio_fildes is not a valid file descriptor open for writing. she's not even allowed in here. 🚫
• EFBIG — the file is a regular file, we want to write at least one byte, but the starting position is at or beyond the maximum offset for this file. too far, babes. 📏
• EINVAL — one or more of aio_offset, aio_reqprio, aio_nbytes are invalid. nope nope nope. 🙅
• ENOSYS — aio_write() is not implemented. bestie... this function doesn't exist here. 😭

🌈 ATTRIBUTES 🌈

for the whole explanation of these terms, hit up attributes(7). here's the stat block, just not in table form because we're cute like that ✨:

• aio_write() — Thread safety: MT-Safe

so yeah, threads can share it. icon behavior. 👑

⭐ STANDARDS ⭐

POSIX.1-2008. official, certified, iconic.

🦋 HISTORY 🦋

• glibc 2.1
• POSIX.1-2001

she's been around. a true veteran. 🤍

💅 NOTES 💅

okay listen up, these are the rules of the house:

• it is a good idea to zero out the control block before use. do it. bestie please.
• the control block must not be changed while the write operation is in progress. hands off. 🙅
• the buffer area being written out must not be accessed during the operation, or undefined results may occur. and we do NOT do undefined results in this household. 💀
• the memory areas involved must remain valid.
• simultaneous I/O operations specifying the same aiocb structure produce undefined results. sharing is not always caring, bestie. 😭

🔥 SEE ALSO 🔥

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

---

okay that's the whole page, bestie!! 🫶 this was Linux man-pages 6.20, dated 2026-02-08, and the page you just read is aio_write(3). go queue some async writes and absolutely eat. mwah 💖✨🎀🦋🌸