io_uring_prep_msg_ring_fd(3)

💌 io_uring_prep_msg_ring_fd — send a direct descriptor to another ring

okay bestie, welcome to the liburing manual 💖 you're reading the page for io_uring_prep_msg_ring_fd(3) and honestly? it's giving ring-to-ring gossip. like, one ring is sliding a whole file descriptor to another ring. telepathy. iconic. 🦋

✨ SYNOPSIS ✨

#include <liburing.h>

void io_uring_prep_msg_ring_fd(struct io_uring_sqe *sqe,
                        int fd,
                        int source_fd,
                        int target_fd,
                        __u64 data,
                        unsigned int flags);

void io_uring_prep_msg_ring_fd_alloc(struct io_uring_sqe *sqe,
                        int fd,
                        int source_fd,
                        __u64 data,
                        unsigned int flags);

two functions, one vibe. let's get into it 💅

🌸 DESCRIPTION 🌸

io_uring_prep_msg_ring_fd(3)

so this one prepares an SQE that sends a direct file descriptor over to another ring. yes, rings can pass notes. 🎀

here's the tea:

• the submission queue entry sqe gets set up to use the file descriptor fd, and fd must identify a target io_uring context, no cap
• it sends the locally registered file descriptor whose value is source_fd
• that lands in the destination ring at index target_fd
• and data rides along as the user data in the target CQE 🫶
• the request modifier flags get set by flags

⚠️ heads up: right now there are no valid flag modifiers. that field has to contain 0. literally zero. don't get creative with it. 💀

io_uring_prep_msg_ring_fd_alloc(3)

this one is basically the sibling of io_uring_prep_msg_ring_fd(3) but it does not let you pick a target index for the direct descriptor. instead, the index gets allocated in the target ring and handed back to you in the CQE res field. surprise! 🎁 main character behavior fr fr.

💫 RETURN VALUE 💫

None

that's it. nothing. void. the silence after you send the perfect text. 😌

😭 ERRORS 😭

these are the errors that show up in the CQE res field. know them, love them, respect them.

• -ENOMEM — the kernel was unable to allocate memory for the request. out of brain cells, out of memory, same energy 🧠
• -EINVAL — one of the fields set in the SQE was invalid. something in there was Not It 🙈
• -EINVAL — the target ring is identical to the source ring. bestie you cannot text yourself. the rings have to be different 💀
• -EBADFD — the descriptor passed in fd does not refer to an io_uring file descriptor, or the ring is in a disabled state. not a ring, not today 🚫
• -EOVERFLOW — the kernel was unable to fill a CQE on the target ring. this can happen if the target CQ ring is in an overflow state and the kernel wasn't able to allocate memory for a new CQE entry. the target ring's inbox is just... full 📬
• -ENFILE — the direct descriptor table in the target ring was full, so no new descriptors could be successfully allocated. no room at the inn, no room in the table 🍓

🧚 a lil sign-off 🧚

this page is from liburing-2.4, dated Mar 16, 2023. go forth and pass descriptors between your rings like the absolute Unix icon you are. slay, periodt, and remember: flags stays 0. 💜👑