io_fsync(3)

✨ io_fsync — bestie, let's get your file's whole in-core state synced up with the disk 💾✨

okay so this one is from Linux AIO, the io_fsync(3) page, and it's genuinely so useful once it clicks. buckle up 🎀

🌸 NAME 🌸

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

🦋 SYNOPSIS 🦋

#include <errno.h>

#include <libaio.h>

int io_fsync(io_context_t ctx, struct iocb *iocb, io_callback_t cb, int fd);

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

typedef void (*io_callback_t)(io_context_t ctx, struct iocb *iocb, long res, long res2);

like, look at that struct. it's giving ✨data✨. anyway.

💅 DESCRIPTION 💅

so when you're doing asynchronous operations, sometimes you literally just need to get into a consistent state. and for AIO that means: you wanna know whether a certain request — or a whole group of requests — actually got processed. sure, you could just sit there waiting for the notification the system sends after the operation terminated, but bestie… that sometimes means wasting resources (mainly computation time 😭). not the vibe.

so here's the tea: calling this function forces all I/O operations queued at the time of the function call operating on the file descriptor iocb->io_fildes into the synchronized I/O completion state. periodt.

the io_fsync() function returns immediately, but the notification through the method described in io_callback will happen only after all requests for this file descriptor have terminated and the file is synchronized. 👑

and this part matters: requests for this very same file descriptor that are queued after the synchronization request are not affected. so don't come for them, they're innocent 🙈

⭐ RETURN VALUES ⭐

Returns 0, otherwise returns errno.

💀 ERRORS 💀

• EFAULT — iocbs referenced data outside of the program's accessible address space. (rude of it, honestly)
• EINVAL — ctx refers to an uninitialized aio context, the iocb pointed to by iocbs contains an improperly initialized iocb,
• EBADF — The iocb contains a file descriptor that does not exist.
• EINVAL — The file specified in the iocb does not support the given io operation.

yes bestie, EINVAL shows up twice up there, and I'm not about to gaslight you into thinking it doesn't. it's two different situations, both iconic, both annoying 💅

🫶 SEE ALSO 🫶

io(3), io_cancel(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).

and that's the whole page, bestie 🎀 this one's from Linux, dated 2019-07-23 — go sync something responsibly, mwah 💖✨🌸🦋