io_uring_prep_writev(3)

✨ io_uring_prep_writev(3) ✨

okay bestie, welcome to the liburing Manual 💖 you're literally about to learn how to prep a vectored write request and honestly? iconic of you.

---

🌸 NAME 🌸

io_uring_prep_writev — prep a vector I/O write request, no cap 🦋

---

💅 SYNOPSIS 💅

#include <sys/uio.h>
#include <liburing.h>

void io_uring_prep_writev(struct io_uring_sqe *sqe,
                          int fd,
                          const struct iovec *iovecs,
                          unsigned nr_vecs,
                          __u64 offset);

look at her. she's giving five arguments of pure power ✨

---

🎀 DESCRIPTION 🎀

so the way that io_uring_prep_writev(3) works is it preps a vectored IO write request. you hand it a submission queue entry sqe, and it sets that bad boy up to use the file descriptor fd to start writing nr_vecs from the iovecs array, all at the specified offset. periodt 💅

now on files that support seeking — listen up, this part matters — if the offset is set to -1, the write operation commences at the file offset, and then the file offset gets incremented by however many bytes were written. if you want the full lore, go read write(2). 🫶

⚠️ but fr fr: for an async API, reading and updating the current file offset may result in unpredictable behavior, unless access to the file is serialized. it is not encouraged to use this feature if it's possible to provide the desired IO offset from the application or library. like, just pass the offset, bestie, it's right there 😭

on files that are not capable of seeking, the offset must be 0 or -1. no in-between. that's the rule. 👑

and once the write has been prepared, you can submit it with one of the submit functions. go off ✨

---

🌈 RETURN VALUE 🌈

None

literally nothing. 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 the deets 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, if you were waiting for errno to tell you what happened... she's not coming. check res. 💅

---

🦋 NOTES 🦋

okay so unless an application explicitly needs to pass in more than one iovec, it is more efficient to use io_uring_prep_write(3) rather than this function, because no state has to be maintained for a non-vectored IO request. lowkey just saying. save yourself the work 🍓

and as with any request that passes in data in a struct, that data must remain valid until the request has been successfully submitted. it need not remain valid until completion. once a request has been submitted, the in-kernel state is stable. 💖

⚠️ very early kernels (5.4 and earlier) required state to be stable until the completion occurred. so if you're on ancient kernel energy, bestie, be careful 😭

applications can test for this behavior by inspecting the IORING_FEAT_SUBMIT_STABLE flag passed back from io_uring_queue_init_params(3). iykyk 👑

---

💜 SEE ALSO 💜

• io_uring_get_sqe(3)
• io_uring_prep_write(3)
• io_uring_prep_writev2(3)
• io_uring_submit(3)

---

and that's the whole page, bestie 🎀 this one's from liburing-2.1, dated November 15, 2021. go prep those writes and slay 💅✨🦋