io_uring_prep_renameat(3)

💅 io_uring_prep_renameat — the liburing manual, bestie edition

okay so you want to move/rename files but make it async? say less. this is io_uring_prep_renameat(3) from the liburing manual and she is lowkey iconic.

✨ NAME ✨

io_uring_prep_renameat — get a renameat request all prepped and ready 🎀

✨ SYNOPSIS ✨

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

void io_uring_prep_renameat(struct io_uring_sqe *sqe,
                            int olddirfd,
                            const char *oldpath,
                            int newdirfd,
                            const char *newpath,
                            unsigned int flags);

void io_uring_prep_rename(struct io_uring_sqe *sqe,
                          const char *oldpath,
                          const char *newpath);

✨ DESCRIPTION ✨

so io_uring_prep_renameat(3) prepares a renameat request. the submission queue entry sqe gets set up to use the old directory file descriptor that olddirfd points to, plus the old path that oldpath points to, and then the new directory file descriptor that newdirfd points to with the new path that newpath points to — all using whatever you dropped into flags. 🦋

and io_uring_prep_rename(3) prepares a rename request. the submission queue entry sqe gets set up to use the old path that oldpath points to together with the new path that newpath points to, both relative to the current working directory, and using the specified flags in flags. periodt.

these functions prepare an async renameat2(2) or rename(2) request. if flags is zero, then this call is similar to the renameat(2) system call. go read those man pages for the details, iykyk. 📚

✨ RETURN VALUE ✨

none. nope. nothing. the void returns nothing, bestie. 🙈

✨ ERRORS ✨

the res field of the CQE is where the result of the operation lives. check the related man page for the possible values, fr fr. 🍓

⚠️ important: 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. no cap.

✨ NOTES ✨

like with any request that passes in data in a struct, that data has to stay valid until the request has been successfully submitted. it does not need to stay valid until completion — once a request has been submitted, the in-kernel state is stable. 🫶

very early kernels (5.4 and earlier) did require that state to stay stable until the completion occurred, so watch out for the old ones. applications can test for this behavior by inspecting the IORING_FEAT_SUBMIT_STABLE flag passed back from io_uring_queue_init_params(3). 💜

✨ SEE ALSO ✨

• io_uring_get_sqe(3)
• io_uring_submit(3)
• renameat(2)
• renameat2(2)
• rename(2)

liburing-2.2 · March 13, 2022 — that's the vibe check, we're done here. go rename something, bestie, you're the main character now 👑✨💖