Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Time::Local.3pm

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