io_uring_prep_timeout_update(3)

💖 io_uring_prep_timeout_update — bestie edition 💖

okay so this is a page from the liburing Manual, and we're talking about io_uring_prep_timeout_update(3) — the girlies who edit timeouts instead of just making them. she's the glow-up arc of timeout requests, fr fr. ✨

---

✨ NAME ✨

io_uring_prep_timeout_update — get a request ready to update an existing timeout

---

🎀 SYNOPSIS 🎀

#include <liburing.h>

void io_uring_prep_timeout_update(struct io_uring_sqe *sqe,
                                  const struct __kernel_timespec *ts,
                                  __u64 user_data,
                                  unsigned flags);

void io_uring_prep_timeout_remove(struct io_uring_sqe *sqe,
                                  __u64 user_data,
                                  unsigned flags);

---

💅 DESCRIPTION 💅

so basically these two functions are the modify-and-cancel squad for timeouts you already have going. they take your submission queue entry sqe and set it up to either update or remove a timeout — which one you're messing with is picked out by user_data, and the modifier behaviour comes from flags.

and because it's an update, bestie, it also takes a ts structure, and ts is where the new timeout info lives. new numbers, new deadline, new vibe. 💫

for an update request, that flags member can be a bitmask made of these cuties:

• IORING_TIMEOUT_ABS — the value you dropped in ts is an absolute value, not a relative one. no counting from now, she's an absolute queen.
• IORING_TIMEOUT_BOOTTIME — use the boottime clock source, bestie.
• IORING_TIMEOUT_REALTIME — use the realtime clock source instead.
• IORING_TIMEOUT_ETIME_SUCCESS — treat an expired timeout as a success when it comes to the posted completion. normally, when a timeout actually triggers, you get back a -ETIME in the CQE res value. with this flag? expired = win. 😌

and the timeout remove command? she does not currently accept any flags. not one. zero. periodt. 💀

---

🫶 RETURN VALUE 🫶

None. she gives you nothing back directly, it's giving mysterious. the real tea shows up in the CQE.

---

😭 ERRORS 😭

these are the errors that get reported in the CQE res field. when everything's good, you get 0 back. slay.

• -ENOENT — the timeout identified by user_data could not be found. maybe it's invalid, or maybe it already triggered before your update or removal request even got processed. she's gone, bestie. 🙈
• -EALREADY — the timeout identified by user_data is already firing and cannot be canceled. too late, she's mid-main-character-moment.
• -EINVAL — one of the fields you set in the SQE was invalid. like, for example, you gave two clocksources (pick ONE, girl), or the timeout seconds or nanoseconds you specified were < 0.
• -EFAULT — io_uring was unable to access the data specified by ts.

---

🧚 NOTES 🧚

okay this part is important so listen up. as with any request that passes in data in a struct, that data has to stay valid until the request has been successfully submitted. it does not need to stay valid until completion. once a request has been submitted, the in-kernel state is stable. 💅

very early kernels (5.4 and earlier) were the exception though — they required that state to stay stable all the way until the completion happened. so old-school. if you wanna know whether you're dealing with that behavior, apps can test for it by inspecting the IORING_FEAT_SUBMIT_STABLE flag that gets passed back from io_uring_queue_init_params(3). iykyk 🌸

---

🌈 SEE ALSO 🌈

• io_uring_get_sqe(3)
• io_uring_submit(3)
• io_uring_prep_timeout(3)

---

and that's the whole page, bestie! this one's from liburing-2.2, dated March 12, 2022 — genuinely iconic of her, no cap. go forth and update your timeouts responsibly, mwah 💖🦋👑