io_uring_prep_symlinkat(3)

✨ io_uring_prep_symlinkat ✨

okay bestie, so this is a page from the liburing Manual, and it's all about io_uring_prep_symlinkat(3) — the function that gets your symlink requests ready to go. no cap, it's giving "make a link, but async" 💅

🌸 NAME 🌸

io_uring_prep_symlinkat — prepare a symlinkat request

🎀 SYNOPSIS 🎀

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

void io_uring_prep_symlinkat(struct io_uring_sqe *sqe,
                             const char *target,
                             int newdirfd,
                             const char *linkpath);

void io_uring_prep_symlink(struct io_uring_sqe *sqe,
                           const char *target,
                           const char *linkpath);

like, two whole functions, both of them icons 💖

🦋 DESCRIPTION 🦋

so, the io_uring_prep_symlinkat(3) function prepares a symlinkat request. it takes that submission queue entry, your sqe, and sets it up to symlink the target path that target points to, over to the new destination indicated by newdirfd and linkpath. that's the whole vibe 🌈

meanwhile, io_uring_prep_symlink(3) prepares a plain symlink request. the sqe gets set up to symlink the target path that target points to, over to the new destination indicated by linkpath — but this time relative to the current working directory. and yes, this one prepares an async symlink(2) request, so go read that man page for the deets 👑

fr fr, these functions prepare an async symlinkat(2) or symlink(2) request. see those man pages for details. periodt 💅

💜 RETURN VALUE 💜

None. that's it, that's the whole thing. nothing returned, no crumbs 🫶

💀 ERRORS 💀

the CQE res field is where the result of the operation lives. check the related man page for what possible values it could be, iykyk.

but here's the tea, bestie: where synchronous system calls would 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 don't be out here checking errno, she's not the main character here 😭

🔥 NOTES 🔥

okay so this is important. as 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 — she's locked in, no takebacks ✨

very early kernels (5.4 and earlier) required state to be stable until the completion occurred. so if you're on ancient kernel energy, watch out 💀

applications can test for this behavior by inspecting the IORING_FEAT_SUBMIT_STABLE flag passed back from io_uring_queue_init_params(3). go check that flag, it'll tell you what you're working with 🌟

⭐ SEE ALSO ⭐

• io_uring_get_sqe(3)
• io_uring_submit(3)
• symlinkat(2)
• symlink(2)

and that's the whole page, bestie!! 🎀 this one's from liburing-2.2, dated March 13, 2022 — so like, vintage but still slaying. go make some symlinks, you've got this 💖🦋✨