io_prep_fsync(3)

💾 io_prep_fsync — Linux AIO, bestie edition ✨

okay so this is a page from the Linux AIO manual, section 3 (that's the library-functions girlies 💅), and we're about to make your file's whole in-core state line up with what's on disk. no cap.

🌸 NAME 🌸

io_prep_fsync — Synchronize a file's complete in-core state with that on disk 🫶

literally what it says. your RAM copy and your disk copy are gonna be the same, fr fr.

✨ SYNOPSIS ✨

#include <errno.h>

#include <libaio.h>

static inline void io_prep_fsync(struct iocb *iocb, int fd);

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

yes bestie, two includes. errno.h AND libaio.h. both. we don't make the rules 💀

🦋 DESCRIPTION 🦋

so this is an inline convenience function — a little helper — for setting up an iocb for an FSYNC request. think of it as the pre-game. the actual performance happens later.

it sets up the file where

iocb->aio_fildes = fd

is the descriptor, with the command

iocb->aio_lio_opcode = IO_CMD_FSYNC

now the real tea ☕ — the io_prep_fsync() function shall set up an IO_CMD_FSYNC operation to asynchronously force all I/O operations associated with the file indicated by the file descriptor aio_fildes member of the iocb structure referenced by the iocb argument and queued at the time of the call to io_submit() to the synchronized I/O completion state. whew, that was a mouthful, but it ate. 🔥

and the function call shall return when the synchronization request has been initiated or queued to the file or device — even when the data cannot be synchronized immediately. so like, it's out there, it's on its way, don't stress.

all currently queued I/O operations shall be completed as if by a call to fsync(2); that is, as defined for synchronized I/O file integrity completion. periodt. 💅

😭 okay important one: if the operation queued by io_prep_fsync() fails, then, as for fsync(2), outstanding I/O operations are not guaranteed to have been completed. not me being the bearer of bad news but you needed to know.

if io_prep_fsync() succeeds, then it is only the I/O that was queued at the time of the call to io_submit(3) that is guaranteed to be forced to the relevant completion state. the completion of subsequent I/O on the file descriptor is not guaranteed to be completed in a synchronized fashion. so like… the guarantee has a cutoff date, and that date is "when you called io_submit(3)". iykyk. 🎀

this function returns immediately. to actually schedule the operation, you have to call io_submit(3). it's giving "I set it up, you send it", honestly iconic teamwork.

💀 and listen: simultaneous asynchronous operations using the same iocb produce undefined results. don't do it. sharing one iocb across overlapping ops is not the vibe. main character energy only for one operation at a time on that struct, okay?

🌈 RETURN VALUES 🌈

None. nothing. void. she gives nothing and takes nothing. 🙈

💜 ERRORS 💜

None. no errors reported here. clean, pristine, unbothered. ✨

🎀 SEE ALSO 🎀

• io(3)
• io_cancel(3)
• io_fsync(3)
• io_getevents(3)
• io_prep_pread(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 read them all, they're all slaying in their own way. 🫶

okay that's the page bestie!! this one's from Linux, dated 2019-07-23, and it's page io_prep_fsync(3) of the Linux AIO manual — mwah, go sync something. 💖🦋🌸