io_uring_pre...d_fd_install(3)

💖 io_uring_prep_fixed_fd_install(3) 💖

okay bestie, so this one lives in the liburing Manual and it's literally the glow-up arc for your file descriptors ✨

🌸 NAME 🌸

io_uring_prep_fixed_fd_install — get your fixed file fd installed, like it's moving into a whole new apartment 🏠💅

🎀 SYNOPSIS 🎀

#include <liburing.h>

void io_uring_prep_fixed_fd_install(struct io_uring_sqe *sqe,
                                    int fd,
                                    unsigned int flags);

✨ DESCRIPTION ✨

so the io_uring_prep_fixed_fd_install(3) helper is out here prepping a fixed file descriptor installation. it sets up the submission queue entry sqe to install the direct/fixed file descriptor fd, using whatever flags you hand it for the file installation flags. no cap, that's the whole job 🫶

one use case of direct/fixed file descriptors is turning a regular file descriptor into a direct one — that way any request that needs to touch this file has less overhead to deal with. this helper goes the other way, turning a direct descriptor into a regular file descriptor that can then be used by regular system calls that take a normal file descriptor. super handy when there's just… no regular file descriptor for this direct descriptor?? 😭 either because it got instantiated directly as a fixed descriptor, or because the regular file was closed with close(2) after it got turned into a direct descriptor. messy history, we don't judge 💀

once this request returns successfully, both a normal and a fixed file descriptor exist for the same file. either one can be used to access the file, and either one can be closed without affecting the other one. iconic, no drama, they don't even know each other 👑

now, flags can be either zero, or set to IORING_FIXED_FD_NO_CLOEXEC — which says the new regular file descriptor should not be closed during exec. by default, O_CLOEXEC gets set on the new descriptor otherwise. and listen, if you set this field to literally anything besides those two values, the request gets failed with -EINVAL in the CQE res field. so… don't 🙈

💜 RETURN VALUE 💜

None. nothing. zero. it's void, bestie, she gives nothing back directly 🎀

🔥 ERRORS 🔥

the CQE res field is where the tea actually lives — it holds the result of the operation, which in this case is the value of the new regular file descriptor. if it went sideways, you get a negative value back instead 😭

🌈 SEE ALSO 🌈

• io_uring_get_sqe(3)
• io_uring_submit(3)
• io_uring_register_files(3)
• io_uring_unregister_files(3)
• io_uring_prep_close_direct(3)
• io_uring_prep_openat_direct(3)

and that's the whole page, periodt 💅 this was brought to you by liburing-2.6, dated December 8, 2023 — go install some fixed fds, you've got this, mwah 🦋💖