io_uring_get_sqe(3)

✨ io_uring_get_sqe — bestie edition ✨

okay so this one is from the liburing manual, and it's literally the function that hands you your next submission queue entry. no cap, it's the plug. 🫶

🌸 NAME 🌸

io_uring_get_sqe — grab the next available submission queue entry off the submission queue 💅

🦋 SYNOPSIS 🦋

#include <liburing.h>

struct io_uring_sqe *io_uring_get_sqe(struct io_uring *ring);

💖 DESCRIPTION 💖

so the io_uring_get_sqe(3) function gets you the next available submission queue entry from the submission queue that belongs to the ring param. that's it, that's the job. she's a giver. 👑

on success, io_uring_get_sqe(3) returns a pointer to that submission queue entry. on failure, it returns NULL. (and if you got NULL, go read RETURN VALUE below, it's giving "queue is full, bestie".)

if a submission queue entry does come back to you, you fill it out with one of the prep functions — like io_uring_prep_read(3), iconic — and then you submit it with io_uring_submit(3). that's the whole flow, no skipping steps. ✨

⚠️ the note that eats, fr fr: neither io_uring_get_sqe nor the prep functions set (or clear) the user_data field of the SQE. so if you're expecting io_uring_cqe_get_data(3) or io_uring_cqe_get_data64(3) to return valid data when you're reaping IO completions, then either io_uring_sqe_set_data(3) or io_uring_sqe_set_data64(3) MUST have been called before submitting the request. not "should", not "maybe", MUST. periodt. 💀

⭐ RETURN VALUE ⭐

io_uring_get_sqe(3) returns a pointer to the next submission queue event on success, and NULL on failure.

and if it hands you NULL? that means the SQ ring is currently full, and entries must be submitted for processing before new ones can get allocated. basically: girl, submit your work before you ask for more. 🎀

🌈 SEE ALSO 🌈

• io_uring_submit(3)
• io_uring_sqe_set_data(3)

and that's the whole page, bestie!! 🦋 this came to you from liburing-0.7, dated July 10, 2020 — oldie but a goodie, still serving. go get your SQEs and slay 💜✨