io_uring_prep_unlinkat(3)

✨ io_uring_prep_unlinkat — prepare an unlinkat request ✨

okay bestie, welcome to the liburing Manual 💖 this is the page for deleting files the async way, and it's actually so much simpler than it sounds. buckle up 🎀

🌸 NAME 🌸

io_uring_prep_unlinkat — prepare an unlinkat request

🦋 SYNOPSIS 🦋

#include <fcntl.h>
#include <unistd.h>
#include <liburing.h>

void io_uring_prep_unlinkat(struct io_uring_sqe *sqe,
                            int dirfd,
                            const char *path,
                            int flags);

void io_uring_prep_unlink(struct io_uring_sqe *sqe,
                          const char *path,
                          int flags);

💜 DESCRIPTION 💜

so, io_uring_prep_unlinkat(3) prepares an unlinkat request. the submission queue entry sqe gets set up to use the directory file descriptor that dirfd points at, to start an unlinkat operation on the path identified by path, using the flags you passed in flags. yeah it's literally that straightforward 💅

and io_uring_prep_unlink(3) prepares an unlink request. same deal: the submission queue entry sqe gets set up to start an unlinkat operation on the path identified by path, but this time relative to the current working directory instead of some dirfd, and using the flags given in flags. no dirfd, no problem 🫶

basically both of these are preparing an async unlinkat(2) or unlink(2) request. if you want the actual details of what those do, go read those man pages, they're the main characters of that story 👑

🌈 RETURN VALUE 🌈

None. it's a void function bestie, it returns nothing, it just sets your sqe up and vibes ✨

😭 ERRORS 😭

the CQE res field is gonna hold the result of the operation. check the related man page for what possible values can show up there 👀

okay this part matters: where synchronous system calls 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 if you see a negative number, that's your error, fr fr 💀

🧚 NOTES 🧚

like with literally any request that passes data in a struct, that data must remain valid until the request has been successfully submitted. it does not need to stay valid until completion though. once a request has been submitted, the in-kernel state is stable and you're free 🌸

tiny history moment: very early kernels (5.4 and earlier) required that state to stay stable all the way until the completion occurred. so if you're dealing with ancient kernels, watch out 🙈

applications can test for this behavior by inspecting the IORING_FEAT_SUBMIT_STABLE flag that gets passed back from io_uring_queue_init_params(3). iconic little flag, lowkey saves you 🎀

👑 SEE ALSO 👑

• io_uring_get_sqe(3)
• io_uring_submit(3)
• unlinkat(2)
• unlink(2)

and that's the whole page bestie!! this was liburing-2.2, dated March 13, 2022 🌟 go delete some files (responsibly), slay, and remember: negative res = the errno, not a vibe 💅💖🦋