io_queue_init(3)

💖 io_queue_init(3) 💖

okay bestie, welcome to the Linux AIO corner of the manual — yes it's a section 3 page, yes it's iconic, let's get into it 🦋

✨ NAME ✨

io_queue_init — spins up your asynchronous io state machine, no cap 🎀

✨ SYNOPSIS ✨

#include <errno.h>

#include <libaio.h>

int io_queue_init(int maxevents, io_context_t *ctx);

✨ DESCRIPTION ✨

so io_queue_init() tries to create an aio context — like, a whole setup that can receive at least maxevents events. that's the vibe 💅

now listen, ctx has to point to an aio context that already exists, and it must be initialized to 0 before you call this. do not skip that part, i'm literally begging 🙈

if everything goes right, *cxtp gets filled in with the resulting handle. slay ✨

✨ RETURN VALUES ✨

on success, io_queue_init() returns 0. queen behavior 👑

otherwise it returns -error, where error is one of the Exxx values listed down in the ERRORS section. so like, negative number, look it up, that's the assignment 📚

✨ ERRORS ✨

• EFAULT — the iocbs referenced data that lives outside the program's accessible address space. nope, not allowed, that's not your house 🚫
• EINVAL — either maxevents is <= 0, or ctx is an invalid memory location. zero events? negative events? a fake address? bestie no 😭
• ENOSYS — not implemented. it's giving "we didn't build that" 💀
• EAGAIN — maxevents is greater than max_aio_reqs, where max_aio_reqs is a tunable value. you asked for too much, tune it down 🌸

✨ SEE ALSO ✨

io(3), io_cancel(3), io_fsync(3), io_getevents(3), io_prep_fsync(3), io_prep_pread(3), io_prep_pwrite(3), io_queue_release(3), io_queue_run(3), io_queue_wait(3), io_set_callback(3), io_submit(3), errno(3).

go read those too, i know you will, you're so good at this 🫶

mwah 💋 this one's from the Linux AIO crew, dated 2019-07-23 — yeah she's a classic, and she's still serving. periodt. 💜