io_uring_prep_cmd_discard(3)

✨ io_uring_prep_cmd_discard ✨

okay bestie, so this one lives in the liburing manual, and it's literally the glow-up for preparing a discard command. discard = telling your storage "hey, this chunk? don't need it, throw it out 💅". let's get into it 🫶

🌸 SYNOPSIS 🌸

#include <liburing.h>

void io_uring_prep_cmd_discard(struct io_uring_sqe *sqe,
                          int fd,
                          uint64_t offset,
                          uint64_t nbytes);

🦋 DESCRIPTION 🦋

so the way that io_uring_prep_cmd_discard(3) works is: it preps a discard command request, no cap. the submission queue entry sqe gets set up to use the file descriptor fd to start discarding nbytes at the specified offset. that's it, that's the whole vibe ✨

now here's the tea ☕ — this command is an asynchronous equivalent of the BLOCK_URING_CMD_DISCARD ioctl, but with a few differences:

• it lets you do multiple parallel discards 🔥
• and it does not exclude concurrent writes and reads

and that last one is highkey the important part, so listen up bestie:

it may lead to races for the data on the disk, if the application has IO inflight for the same ranges that the discard operates on. it's the user's responsibility to account for that. 😭

also, only best efforts are done to invalidate page caches. the user has to make sure that no other inflight requests are modifying or reading the range(s). if that is the case, it might result in stale page cache and data inconsistencies. 💀 so like, be careful fr fr.

available since 6.12. 🎀

⭐ RETURN VALUE ⭐

None. that's it. nothing. zero. the void. 🙈

👑 ERRORS 👑

the CQE res field will contain the result of the operation, periodt.

• on success, this field will be set to 0
• on error, a negative error value is returned

and ngl here's the quirky part — 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. iconic behavior, honestly 🌈

💖 SEE ALSO 💖

• io_uring_get_sqe(3)
• io_uring_submit(3)

and that's the whole page, bestie! this one came from liburing-2.8, dated Oct 13, 2024, and it's all about io_uring_prep_cmd_discard(3). go forth and discard responsibly, mwah 💅💜🦋