Time::timegm(3pm)

✨ Time::timegm — bestie's guide to UTC time 💖

okay so real quick: this is Time::timegm, a lil' Perl module that lives in the User Contributed Perl Documentation corner of your system, and it's basically a UTC version of mktime(). it's giving timezone-agnostic icon energy, no cap 🕐✨

---

🌸 NAME 🌸

Time::timegm — a UTC version of mktime() 🦋

---

💅 SYNOPSIS 💅

here's the vibe, bestie:

use Time::timegm qw( timegm );

my $epoch = timegm( 0, 0, 0, 14, 6-1, 2012-1900 );

print "2012-06-14 00:00:00 UTC happened at ",
   scalar localtime($epoch), " localtime\n";

like. look at her. converting a UTC date straight into an epoch and then printing what that epoch looks like in your local timezone. main character behavior tbh 👑

---

🎀 DESCRIPTION 🎀

okay so context time, and this part is genuinely important so stay with me 🫶

The POSIX standard hands you three whole functions for bouncing between integer epoch values and 6-component "broken-down" time representations. we love a clean conversion pipeline:

• localtime and gmtime — these take an epoch and spit out the 6 components: seconds, minutes, hours, day of month, month and year. localtime does it in your local timezone, gmtime does it in UTC.
• mktime — this one goes the other way and turns a local broken-down time into an epoch value.

and then... POSIX just doesn't give you a UTC version of that 😭 like hello?? where is she??

so that's literally what this module is for. it provides a function called timegm and it has exactly this ability. the missing piece, the moment, the slay 💖

and here's the part where it's lowkey better than some other options out there: unlike some other CPAN implementations of this behavior, this version does not re-implement the time handling logic internally. instead it reuses the mktime and gmtime functions that your system already provides, so its results are always consistent with the other functions. periodt. no drift, no drama, no "why does this one disagree with gmtime" situations 🙈

---

⭐ FUNCTIONS ⭐

💜 $epoch = timegm( $sec, $min, $hour, $mday, $mon, $year )

returns the epoch integer value representing the time given by those 6 broken-down components. that's it, that's the function 🫶

and now for the fun part — as with POSIX::mktime, it is not required that these values be within their "valid" ranges. this function will normalise values that are out of range. for example:

• the 25th hour of a day gets normalised to the 1st hour of the following day
• the 0th month gets normalised to the 12th month of the preceding year

so you can absolutely hand it chaos and it will do the math and hand you back a sensible epoch. she's flexible like that 💅✨

---

🦋 COMPARISON WITH Time::Local 🦋

okay so the Time::Local module ALSO ships a function called timegm() with behavior that's similar to this one. but bestie, there are differences and you need to know them:

• Time::timegm::timegm() handles denormalised values — that is, seconds or minutes outside of the range 0 to 59, hours outside 0 to 23, etc. — by adjusting the next largest unit (such that 61 seconds is 1 second of the next minute, etc.). Time::Local::timegm() croaks on out-of-range input. and yes, Time::Local also provides a function called timegm_nocheck() which does not croak, but it is documented that the behavior is unspecified on out-of-range values — so that's a big ol' "here be dragons" situation, be careful 💀
• Time::timegm::timegm() is implemented by a light XS wrapper around the timegm(3) or _mkgmtime(3) function provided by the platform's C library, if such a function is provided — so its behavior stays consistent with the rest of the platform. Time::Local re-implements the logic in perl code instead. and fyi, Time::timegm will fall back to a perl implementation only if the XS one cannot be used 🌈

tl;dr: one of them croaks on weird input, one of them normalises it. one of them rides the platform's C library, one of them does its own perl math. know which one you're calling, bestie 🫶

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk> — thank you for your service, legend 🎀

---

and that's the whole page, bestie!! this manual ships with perl v5.42.0 and it was dated 2025-07-25 — so yeah, she's fresh, she's documented, she's slaying. go convert some UTC times, you've got this 💖✨🦋