1Time::timegm(3) User Contributed Perl Documentation Time::timegm(3)
2
6 "Time::timegm" - a UTC version of "mktime()"
7
9 use Time::timegm qw( timegm );
10 my $epoch = timegm( 0, 0, 0, 14, 6-1, 2012-1900 );
12 print "2012-06-14 00:00:00 UTC happened at ",
14 scalar localtime($epoch), " localtime\n";
15
17 The POSIX standard provides three functions for converting between
18 integer epoch values and 6-component "broken-down" time
19 representations. "localtime" and "gmtime" convert an epoch into the 6
20 components of seconds, minutes, hours, day of month, month and year, in
21 either local timezone or UTC. The "mktime" function converts a local
22 broken-down time into an epoch value. However, "POSIX" does not
23 provide a UTC version of this.
24 This module provides a function "timegm" which has this ability.
26 Unlike some other CPAN implementations of this behaviour, this version
28 does not re-implement the time handling logic internally. It reuses the
29 "mktime" and "gmtime" functions provided by the system to ensure its
30 results are always consistent with the other functions.
31
33 $epoch = timegm( $sec, $min, $hour, $mday, $mon, $year )
34 Returns the epoch integer value representing the time given by the 6
35 broken-down components.
36 As with "POSIX::mktime" it is not required that these values be within
38 their "valid" ranges. This function will normalise values out of range.
39 For example, the 25th hour of a day is normalised to the 1st hour of
40 the following day; or the 0th month is normalised to the 12th month of
41 the preceeding year.
42
44 The Time::Local module also provides a function called timegm() with
45 similar behaviour to this one. The differences are:
46 • Time::timegm::timegm() handles denormalised values (that is, seconds
48 or minutes outside of the range 0 to 59, hours outside 0 to 23,
49 etc..) by adjusting the next largest unit (such that 61 seconds is 1
50 second of the next minute, etc). Time::Local::timegm() croaks on out-
51 of-range input. "Time::Local" also provides a function
52 timegm_nocheck() which does not croak but it is documented that the
53 behavior is unspecified on out-of-range values.
54 • Time::timegm::timegm() is implemented by a light XS wrapper around
56 the timegm(3) or _mkgmtime(3) function provided by the platform's C
57 library if such a function is provided, so its behaviour is
58 consistent with the rest of the platform. "Time::Local" re-implements
59 the logic in perl code. "Time::timegm" will fall back to a perl
60 implementation only if the XS one cannot be used.
61
63 Paul Evans <leonerd@leonerd.org.uk>
64perl v5.36.0 2023-01-20 Time::timegm(3)