io_prep_pread(3)

💖 io_prep_pread(3) — the Linux AIO girlies' guide 💖

okay so bestie, we're in the Linux AIO section of the manual, and today's main character is io_prep_pread. she's a lil inline function, she's chill, she's literally just here to set things up. let's get into it 🦋

✨ NAME ✨

io_prep_pread — Set up asynchronous read

like, that's her whole job. setting up the async read. no cap. 💅

🌸 SYNOPSIS 🌸

#include <errno.h>

#include <libaio.h>

inline void io_prep_pread(struct iocb *iocb, int fd, void *buf, size_t count, long long offset);

struct iocb {
     void      *data;
     unsigned  key;
     short          aio_lio_opcode;
     short          aio_reqprio;
     int       aio_fildes;
};

okay so first things first: you gotta pull in <errno.h> and <libaio.h>, bestie. then there's the function signature — inline void io_prep_pread(...) — and yeah she's inline, she's void, she's not returning anything to you, she's just doing the prep work behind the scenes. and then the struct iocb is right there so you can see what you're actually filling in. iconic. 👑

🎀 DESCRIPTION 🎀

io_prep_pread() is an inline convenience function designed to facilitate the initialization of the iocb for an asynchronous read operation.

so basically, she's your little prep-bestie. before you can yeet an async read into the void, you need an iocb (that's the "io control block", the lil form you fill out) and she fills it out for you so you don't have to do it by hand. the way that she just handles it for you?? obsessed. 😭

here's the actual tea though, fr fr:

• The first iocb->u.c.nbytes = count bytes of the file for which iocb->aio_fildes = fd is a descriptor are written to the buffer starting at iocb->u.c.buf = buf.
• Reading starts at the absolute position ioc->u.c.offset = offset in the file.

so like, count bytes, from the file that fd points at, landing in buf, starting from absolute position offset. that's the whole vibe check right there. ✨

lowkey important: this function returns immediately. she does NOT do the read. she just gets everything ready. to actually schedule the operation you must call io_submit(3). no io_submit, no read. periodt. 💅

🚨 warning bestie, real talk 🚨 Simultaneous asynchronous operations using the same iocb produce undefined results. so like, don't be out here sharing one iocb between multiple in-flight operations, that's giving chaos and not the cute kind. one iocb, one operation, iykyk. 💀

🌈 RETURN VALUES 🌈

None.

(yeah. she returns nothing. she's a void queen. she gave you setup and that's it. 💜)

🧚 ERRORS 🧚

None.

🫶 SEE ALSO 🫶

• io(3)
• io_cancel(3)
• io_fsync(3)
• io_getevents(3)
• io_prep_fsync(3)
• io_prep_pwrite(3)
• io_queue_init(3)
• io_queue_release(3)
• io_queue_run(3)
• io_queue_wait(3)
• io_set_callback(3)
• io_submit(3)
• errno(3)

the whole friend group honestly, go say hi to all of them 💖

okay that's the whole page!! this one's from Linux, dated 2019-07-23, and yeah that's genuinely it — short page, big energy. go prep those iocbs and slay, bestie 🌸✨🎀