io_uring_prep_timeout(3)

💖 io_uring_prep_timeout — bestie edition 💖

okay so this is a page from the liburing Manual, and it's literally about io_uring_prep_timeout(3) — the function that sets up a timeout request. yes, THE timeout request. let's get into it 🫶

---

✨ NAME ✨

io_uring_prep_timeout — prepare a timeout request. that's it, that's the whole name. iconic.

---

🌸 SYNOPSIS 🌸

#include <liburing.h>

void io_uring_prep_timeout(struct io_uring_sqe *sqe,
                           const struct __kernel_timespec *ts,
                           unsigned count,
                           unsigned flags);

look at that signature. she's beautiful. no return value, just vibes and side effects 💅

---

🦋 DESCRIPTION 🦋

so the io_uring_prep_timeout(3) function prepares a timeout request. like, it gets one ready to go.

the submission queue entry sqe gets set up to arm a timeout — that timeout is specified by ts, and it comes with a timeout count of count completion entries. the flags argument holds modifier flags for the request. slay.

now here's the tea: this request type can be used as a timeout that wakes anyone who's sleeping and waiting for events on the CQ ring. so like, a lil alarm clock for your ring. ⏰

the flags argument may contain these babies:

• IORING_TIMEOUT_ABS — the value specified in ts is an absolute value rather than a relative one.
• IORING_TIMEOUT_BOOTTIME — the boottime clock source should be used.
• IORING_TIMEOUT_REALTIME — the realtime clock source should be used.
• IORING_TIMEOUT_ETIME_SUCCESS — consider an expired timeout a success in terms of the posted completion. this means it will not sever dependent links, the way a failed request normally would. but heads up bestie, the posted CQE result code will still contain -ETIME in the res value. so it's a success on the outside, -ETIME on the inside 😭
• IORING_TIMEOUT_MULTISHOT — the request will return multiple timeout completions. the completion flag IORING_CQE_F_MORE is set if more timeouts are expected. the value specified in count is the number of repeats. a value of 0 means the timeout is indefinite and can only be stopped by a removal request. available since the 6.4 kernel. she's new here but she's already main character energy 👑

fr fr: if no alternate clock source is given in the above flags, then CLOCK_MONOTONIC is used. default queen.

and the timeout completion event will trigger if either the specified timeout has occurred, or the specified number of events to wait for have been posted to the CQ ring. whichever comes first, bestie. race you there 🏁

---

💜 RETURN VALUE 💜

None.

literally none. nothing. void. the silence is the answer 🙈

---

💀 ERRORS 💀

these are the errors that get reported in the CQE res field. on success, 0 is returned. (we love a zero.)

• -ETIME — the specified timeout occurred and triggered the completion event. time's up, babes ⏰
• -EINVAL — one of the fields set in the SQE was invalid. for example, two clocksources were given, or the specified timeout seconds or nanoseconds were < 0. pick a clock, any clock, just not two 🫠
• -EFAULT — io_uring was unable to access the data specified by ts. it tried to read it and just... couldn't. embarrassing for everyone 💀
• -ECANCELED — the timeout was canceled by a removal request. somebody said "never mind" and meant it.

---

🎀 NOTES 🎀

okay important one, listen up. as with 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. periodt.

but here's the throwback lore: very early kernels (5.4 and earlier) required state to be stable until the completion occurred. ancient behaviour. apps can test for this behavior by inspecting the IORING_FEAT_SUBMIT_STABLE flag passed back from io_uring_queue_init_params(3).

so if you're on some fossil kernel, keep your data alive longer. iykyk 🧚

---

🌈 SEE ALSO 🌈

• io_uring_get_sqe(3)
• io_uring_submit(3)
• io_uring_prep_timeout_remove(3)
• io_uring_prep_timeout_update(3)

go read those too, bestie, they're all connected like a little friend group 🫶

---

and that's the whole page, no cap. this was brought to you by liburing-2.2, dated March 12, 2022 — so yeah, she's been out here serving timeout realness since 2022 and she has not missed once. mwah, go arm some timeouts, you got this 💖✨🎀🦋🌸💅