io_uring_prep_openat(3)

💖 io_uring_prep_openat — the liburing girlies' guide 💖

okay so bestie, you're in the liburing Manual and today we're learning how to prep an openat request with io_uring. yes this is the io_uring_prep_openat(3) page, and no I will not be normal about it. let's go ✨

🌸 NAME 🌸

io_uring_prep_openat — prepare an openat request

🎀 SYNOPSIS 🎀

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <liburing.h>

void io_uring_prep_open(struct io_uring_sqe *sqe,
                          const char *path,
                          int flags,
                          mode_t mode);

void io_uring_prep_open_direct(struct io_uring_sqe *sqe,
                                 const char *path,
                                 int flags,
                                 mode_t mode,
                                 unsigned file_index);

void io_uring_prep_openat(struct io_uring_sqe *sqe,
                          int dfd,
                          const char *path,
                          int flags,
                          mode_t mode);

void io_uring_prep_openat_direct(struct io_uring_sqe *sqe,
                                   int dfd,
                                   const char *path,
                                   int flags,
                                   mode_t mode,
                                   unsigned file_index);

four whole glow-ups in one page, we're being so spoiled rn 💅

✨ DESCRIPTION ✨

so. io_uring_prep_openat(3) prepares an openat request. the submission queue entry sqe gets set up to use the directory file descriptor dfd to start opening a file described by path, using the open flags in flags, and using the file mode bits specified in mode. and like, same energy: io_uring_prep_open(3) prepares an open request. two icons, one job 🫶

🦋 the direct variants (aka the fancy ones) 🦋

if you're using the direct variant, the application must first have registered a file table using io_uring_register_files(3) of the appropriate size. no table, no direct, that's the rule bestie.

once that's registered, a direct accept request may use any entry in that table, and you specify which one in file_index — as long as it's within the size of the registered table. if a specified entry already contains a file, the file will first be removed from the table and closed. this is consistent with the behavior of updating an existing file with io_uring_register_files_update(3). so yes, you're overwriting, and yes, it closes the old one first. noted 💀

if IORING_FILE_INDEX_ALLOC is used as the file_index for a direct open, then io_uring will allocate a free direct descriptor in the existing table. the allocated descriptor is returned in the CQE res field, just like it would be for a non-direct open request. and if there are no more entries available in the direct descriptor table? -ENFILE is returned instead. sad but true 😭

👑 what even IS a direct descriptor 👑

direct descriptors are io_uring private file descriptors. they avoid some of the overhead associated with thread shared file tables, and they can be used in any subsequent io_uring request that takes a file descriptor. to do that:

• IOSQE_FIXED_FILE must be set in the SQE flags member, and
• the SQE fd field should use the direct descriptor value rather than the regular file descriptor.

direct descriptors are managed like registered files. periodt ✨

also, quick thing: the directory file descriptor dfd is always a regular file descriptor. no direct energy for dfd, sorry.

⚠️ heads up bestie: old kernels don't check the SQE file_index field. this is not a problem for liburing helpers, but users of the raw io_uring interface need to zero SQEs to avoid unexpected behavior. like, actually zero them. don't skip this 🙈

and finally — these functions prepare an async openat(2) or open(2) request. go read that man page for details, iykyk 📖

🌈 RETURN VALUE 🌈

None. that's it, that's the whole section. nothing returned, we simply vibe 🌸

💜 ERRORS 💜

the CQE res field will contain the result of the operation. see the related man page for details on possible values.

⚠️ and this part matters: 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 stop checking errno, bestie, it's not the moment 🔥

🧚 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 need not 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. applications can test for this behavior by inspecting the IORING_FEAT_SUBMIT_STABLE flag passed back from io_uring_queue_init_params(3). good to know, iconic to check 💅

🍓 SEE ALSO 🍓

• io_uring_get_sqe(3)
• io_uring_submit(3)
• io_uring_register(2)
• openat(2)

k bye bestie, go open some files 💖 this page is brought to you by liburing-2.2, dated March 13, 2022 — slay, mwah 🎀✨