UUID_TIME(3)

📦
version 2.41.6 · 14 versions
, in alpine 3.22, alpine 3.23, fedora 43, fedora 44

💅 UUID_TIME(3) 💅

okay so first things first, bestie: this is uuid_time(3), from the section 3 manual pages (that's the library-call section, iykyk). buckle up, we're doing time archaeology on UUIDs ✨

🌸 NAME 🌸

uuid_time — it pulls out the exact moment your UUID was born 🎀 like a birthday but for a 128-bit identifier

🦋 SYNOPSIS 🦋

#include <uuid.h>

time_t uuid_time(const uuid_t uu, struct timeval *ret_tv)

that's it. that's the whole vibe. two args, one timestamp, zero drama 💜

✨ DESCRIPTION ✨

so uuid_time() extracts the time at which the time-based UUID you handed it — uu — was created. literally pulling the birthday out of the ID. no cap.

but — and this is the important part, so pay attention bestie 🙈 — the UUID creation time is only encoded within certain types of UUIDs. it's not in all of them, it's not a universal thing, it's a "some UUIDs came with the timestamp baked in" situation.

so this function can only reasonably expect to extract the creation time for UUIDs that were created with uuid_generate_time(3) and uuid_generate_time_safe(3). those two, yes. those are the ones that behave.

with UUIDs created by other mechanisms? it may or may not work. and that "may or may not" is doing a LOT of heavy lifting, so like... don't come for this function when it doesn't give you what you want 😭 it warned you fr fr

⭐ RETURN VALUE ⭐

you get the time at which the UUID was created, in seconds since January 1, 1970 GMT — that's the epoch, bestie, the big bang of Unix time — returned as your return value (see time(2)). 🔥

and there's a bonus: the same creation time, but in seconds and microseconds since the epoch, also gets stored in the location pointed to by ret_tv (see gettimeofday(2)). so you get the seconds twice, once plain and once with the microsecond garnish. we love a two-for-one 🫶

👑 AUTHORS 👑

Theodore Y. Ts’o — the icon who wrote this, we stan 💖

💀 SEE ALSO 💀

the whole UUID friend group, all linked up 🧚

🐛 REPORTING BUGS 🐛

found a bug? no gatekeeping, go report it — use the issue tracker at <https://github.com/util-linux/util-linux/issues>. the maintainers want to hear from you, fr fr 🙏

🌈 AVAILABILITY 🌈

the libuuid library is part of the util-linux package since version 2.15.1. you can download it from the Linux Kernel Archive at <https://www.kernel.org/pub/linux/utils/util-linux/>. go get it, bestie 💅

okay that's the whole thing!! this page is util-linux 2.41.6, dated 2026-08-31, and honestly? iconic. periodt. 🍓🦋✨

📦 where this page comes from