io_uring_sqe_set_flags(3)

💅 io_uring_sqe_set_flags — the liburing manual, bestie edition 💅

okay so we're deep in the liburing manual, specifically the page for io_uring_sqe_set_flags. pull up a chair, grab a boba, we're doing kernel-adjacent lore today 🧋✨

🎀 NAME 🎀

io_uring_sqe_set_flags — the way you set flags for a submission queue entry, no cap 🫶

🌸 SYNOPSIS 🌸

#include <liburing.h>

void io_uring_sqe_set_flags(struct io_uring_sqe *sqe,
                            unsigned flags);

🦋 DESCRIPTION 🦋

so io_uring_sqe_set_flags(3) is literally the function that lets you, the caller, change the behavior of the submission queue entry by specifying flags. it enables the flags belonging to the sqe submission queue entry param. that's it, that's the job. 💁‍♀️

flags is a bit mask of 0 or more of the following values ORed together:

• IOSQE_FIXED_FILE — the file descriptor in the SQE refers to the index of a previously registered file or direct file descriptor, not a normal file descriptor. it's giving "i already told you about this file, go look it up" 👑
• IOSQE_ASYNC — normal io_uring operation is to try and issue an sqe as non-blocking first, and if that fails, execute it in an async manner. but to support more efficient overlapped operation of requests that the application knows / assumes will always (or most of the time) block, the application can ask for an sqe to be issued async from the start. heads up though: this flag immediately causes the SQE to be offloaded to an async helper thread with no initial non-blocking attempt. that may be less efficient, so don't use it liberally, and definitely not without understanding the performance and efficiency tradeoffs. 😭 (this is the "skip the vibe check and go straight to the line" flag)
• IOSQE_IO_LINK — when this flag is specified, the SQE forms a link with the next SQE in the submission ring. that next SQE will not be started before the previous request completes. this, in effect, forms a chain of SQEs, which can be arbitrarily long. the tail of the chain is denoted by the first SQE that does not have this flag set. chains are not supported across submission boundaries — even if the last SQE in a submission has this flag set, it will still terminate the current chain. this flag has no effect on previous SQE submissions, nor does it impact SQEs that are outside of the chain tail. which means multiple chains can be executing in parallel, or chains and individual SQEs can be running side by side. only members inside the chain are serialized. also, a chain of SQEs will be broken if any request in that chain ends in error. 💀
• IOSQE_IO_HARDLINK — like IOSQE_IO_LINK, except the links aren't severed if an error or unexpected result occurs. ride or die fr fr 🫶
• IOSQE_IO_DRAIN — when this flag is specified, the SQE will not be started before previously submitted SQEs have completed, and new SQEs will not be started before this one completes. it's giving "everyone wait, i'm going first and you can't start till i'm done" 🚧
• IOSQE_CQE_SKIP_SUCCESS — request that no CQE be generated for this request, if it completes successfully. this can be useful in cases where the application doesn't need to know when a specific request completed, if it completed successfully. lowkey the "don't text me if it went fine" option 🙈
• IOSQE_BUFFER_SELECT — if set, and if the request types supports it, select an IO buffer from the indicated buffer group. this can be used with requests that read or receive data from a file or socket, where buffer selection is deferred until the kernel is ready to transfer data, instead of when the IO is originally submitted. the application must also set the buf_group field in the SQE, indicating which previously registered buffer group to select a buffer from. pick your buffer at the last possible second, main character energy ✨

⭐ RETURN VALUE ⭐

None. literally nothing. it's void, bestie, it gives you nothing back and that's fine 🌈

💜 SEE ALSO 💜

• io_uring_submit(3)
• io_uring_register(3)
• io_uring_register_buffers(3)
• io_uring_register_buf_ring(3)

and that's the whole page, you ate it 💅 this was liburing-2.1, dated January 25, 2022 — go forth and set your flags, queen 👑🌸