Debian Codegraph @

upstream/debian-unstable/man3/Time::Local.3perl

raw
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.