io_uring_prep_recvmsg(3)

💖 io_uring_prep_recvmsg — ok bestie, let's receive some messages 💖

So this is io_uring_prep_recvmsg(3), and it lives in the liburing Manual (yes, that liburing, the cool one) ✨

---

🎀 NAME 🎀

io_uring_prep_recvmsg — get a recvmsg request all prepped and ready, no cap 💅

---

🌸 SYNOPSIS 🌸

#include <sys/types.h>
#include <sys/socket.h>
#include <liburing.h>

void io_uring_prep_recvmsg(struct io_uring_sqe *sqe,
                           int fd,
                           struct msghdr *msg,
                           unsigned flags);

void io_uring_prep_recvmsg_multishot(struct io_uring_sqe *sqe,
                                     int fd,
                                     struct msghdr *msg,
                                     unsigned flags);

Like… two whole functions. Iconic behaviour honestly 🫶

---

✨ DESCRIPTION ✨

So the way this works: io_uring_prep_recvmsg(3) prepares a recvmsg request. The submission queue entry sqe gets set up to use the file descriptor fd, and it starts receiving the data that msg points at, using the flags defined by recvmsg(2) that you pass in the flags argument. Periodt. 🌈

This function preps an async recvmsg(2) request, so if you wanna know what the heck the arguments actually mean, go read that man page, bestie. It's all there. 😌

🦋 the multishot version 🦋

The multishot version is giving main character energy: you issue a single receive request, and it just keeps posting a CQE whenever data shows up. Repeatedly. Obsessed. 💖

But it has ✌️ requirements, and you can't skip them:

• It needs the IOSQE_BUFFER_SELECT flag to be set.
• It needs MSG_WAITALL to not be set.

Because of that, every single CQE will pull a buffer out of a provided buffer pool for receiving. So the app should check the flags on each CQE, regardless of what its result was — like, don't skip the vibe check, fr fr 🙈

If a posted CQE does not have the IORING_CQE_F_MORE flag set, then the multishot receive is done, and you have to issue a new request if you still wanna receive data from that socket. No more free CQEs, babe 😭

🌟 the plot twist: io_uring_recvmsg_out 🌟

Unlike plain recvmsg(2), multishot recvmsg will prepend a struct io_uring_recvmsg_out, which describes the layout of the rest of the buffer, in combination with the initial struct msghdr you submitted with the request. Head to io_uring_recvmsg_out(3) for the deets on how to actually access the data. iykyk 👑

Multishot variants are available since kernel 6.0. ⭐

💅 the internal modifier flags 💅

After you call this function, additional io_uring internal modifier flags may be set in the SQE ioprio field. The supported ones are:

• IORING_RECVSEND_POLL_FIRST — If set, io_uring will assume the socket is currently empty, and that attempting to receive data will be unsuccessful. In that case, io_uring will arm internal poll and trigger a receive of the data when the socket actually has data to be read. The initial receive attempt can be wasteful when you expect the socket to be empty, so setting this flag bypasses that initial receive attempt and goes straight to arming poll. If poll does indicate data is ready to be received, the operation will proceed. 🍓

It can be used with the CQE IORING_CQE_F_SOCK_NONEMPTY flag, which io_uring will set on CQEs after a recv(2) or recvmsg(2) operation. If that's set, the socket still had data to be read after the operation completed. Both these flags are available since 5.19. 🧚

---

🔥 RETURN VALUE 🔥

None. That's it. Nothing. Zero. Nada. It's a prep helper, she doesn't return anything, she just sets things up 💀

---

😭 ERRORS 😭

The CQE res field will contain the result of the operation — check the related man page for the possible values, bestie.

Now here's the thing, and it's lowkey important: 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 don't go looking in errno, she's not there. 🙈

---

💜 NOTES 💜

As with any request that passes in data in a struct, that data must remain valid until the request has been successfully submitted. It does not need to 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. Yeah. Those ones. 😬

Applications can test for this behavior by inspecting the IORING_FEAT_SUBMIT_STABLE flag passed back from io_uring_queue_init_params(3). Slay. ✅

---

👑 SEE ALSO 👑

• io_uring_get_sqe(3)
• io_uring_submit(3)
• io_uring_buf_ring_init(3)
• io_uring_buf_ring_add(3)
• recvmsg(2)

---

ok that's the whole page, you ate that 💖✨🎀🦋🌸💅🫶

This one's from liburing-2.2, dated March 12, 2022 — so yeah, she's been serving since way back, and she's still that girl. Bye bestie, go prep some requests 💜🌈⭐