io_uring_prep_mkdirat(3)

✨ io_uring_prep_mkdirat — the liburing glow-up ✨

okay bestie, we're doing liburing today and honestly? it's giving "make a directory but async, and make it cute." no cap, let's go 💅

🌸 NAME 🌸

io_uring_prep_mkdirat — prepare an mkdirat request 🫶

🎀 SYNOPSIS 🎀

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

void io_uring_prep_mkdirat(struct io_uring_sqe *sqe,
                           int dirfd,
                           const char *path,
                           mode_t mode);

void io_uring_prep_mkdir(struct io_uring_sqe *sqe,
                         const char *path,
                         mode_t mode);

💖 DESCRIPTION 💖

so. io_uring_prep_mkdirat(3) prepares a mkdirat request. the submission queue entry sqe gets set up to use the directory file descriptor that dirfd points at, to start a mkdirat operation on the path identified by path, with the mode given in mode. iconic behavior, truly. ✨

then there's io_uring_prep_mkdir(3), which prepares a mkdir request. that one sets up the submission queue entry sqe to use the current working directory to start a mkdir operation on the path identified by path, with the mode given in mode. same energy, just no dirfd, she works with what she's got 💁♀️

both of these functions prepare an async mkdir(2) or mkdirat(2) request. lowkey if you want the full tea on how that goes down, go read those man pages, because the details live there. 📖

⭐ RETURN VALUE ⭐

None. that's it. nothing returned. she gives you nothing and you respect it. 💀

🔥 ERRORS 🔥

the CQE res field is where the result of the operation shows up. check the related man page for what values are possible, bestie, because that's where the lore is.

now here's the important part, and I need you to lock in: where synchronous system calls will return -1 on failure and set errno to the actual error value, io_uring never uses errno. nope. instead it returns the negated errno directly in the CQE res field. periodt. 🚨

🦋 NOTES 🦋

okay so this part is the "don't get got" section. 🙈

like 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. slay.

⚠️ BUT — and this is the plot twist — very early kernels (5.4 and earlier) required state to be stable until the completion occurred. so if you're out here living in the past, be careful.

apps can test for this behavior by inspecting the IORING_FEAT_SUBMIT_STABLE flag that gets passed back from io_uring_queue_init_params(3). vibe check your kernel, basically. 🌈

👑 SEE ALSO 👑

• io_uring_get_sqe(3)
• io_uring_submit(3)
• mkdirat(2)
• mkdir(2)

and that's the whole page, bestie, you ate. this was served up by liburing-2.2 on March 13, 2022 — go make some directories, but like, asynchronously 💜✨🍓