io_uring_prep_read_multishot(3)

💅 io_uring_prep_read_multishot — NAME 🦋

okay so bestie, meet io_uring_prep_read_multishot, a lil helper from the liburing manual and her whole job is preparing an I/O read multishot request. that's the name, that's the vibe, periodt ✨

📖 SYNOPSIS 🌸

#include <liburing.h>

void io_uring_prep_read_multishot(struct io_uring_sqe *sqe,
                                  int fd,
                                  unsigned nbytes,
                                  __u64 offset,
                                  int buf_group);

✨ DESCRIPTION ✨

so the io_uring_prep_read_multishot(3) helper does the prep work for an IO read multishot request. she sets up that submission queue entry sqe so it uses the file descriptor fd to start reading into a buffer — and that buffer comes from the provided buffer group with ID buf_group, at the offset you specify. slay 💖

nbytes must be set to zero, because the size that actually gets read is given by the size of the buffers in the indicated buffer group IO. not negotiable, she said what she said 💅

on files that are not capable of seeking, the offset must be 0 or -1. no cap.

if nbytes exceeds the size of the buffers in the specified buffer group, or if nbytes is 0, then the size of the buffer in that group will be used for the transfer. so like, either way, the group is the main character 👑

a multishot read request will repeatedly trigger a completion event whenever data is available to read from the file. and because of that, this type of request can only be used with a file type that is pollable. examples of that include pipes, tun devices, etc. if you use it with a regular file, or a wrong file type in general, the request will fail with -EBADFD in the CQE res field. 💀 not the flex you want, fr fr.

since multishot requests repeatedly trigger completion events as data arrives, it must be used with provided buffers. with provided buffers, the application provides buffers to io_uring upfront, and then the kernel picks a buffer from the specified group in buf_group when the request is ready to transfer data. teamwork, honestly 🫶

a multishot request will persist as long as no errors are encountered doing handling of the request. for each CQE posted on behalf of this request, the CQE flags will have IORING_CQE_F_MORE set if the application should expect more completions from this request. if this flag isn't set, then that signifies termination of the multishot read request. so like, no IORING_CQE_F_MORE = she's done, she's clocked out 🎀

after the read has been prepared it can be submitted with one of the submit functions.

available since 6.7. yes she's new-ish, she's fresh, she's iconic 🌈

🫧 RETURN VALUE 🫧

None. literally nothing. that's the whole section bestie 😭

🚨 ERRORS 🚨

the CQE res field will contain the result of the operation. see the related man page for details on possible values. note that 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. different system, different rules, iykyk ✨

👀 SEE ALSO 👀

• io_uring_get_sqe(3)
• io_uring_prep_read(3)
• io_uring_buf_ring_init(3)
• io_uring_buf_ring_add(3)
• io_uring_submit(3)

okay that's the whole page!! this one's from liburing-2.5, dated September 12, 2024 — mwah, go read your buffers, ily, bye 🧚💜