io_uring_prep_connect(3)

✨ io_uring_prep_connect — from the liburing manual, bestie edition ✨

okay so. sit down, grab your strawberry milk 🍓, because we're talking about io_uring_prep_connect(3) — that's the liburing page, section 3, and she is so useful.

🎀 NAME 🎀

io_uring_prep_connect — get a connect request all prepped and ready to go 💅

🦋 SYNOPSIS 🦋

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

void io_uring_prep_connect(struct io_uring_sqe *sqe,
                           int sockfd,
                           const struct sockaddr *addr,
                           socklen_t addrlen);

like, literally copy that, don't freestyle it 🙈

🌸 DESCRIPTION 🌸

so io_uring_prep_connect(3) does exactly what it says on the tin: it prepares a connect request. the submission queue entry sqe gets set up to use the file descriptor sockfd to start connecting to the destination described by the socket address at addr, and that structure's length is addrlen. simple. iconic. no notes. 👑

this function prepares an async connect(2) request — so if you want the deets on what connecting actually means, go read that man page, because that's where the lore lives. 📖

💖 RETURN VALUE 💖

None. that's it. nothing. void. she returns nothing because the whole vibe is "the result shows up in the CQE, babe." 😌

💀 ERRORS 💀

the CQE res field is gonna hold the result of the operation. what values could show up? check the related man page, bestie, that's where they're listed.

ok this part matters, don't skim it: normal synchronous system calls return -1 on failure and set errno to the actual error value. io_uring NEVER uses errno. instead, it hands you the negated errno directly in the CQE res field. so like, if you see a negative number in there, that's your error, and it's negative, and that's on purpose. no cap. 🔥

🧚 NOTES 🧚

okay so this is the part where we talk about lifetime, and it's giving "read this twice." 👀

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 — periodt. ✨

but listen: very early kernels (5.4 and earlier) were extra and required that state to stay stable until the completion occurred. 😭 if you wanna know which world you're living in, apps can test for this behavior by inspecting the IORING_FEAT_SUBMIT_STABLE flag passed back from io_uring_queue_init_params(3).

🌈 SEE ALSO 🌈

• io_uring_get_sqe(3)
• io_uring_submit(3)
• connect(2)

and that's the whole page, you ate it, you're welcome 🫶

liburing-2.2 · March 13, 2022 · mwah, love u, go submit some SQEs 💜🦋✨