| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "Time::Local 3perl" |
| 58 |
.TH Time::Local 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
Time::Local \- Efficiently compute time from local and GMT time |
| 65 |
.SH VERSION |
| 66 |
.IX Header "VERSION" |
| 67 |
version 1.35 |
| 68 |
.SH SYNOPSIS |
| 69 |
.IX Header "SYNOPSIS" |
| 70 |
.Vb 1 |
| 71 |
\& use Time::Local qw( timelocal_posix timegm_posix ); |
| 72 |
\& |
| 73 |
\& my $time = timelocal_posix( $sec, $min, $hour, $mday, $mon, $year ); |
| 74 |
\& my $time = timegm_posix( $sec, $min, $hour, $mday, $mon, $year ); |
| 75 |
.Ve |
| 76 |
.SH DESCRIPTION |
| 77 |
.IX Header "DESCRIPTION" |
| 78 |
This module provides functions that are the inverse of built-in perl functions |
| 79 |
\&\f(CWlocaltime()\fR and \f(CWgmtime()\fR. They accept a date as a six-element array, and |
| 80 |
return the corresponding \f(CWtime(2)\fR value in seconds since the system epoch |
| 81 |
(Midnight, January 1, 1970 GMT on Unix, for example). This value can be |
| 82 |
positive or negative, though POSIX only requires support for positive values, |
| 83 |
so dates before the system's epoch may not work on all operating systems. |
| 84 |
.PP |
| 85 |
It is worth drawing particular attention to the expected ranges for the values |
| 86 |
provided. The value for the day of the month is the actual day (i.e. 1..31), |
| 87 |
while the month is the number of months since January (0..11). This is |
| 88 |
consistent with the values returned from \f(CWlocaltime()\fR and \f(CWgmtime()\fR. |
| 89 |
.SH FUNCTIONS |
| 90 |
.IX Header "FUNCTIONS" |
| 91 |
.ie n .SS "timelocal_posix() and timegm_posix()" |
| 92 |
.el .SS "\f(CWtimelocal_posix()\fP and \f(CWtimegm_posix()\fP" |
| 93 |
.IX Subsection "timelocal_posix() and timegm_posix()" |
| 94 |
\&\fISince version 1.30.\fR |
| 95 |
.PP |
| 96 |
These functions are the exact inverse of Perl's built-in \f(CW\*(C`localtime\*(C'\fR and |
| 97 |
\&\f(CW\*(C`gmtime\*(C'\fR functions. That means that calling \f(CW\*(C`timelocal_posix( |
| 98 |
localtime($value) )\*(C'\fR will always give you the same \f(CW$value\fR you started |
| 99 |
with. The same applies to \f(CW\*(C`timegm_posix( gmtime($value) )\*(C'\fR. |
| 100 |
.PP |
| 101 |
The one exception is when the value returned from \f(CWlocaltime()\fR represents an |
| 102 |
ambiguous local time because of a DST change. See the documentation below for |
| 103 |
more details. |
| 104 |
.PP |
| 105 |
These functions expect the year value to be the number of years since 1900, |
| 106 |
which is what the \f(CWlocaltime()\fR and \f(CWgmtime()\fR built-ins returns. |
| 107 |
.PP |
| 108 |
They perform range checking by default on the input \f(CW$sec\fR, \f(CW$min\fR, \f(CW$hour\fR, |
| 109 |
\&\f(CW$mday\fR, and \f(CW$mon\fR values and will croak (using \f(CWCarp::croak()\fR) if given a |
| 110 |
value outside the allowed ranges. |
| 111 |
.PP |
| 112 |
While it would be nice to make this the default behavior, that would almost |
| 113 |
certainly break a lot of code, so you must explicitly import these functions |
| 114 |
and use them instead of the default \f(CWtimelocal()\fR and \f(CWtimegm()\fR. |
| 115 |
.PP |
| 116 |
You are \fBstrongly\fR encouraged to use these functions in any new code which |
| 117 |
uses this module. It will almost certainly make your code's behavior less |
| 118 |
surprising. |
| 119 |
.ie n .SS "timelocal_modern() and timegm_modern()" |
| 120 |
.el .SS "\f(CWtimelocal_modern()\fP and \f(CWtimegm_modern()\fP" |
| 121 |
.IX Subsection "timelocal_modern() and timegm_modern()" |
| 122 |
\&\fISince version 1.27.\fR |
| 123 |
.PP |
| 124 |
When \f(CW\*(C`Time::Local\*(C'\fR was first written, it was a common practice to represent |
| 125 |
years as a two-digit value like \f(CW99\fR for \f(CW1999\fR or \f(CW1\fR for \f(CW2001\fR. This |
| 126 |
caused all sorts of problems (google "Y2K problem" if you're very young) and |
| 127 |
developers eventually realized that this was a terrible idea. |
| 128 |
.PP |
| 129 |
The default exports of \f(CWtimelocal()\fR and \f(CWtimegm()\fR do a complicated |
| 130 |
calculation when given a year value less than 1000. This leads to surprising |
| 131 |
results in many cases. See "Year Value Interpretation" for details. |
| 132 |
.PP |
| 133 |
The \f(CW\*(C`time*_modern()\*(C'\fR functions do not do this year munging and simply take the |
| 134 |
year value as provided. |
| 135 |
.PP |
| 136 |
They perform range checking by default on the input \f(CW$sec\fR, \f(CW$min\fR, \f(CW$hour\fR, |
| 137 |
\&\f(CW$mday\fR, and \f(CW$mon\fR values and will croak (using \f(CWCarp::croak()\fR) if given a |
| 138 |
value outside the allowed ranges. |
| 139 |
.ie n .SS "timelocal() and timegm()" |
| 140 |
.el .SS "\f(CWtimelocal()\fP and \f(CWtimegm()\fP" |
| 141 |
.IX Subsection "timelocal() and timegm()" |
| 142 |
This module exports two functions by default, \f(CWtimelocal()\fR and \f(CWtimegm()\fR. |
| 143 |
.PP |
| 144 |
They perform range checking by default on the input \f(CW$sec\fR, \f(CW$min\fR, \f(CW$hour\fR, |
| 145 |
\&\f(CW$mday\fR, and \f(CW$mon\fR values and will croak (using \f(CWCarp::croak()\fR) if given a |
| 146 |
value outside the allowed ranges. |
| 147 |
.PP |
| 148 |
\&\fBWarning: The year value interpretation that these functions and their nocheck |
| 149 |
variants use will almost certainly lead to bugs in your code, if not now, then |
| 150 |
in the future. You are strongly discouraged from using these in new code, and |
| 151 |
you should convert old code to using either the \fR\f(CB*_posix\fR\fB or \fR\f(CB*_modern\fR\fB |
| 152 |
functions if possible.\fR |
| 153 |
.ie n .SS "timelocal_nocheck() and timegm_nocheck()" |
| 154 |
.el .SS "\f(CWtimelocal_nocheck()\fP and \f(CWtimegm_nocheck()\fP" |
| 155 |
.IX Subsection "timelocal_nocheck() and timegm_nocheck()" |
| 156 |
If you are working with data you know to be valid, you can use the "nocheck" |
| 157 |
variants, \f(CWtimelocal_nocheck()\fR and \f(CWtimegm_nocheck()\fR. These variants must |
| 158 |
be explicitly imported. |
| 159 |
.PP |
| 160 |
If you supply data which is not valid (month 27, second 1,000) the results will |
| 161 |
be unpredictable (so don't do that). |
| 162 |
.PP |
| 163 |
Note that my benchmarks show that this is just a 3% speed increase over the |
| 164 |
checked versions, so unless calling \f(CW\*(C`Time::Local\*(C'\fR is the hottest spot in your |
| 165 |
application, using these nocheck variants is unlikely to have much impact on |
| 166 |
your application. |
| 167 |
.SS "Year Value Interpretation" |
| 168 |
.IX Subsection "Year Value Interpretation" |
| 169 |
\&\fBThis does not apply to the \fR\f(CB*_posix\fR\fB or \fR\f(CB*_modern\fR\fB functions. Use those |
| 170 |
exports if you want to ensure consistent behavior as your code ages.\fR |
| 171 |
.PP |
| 172 |
Strictly speaking, the year should be specified in a form consistent with |
| 173 |
\&\f(CWlocaltime()\fR, i.e. the offset from 1900. In order to make the interpretation |
| 174 |
of the year easier for humans, however, who are more accustomed to seeing years |
| 175 |
as two-digit or four-digit values, the following conventions are followed: |
| 176 |
.IP \(bu 4 |
| 177 |
Years greater than 999 are interpreted as being the actual year, rather than |
| 178 |
the offset from 1900. Thus, 1964 would indicate the year Martin Luther King won |
| 179 |
the Nobel prize, not the year 3864. |
| 180 |
.IP \(bu 4 |
| 181 |
Years in the range 100..999 are interpreted as offset from 1900, so that 112 |
| 182 |
indicates 2012. This rule also applies to years less than zero (but see note |
| 183 |
below regarding date range). |
| 184 |
.IP \(bu 4 |
| 185 |
Years in the range 0..99 are interpreted as shorthand for years in the rolling |
| 186 |
"current century," defined as 50 years on either side of the current year. |
| 187 |
Thus, today, in 1999, 0 would refer to 2000, and 45 to 2045, but 55 would refer |
| 188 |
to 1955. Twenty years from now, 55 would instead refer to 2055. This is messy, |
| 189 |
but matches the way people currently think about two digit dates. Whenever |
| 190 |
possible, use an absolute four digit year instead. |
| 191 |
.PP |
| 192 |
The scheme above allows interpretation of a wide range of dates, particularly |
| 193 |
if 4\-digit years are used. But it also means that the behavior of your code |
| 194 |
changes as time passes, because the rolling "current century" changes each |
| 195 |
year. |
| 196 |
.SS "Limits of time_t" |
| 197 |
.IX Subsection "Limits of time_t" |
| 198 |
On perl versions older than 5.12.0, the range of dates that can be actually be |
| 199 |
handled depends on the size of \f(CW\*(C`time_t\*(C'\fR (usually a signed integer) on the |
| 200 |
given platform. Currently, this is 32 bits for most systems, yielding an |
| 201 |
approximate range from Dec 1901 to Jan 2038. |
| 202 |
.PP |
| 203 |
Both \f(CWtimelocal()\fR and \f(CWtimegm()\fR croak if given dates outside the supported |
| 204 |
range. |
| 205 |
.PP |
| 206 |
As of version 5.12.0, perl has stopped using the time implementation of the |
| 207 |
operating system it's running on. Instead, it has its own implementation of |
| 208 |
those routines with a safe range of at least +/\- 2**52 (about 142 million |
| 209 |
years) |
| 210 |
.SS "Ambiguous Local Times (DST)" |
| 211 |
.IX Subsection "Ambiguous Local Times (DST)" |
| 212 |
Because of DST changes, there are many time zones where the same local time |
| 213 |
occurs for two different GMT times on the same day. For example, in the |
| 214 |
"Europe/Paris" time zone, the local time of 2001\-10\-28 02:30:00 can represent |
| 215 |
either 2001\-10\-28 00:30:00 GMT, \fBor\fR 2001\-10\-28 01:30:00 GMT. |
| 216 |
.PP |
| 217 |
When given an ambiguous local time, the \fBtimelocal()\fR function will always return |
| 218 |
the epoch for the \fIearlier\fR of the two possible GMT times. |
| 219 |
.SS "Non-Existent Local Times (DST)" |
| 220 |
.IX Subsection "Non-Existent Local Times (DST)" |
| 221 |
When a DST change causes a locale clock to skip one hour forward, there will be |
| 222 |
an hour's worth of local times that don't exist. Again, for the "Europe/Paris" |
| 223 |
time zone, the local clock jumped from 2001\-03\-25 01:59:59 to 2001\-03\-25 |
| 224 |
03:00:00. |
| 225 |
.PP |
| 226 |
If the \f(CWtimelocal()\fR function is given a non-existent local time, it will |
| 227 |
simply return an epoch value for the time one hour later. |
| 228 |
.SS "Negative Epoch Values" |
| 229 |
.IX Subsection "Negative Epoch Values" |
| 230 |
On perl version 5.12.0 and newer, negative epoch values are fully supported. |
| 231 |
.PP |
| 232 |
On older versions of perl, negative epoch (\f(CW\*(C`time_t\*(C'\fR) values, which are not |
| 233 |
officially supported by the POSIX standards, are known not to work on some |
| 234 |
systems. These include MacOS (pre-OSX) and Win32. |
| 235 |
.PP |
| 236 |
On systems which do support negative epoch values, this module should be able |
| 237 |
to cope with dates before the start of the epoch, down the minimum value of |
| 238 |
time_t for the system. |
| 239 |
.SH IMPLEMENTATION |
| 240 |
.IX Header "IMPLEMENTATION" |
| 241 |
These routines are quite efficient and yet are always guaranteed to agree with |
| 242 |
\&\f(CWlocaltime()\fR and \f(CWgmtime()\fR. We manage this by caching the start times of |
| 243 |
any months we've seen before. If we know the start time of the month, we can |
| 244 |
always calculate any time within the month. The start times are calculated |
| 245 |
using a mathematical formula. Unlike other algorithms that do multiple calls to |
| 246 |
\&\f(CWgmtime()\fR. |
| 247 |
.PP |
| 248 |
The \f(CWtimelocal()\fR function is implemented using the same cache. We just assume |
| 249 |
that we're translating a GMT time, and then fudge it when we're done for the |
| 250 |
timezone and daylight savings arguments. Note that the timezone is evaluated |
| 251 |
for each date because countries occasionally change their official timezones. |
| 252 |
Assuming that \f(CWlocaltime()\fR corrects for these changes, this routine will also |
| 253 |
be correct. |
| 254 |
.SH "AUTHORS EMERITUS" |
| 255 |
.IX Header "AUTHORS EMERITUS" |
| 256 |
This module is based on a Perl 4 library, timelocal.pl, that was included with |
| 257 |
Perl 4.036, and was most likely written by Tom Christiansen. |
| 258 |
.PP |
| 259 |
The current version was written by Graham Barr. |
| 260 |
.SH BUGS |
| 261 |
.IX Header "BUGS" |
| 262 |
The whole scheme for interpreting two-digit years can be considered a bug. |
| 263 |
.PP |
| 264 |
Bugs may be submitted at <https://github.com/houseabsolute/Time\-Local/issues>. |
| 265 |
.PP |
| 266 |
There is a mailing list available for users of this distribution, |
| 267 |
<mailto:[email protected]>. |
| 268 |
.SH SOURCE |
| 269 |
.IX Header "SOURCE" |
| 270 |
The source code repository for Time-Local can be found at <https://github.com/houseabsolute/Time\-Local>. |
| 271 |
.SH AUTHOR |
| 272 |
.IX Header "AUTHOR" |
| 273 |
Dave Rolsky <[email protected]> |
| 274 |
.SH CONTRIBUTORS |
| 275 |
.IX Header "CONTRIBUTORS" |
| 276 |
.IP \(bu 4 |
| 277 |
Florian Ragwitz <[email protected]> |
| 278 |
.IP \(bu 4 |
| 279 |
Gregory Oschwald <[email protected]> |
| 280 |
.IP \(bu 4 |
| 281 |
J. Nick Koston <[email protected]> |
| 282 |
.IP \(bu 4 |
| 283 |
Tom Wyant <[email protected]> |
| 284 |
.IP \(bu 4 |
| 285 |
Unknown <[email protected]> |
| 286 |
.SH "COPYRIGHT AND LICENSE" |
| 287 |
.IX Header "COPYRIGHT AND LICENSE" |
| 288 |
This software is copyright (c) 1997 \- 2023 by Graham Barr & Dave Rolsky. |
| 289 |
.PP |
| 290 |
This is free software; you can redistribute it and/or modify it under |
| 291 |
the same terms as the Perl 5 programming language system itself. |
| 292 |
.PP |
| 293 |
The full text of the license can be found in the |
| 294 |
\&\fILICENSE\fR file included with this distribution. |