io_uring_prep_statx(3)

💅 io_uring_prep_statx — the liburing manual, but make it cute

okay bestie, so this one lives in the liburing manual, and it's all about prepping a statx request. yes, the async kind. no cap. ✨

🌸 NAME 🌸

io_uring_prep_statx — prepare a statx request

like. that's the whole job. it prepares. it does not submit. it does not wait. it preps. main character energy, honestly. 🎀

✨ SYNOPSIS ✨

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

void io_uring_prep_statx(struct io_uring_sqe *sqe,
                         int dirfd,
                         const char *path,
                         int flags,
                         unsigned mask,
                         struct statx *statxbuf);

look at those includes. five headers and then liburing.h like the finale. the way that signature just sits there. 💜

🦋 DESCRIPTION 🦋

so. the io_uring_prep_statx(3) function prepares a statx request. the submission queue entry sqe gets set up to use the directory file descriptor pointed to by dirfd to start a statx operation on the path identified by path, and it uses the flags given in flags for the fields specified by mask, writing into the buffer located at statxbuf. periodt. 💅

this function prepares an async statx(2) request. and if you want the actual deets on what all of that even means, go read that man page, because this one is just the prep girlie. see statx(2) for details. 📖

🔥 RETURN VALUE 🔥

None

(yeah. it returns nothing. it's above returning things. it just sets up the sqe and lets you handle the rest. iconic behavior, ngl.) 🙈

💀 ERRORS 💀

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

and here's the tea, bestie — 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 like. don't go checking errno and getting confused. she doesn't play that game. 😭

⭐ 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. so if you're on something ancient, that's the vibe you're dealing with.

applications can test for this behavior by inspecting the IORING_FEAT_SUBMIT_STABLE flag passed back from io_uring_queue_init_params(3). it's giving "check the feature flag, bestie." 🌈

🫶 SEE ALSO 🫶

• io_uring_get_sqe(3)
• io_uring_submit(3)
• statx(2)

and that's the whole page, babes!! this little slice of documentation is from liburing-2.2, dated March 13, 2022, and it lives in the liburing Manual. go prep those statx requests. slay. 👑✨