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

NAME

6       Time::Local - Efficiently compute time from local and GMT time
7

VERSION

9       version 1.30
10

SYNOPSIS

12           use Time::Local qw( timelocal_posix timegm_posix );
13
14           my $time = timelocal_posix( $sec, $min, $hour, $mday, $mon, $year );
15           my $time = timegm_posix( $sec, $min, $hour, $mday, $mon, $year );
16

DESCRIPTION

18       This module provides functions that are the inverse of built-in perl
19       functions "localtime()" and "gmtime()". They accept a date as a six-
20       element array, and return the corresponding time(2) value in seconds
21       since the system epoch (Midnight, January 1, 1970 GMT on Unix, for
22       example). This value can be positive or negative, though POSIX only
23       requires support for positive values, so dates before the system's
24       epoch may not work on all operating systems.
25
26       It is worth drawing particular attention to the expected ranges for the
27       values provided. The value for the day of the month is the actual day
28       (i.e. 1..31), while the month is the number of months since January
29       (0..11). This is consistent with the values returned from "localtime()"
30       and "gmtime()".
31

FUNCTIONS

33   "timelocal_posix()" and "timegm_posix()"
34       These functions are the exact inverse of Perl's built-in "localtime"
35       and "gmtime" functions. That means that calling "timelocal_posix(
36       localtime($value) )" will always give you the same $value you started
37       with. The same applies to "timegm_posix( gmtime($value) )".
38
39       The one exception is when the value returned from "localtime()"
40       represents an ambiguous local time because of a DST change. See the
41       documentation below for more details.
42
43       These functions expect the year value to be the number of years since
44       1900, which is what the "localtime()" and "gmtime()" built-ins returns.
45
46       They perform range checking by default on the input $sec, $min, $hour,
47       $mday, and $mon values and will croak (using "Carp::croak()") if given
48       a value outside the allowed ranges.
49
50       While it would be nice to make this the default behavior, that would
51       almost certainly break a lot of code, so you must explicitly import
52       these functions and use them instead of the default "timelocal()" and
53       "timegm()".
54
55       You are strongly encouraged to use these functions in any new code
56       which uses this module. It will almost certainly make your code's
57       behavior less surprising.
58
59   "timelocal_modern()" and "timegm_modern()"
60       When "Time::Local" was first written, it was a common practice to
61       represent years as a two-digit value like 99 for 1999 or 1 for 2001.
62       This caused all sorts of problems (google "Y2K problem" if you're very
63       young) and developers eventually realized that this was a terrible
64       idea.
65
66       The default exports of "timelocal()" and "timegm()" do a complicated
67       calculation when given a year value less than 1000. This leads to
68       surprising results in many cases. See "Year Value Interpretation" for
69       details.
70
71       The "time*_modern()" functions do not do this year munging and simply
72       take the year value as provided.
73
74       They perform range checking by default on the input $sec, $min, $hour,
75       $mday, and $mon values and will croak (using "Carp::croak()") if given
76       a value outside the allowed ranges.
77
78   "timelocal()" and "timegm()"
79       This module exports two functions by default, "timelocal()" and
80       "timegm()".
81
82       They perform range checking by default on the input $sec, $min, $hour,
83       $mday, and $mon values and will croak (using "Carp::croak()") if given
84       a value outside the allowed ranges.
85
86       Warning: The year value interpretation that these functions and their
87       nocheck variants use will almost certainly lead to bugs in your code,
88       if not now, then in the future. You are strongly discouraged from using
89       these in new code, and you should convert old code to using either the
90       *_posix or *_modern functions if possible.
91
92   "timelocal_nocheck()" and "timegm_nocheck()"
93       If you are working with data you know to be valid, you can use the
94       "nocheck" variants, "timelocal_nocheck()" and "timegm_nocheck()". These
95       variants must be explicitly imported.
96
97       If you supply data which is not valid (month 27, second 1,000) the
98       results will be unpredictable (so don't do that).
99
100       Note that my benchmarks show that this is just a 3% speed increase over
101       the checked versions, so unless calling "Time::Local" is the hottest
102       spot in your application, using these nocheck variants is unlikely to
103       have much impact on your application.
104
105   Year Value Interpretation
106       This does not apply to the *_posix or *_modern functions. Use those
107       exports if you want to ensure consistent behavior as your code ages.
108
109       Strictly speaking, the year should be specified in a form consistent
110       with "localtime()", i.e. the offset from 1900. In order to make the
111       interpretation of the year easier for humans, however, who are more
112       accustomed to seeing years as two-digit or four-digit values, the
113       following conventions are followed:
114
115       •   Years greater than 999 are interpreted as being the actual year,
116           rather than the offset from 1900. Thus, 1964 would indicate the
117           year Martin Luther King won the Nobel prize, not the year 3864.
118
119       •   Years in the range 100..999 are interpreted as offset from 1900, so
120           that 112 indicates 2012. This rule also applies to years less than
121           zero (but see note below regarding date range).
122
123       •   Years in the range 0..99 are interpreted as shorthand for years in
124           the rolling "current century," defined as 50 years on either side
125           of the current year. Thus, today, in 1999, 0 would refer to 2000,
126           and 45 to 2045, but 55 would refer to 1955. Twenty years from now,
127           55 would instead refer to 2055. This is messy, but matches the way
128           people currently think about two digit dates. Whenever possible,
129           use an absolute four digit year instead.
130
131       The scheme above allows interpretation of a wide range of dates,
132       particularly if 4-digit years are used. But it also means that the
133       behavior of your code changes as time passes, because the rolling
134       "current century" changes each year.
135
136   Limits of time_t
137       On perl versions older than 5.12.0, the range of dates that can be
138       actually be handled depends on the size of "time_t" (usually a signed
139       integer) on the given platform. Currently, this is 32 bits for most
140       systems, yielding an approximate range from Dec 1901 to Jan 2038.
141
142       Both "timelocal()" and "timegm()" croak if given dates outside the
143       supported range.
144
145       As of version 5.12.0, perl has stopped using the time implementation of
146       the operating system it's running on. Instead, it has its own
147       implementation of those routines with a safe range of at least +/-
148       2**52 (about 142 million years)
149
150   Ambiguous Local Times (DST)
151       Because of DST changes, there are many time zones where the same local
152       time occurs for two different GMT times on the same day. For example,
153       in the "Europe/Paris" time zone, the local time of 2001-10-28 02:30:00
154       can represent either 2001-10-28 00:30:00 GMT, or 2001-10-28 01:30:00
155       GMT.
156
157       When given an ambiguous local time, the timelocal() function will
158       always return the epoch for the earlier of the two possible GMT times.
159
160   Non-Existent Local Times (DST)
161       When a DST change causes a locale clock to skip one hour forward, there
162       will be an hour's worth of local times that don't exist. Again, for the
163       "Europe/Paris" time zone, the local clock jumped from 2001-03-25
164       01:59:59 to 2001-03-25 03:00:00.
165
166       If the "timelocal()" function is given a non-existent local time, it
167       will simply return an epoch value for the time one hour later.
168
169   Negative Epoch Values
170       On perl version 5.12.0 and newer, negative epoch values are fully
171       supported.
172
173       On older versions of perl, negative epoch ("time_t") values, which are
174       not officially supported by the POSIX standards, are known not to work
175       on some systems. These include MacOS (pre-OSX) and Win32.
176
177       On systems which do support negative epoch values, this module should
178       be able to cope with dates before the start of the epoch, down the
179       minimum value of time_t for the system.
180

IMPLEMENTATION

182       These routines are quite efficient and yet are always guaranteed to
183       agree with "localtime()" and "gmtime()". We manage this by caching the
184       start times of any months we've seen before. If we know the start time
185       of the month, we can always calculate any time within the month.  The
186       start times are calculated using a mathematical formula. Unlike other
187       algorithms that do multiple calls to "gmtime()".
188
189       The "timelocal()" function is implemented using the same cache. We just
190       assume that we're translating a GMT time, and then fudge it when we're
191       done for the timezone and daylight savings arguments. Note that the
192       timezone is evaluated for each date because countries occasionally
193       change their official timezones. Assuming that "localtime()" corrects
194       for these changes, this routine will also be correct.
195

AUTHORS EMERITUS

197       This module is based on a Perl 4 library, timelocal.pl, that was
198       included with Perl 4.036, and was most likely written by Tom
199       Christiansen.
200
201       The current version was written by Graham Barr.
202

BUGS

204       The whole scheme for interpreting two-digit years can be considered a
205       bug.
206
207       Bugs may be submitted at
208       <https://github.com/houseabsolute/Time-Local/issues>.
209
210       There is a mailing list available for users of this distribution,
211       <mailto:datetime@perl.org>.
212
213       I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
214

SOURCE

216       The source code repository for Time-Local can be found at
217       <https://github.com/houseabsolute/Time-Local>.
218

AUTHOR

220       Dave Rolsky <autarch@urth.org>
221

CONTRIBUTORS

223       •   Florian Ragwitz <rafl@debian.org>
224
225       •   J. Nick Koston <nick@cpanel.net>
226
227       •   Unknown <unknown@example.com>
228
230       This software is copyright (c) 1997 - 2020 by Graham Barr & Dave
231       Rolsky.
232
233       This is free software; you can redistribute it and/or modify it under
234       the same terms as the Perl 5 programming language system itself.
235
236       The full text of the license can be found in the LICENSE file included
237       with this distribution.
238
239
240
241perl v5.34.0                      2021-07-23                    Time::Local(3)
Impressum