io_uring_prep_read(3)

💖 io_uring_prep_read — the liburing manual, but make it cute 💖

okay bestie, welcome to io_uring_prep_read(3) from the liburing manual ✨ this is the one that sets you up to read stuff asynchronously, and she is lowkey iconic. let's get into it 🫶

✨ NAME ✨

io_uring_prep_read — prepare an I/O read request 🎀

🌸 SYNOPSIS 🌸

#include <liburing.h>

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

look at her. five little arguments. so demure, so mindful 💅

🦋 DESCRIPTION 🦋

So io_uring_prep_read(3) prepares an IO read request. It takes the submission queue entry sqe and sets it all up to use the file descriptor fd to start reading nbytes into the buffer buf at the specified offset. Slay. That's the whole vibe. ✨

Now here's the part where you have to actually pay attention, bestie, because there's lore:

On files that support seeking, if the offset is set to -1, the read operation commences at the file offset, and the file offset is incremented by the number of bytes read. See read(2) for more details 👑

🚨 okay 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, babe. it's giving safer. 💀

And on files that are not capable of seeking, the offset must be 0 or -1. No other options. That's the rule. Periodt. 🎀

After the read has been prepared, it can be submitted with one of the submit functions. that's the part where she actually goes and does the thing 💫

🌈 RETURN VALUE 🌈

None. literally nothing. she's a void function. she sets up the sqe and dips. no cap. 🙈

💜 ERRORS 💜

okay so here's the tea 🍓 — the CQE res field will contain the result of the operation. See the related man page for details on possible values.

✨ important distinction, bestie: 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, -EAGAIN shows up as -11 style negativity. iconic behavior honestly 💅

👑 SEE ALSO 👑

• io_uring_get_sqe(3)
• io_uring_prep_readv(3)
• io_uring_prep_readv2(3)
• io_uring_submit(3)

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

liburing-2.1 🌸 November 15, 2021 — mwah, that's the version and the date, love u, bye bestie, go read some bytes 💖✨🎀