1Time::timegm(3)       User Contributed Perl Documentation      Time::timegm(3)
2
3
4

NAME

6       "Time::timegm" - a UTC version of "mktime()"
7

SYNOPSIS

9        use Time::timegm qw( timegm );
10
11        my $epoch = timegm( 0, 0, 0, 14, 6-1, 2012-1900 );
12
13        print "2012-06-14 00:00:00 UTC happened at ",
14           scalar localtime($epoch), " localtime\n";
15

DESCRIPTION

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
25       This module provides a function "timegm" which has this ability.
26
27       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

FUNCTIONS

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
37       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

COMPARISON WITH Time::Local

44       The Time::Local module also provides a function called timegm() with
45       similar behaviour to this one. The differences are:
46
47       • 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
55       • 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

AUTHOR

63       Paul Evans <leonerd@leonerd.org.uk>
64
65
66
67perl v5.36.0                      2023-01-20                   Time::timegm(3)
Impressum