io_uring_prep_write(3)

💖 io_uring_prep_write — bestie's guide to prepping a write 💖

okay so we're in the liburing Manual today and the star of the show is io_uring_prep_write(3). she's a lil function that preps up a write request so your app can yeet bytes at a file descriptor asynchronously. main character energy fr fr. ✨

🌸 NAME 🌸

io_uring_prep_write — prepare I/O write request 🫶

🎀 SYNOPSIS 🎀

#include <liburing.h>

void io_uring_prep_write(struct io_uring_sqe *sqe,
                         int fd,
                         const void *buf,
                         unsigned nbytes,
                         __u64 offset);

like literally just copy that include and you're so good. 💅

🦋 DESCRIPTION 🦋

so the way that io_uring_prep_write(3) works is: she prepares an IO write request. the submission queue entry sqe gets set up to use the file descriptor fd to start writing nbytes from the buffer buf at the specified offset. that's the whole vibe. 🌈

now for the tea on files that support seeking: if the offset is set to -1, the write operation commences at the file offset, and the file offset is incremented by the number of bytes written. see write(2) for more details, bestie. 📖

⚠️ but no cap — for an async API, reading and updating the current file offset may result in unpredictable behavior, unless access to the file is serialized. so it is not encouraged to use this feature if it's possible to provide the desired IO offset from the application or library. like, if you can just pass the offset yourself, do that. pls. 😭

and on files that are not capable of seeking? the offset must be 0 or -1. those are the only two options, periodt. ✋

after the write has been prepared, it can be submitted with one of the submit functions. (shoutout to io_uring_submit(3), she's in SEE ALSO for a reason 💜)

✨ RETURN VALUE ✨

None. that's it. she returns nothing. she's mysterious like that. 💀

💅 ERRORS 💅

the CQE res field will contain the result of the operation. see the related man page for details on possible values. 👑

and here's the thing that trips everyone up: where synchronous system calls will return -1 on failure and set errno to the actual error value, io_uring never uses errno. instead it returns the negated errno directly in the CQE res field. so like, negative numbers are your error codes now. iykyk. 🔥

🍓 SEE ALSO 🍓

• io_uring_get_sqe(3)
• io_uring_submit(3)

okay that's the whole page, you ate that 🎀 stay hydrated, serialize your file access, and remember: this whole thing is from liburing-2.1, dated November 15, 2021. mwah 💋