io_uring_prep_fsync(3)

💾 io_uring_prep_fsync — bestie, it's time to flush

okay so welcome to io_uring_prep_fsync(3), a lil liburing helper whose whole job is prepare an fsync request. yes, the manual page is literally called that. it's part of the liburing manual, and it lives in section 3, and it is genuinely so good at what it does. sit down, grab a strawberry 🍓, let's go.

✨ SYNOPSIS ✨

#include <liburing.h>

void io_uring_prep_fsync(struct io_uring_sqe *sqe,
                         int fd,
                         unsigned flags);

that's it. three args. no drama. 💅

🌸 DESCRIPTION 🌸

so the way that io_uring_prep_fsync(3) works is: it prepares an fsync request. that's the whole vibe. it takes your submission queue entry sqe and sets it up to use the file descriptor fd, which is the thing that's gonna get synced, and then it sprinkles on the modifier behavior you asked for via the flags argument. ✨

here's the tea though — this helper can act two different ways:

• by default, it behaves like an fsync(2) operation. classic. iconic. 👑
• if IORING_FSYNC_DATASYNC is set in the flags argument, then it behaves like fdatasync(2) instead. boom, different flavor.

and if you don't specify a range? no worries, the fd will be synced from 0 all the way to end-of-file. full sweep. no crumbs left. 🧹

now — you can specify a range to sync if that's what you want, and this part is important so don't scroll past it:

• if the off field of the SQE is set to non-zero, that indicates the offset to start syncing at 📍
• if len is set in the SQE, that indicates the size in bytes to sync from the offset 📏

⚠️ but listen — those fields are not accepted by this helper. it will not take them from you. you have to set them manually in the SQE after calling this prep helper. like, set it up first, then reach in and fix the fields yourself. iykyk. 🙈

💖 RETURN VALUE 💖

None. literally nothing. it returns void, it says nothing, it gives nothing back. it's not about the return, bestie, it's about the prep. 😌

😭 ERRORS 😭

okay so where do errors even go if the function returns nothing? great question, obsessed that you asked. 💜

the CQE res field will contain the result of the operation. if you want details on the possible values, go read the related man page — that's where that info lives.

and here's the big one, the one that trips people up, so pay attention:

• where synchronous system calls will return -1 on failure and set errno to the actual error value…
• io_uring never uses errno. never. not once. not ever.
• instead, it returns the negated errno directly in the CQE res field. 🔥

so like, no errno checking over here. the error is right there in res, negated. that's the whole system. periodt. 💅

🦋 SEE ALSO 🦋

• io_uring_get_sqe(3)
• io_uring_submit(3)
• fsync(2)
• fdatasync(2)

go read those too, they're all part of the same little friend group. 🫶

and that's the page!! this whole thing is from liburing-2.2, dated March 12, 2022, and honestly it ate. 💖✨ sync responsibly, bestie. 🎀🌈