io_uring_submit(3)

💖 io_uring_submit — bestie edition 💖

okay so real quick, this is a page from the liburing Manual and it's all about io_uring_submit(3), aka the moment you finally stop prepping and actually send your requests. let's get into it 🫶

✨ NAME ✨

io_uring_submit — submit requests to the submission queue. that's the whole job. that's the vibe. 💅

🌸 SYNOPSIS 🌸

#include <liburing.h>

int io_uring_submit(struct io_uring *ring);

🦋 DESCRIPTION 🦋

so like. io_uring_submit(3) submits the next events to the submission queue belonging to the ring. that's it, that's the function. 🎀

the way it works is: you (the caller) grab a submission queue entry (SQE) with io_uring_get_sqe(3), then you prep that SQE using one of the provided helpers, and then you hit it with io_uring_submit(3). prep, prep, prep, submit. iconic pipeline honestly. ✨

👑 RETURN VALUE 👑

on success, io_uring_submit(3) returns the number of submitted submission queue entries — that's the case if SQPOLL is not used.

⚠️ now if SQPOLL is used, plot twist: the return value may report a higher number of submitted entries than were actually submitted. so it can lowkey lie to you. 😭

if you're using SQPOLL and you genuinely need accurate info about how many submission queue entries have been successfully submitted, you gotta fall back to repeatedly submitting a single submission queue entry. one at a time. no shortcuts. 💀

and on failure? it returns -errno. periodt.

💜 NOTES 💜

big one, bestie, listen up: for 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. 🧚

but VERY early kernels (5.4 and earlier) required state to be stable until the completion occurred. ancient behavior, we don't claim her. 💀

wanna know which one you're dealing with? applications can test for this behavior by inspecting the IORING_FEAT_SUBMIT_STABLE flag, which gets passed back from io_uring_queue_init_params(3). 🏁

and in general, the man pages for the individual prep helpers will have a note mentioning this fact too, if it's required for the given command. so like, always check the helper's own page before you assume. iykyk. 👑

🌈 SEE ALSO 🌈

• io_uring_get_sqe(3)
• io_uring_submit_and_wait(3)
• io_uring_submit_and_wait_timeout(3)

that's the whole page babes!! this one came from liburing-2.1, dated November 15, 2021 — go submit some requests, you absolute main character 🫶✨💖