From fc22b3d6507c6745911b9dfcc68f1e665ae13dbc Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:43:11 +0200 Subject: Adding upstream version 4.22.0. Signed-off-by: Daniel Baumann --- upstream/debian-unstable/man3/Time::Local.3perl | 290 ++++++++++++++++++++++++ 1 file changed, 290 insertions(+) create mode 100644 upstream/debian-unstable/man3/Time::Local.3perl (limited to 'upstream/debian-unstable/man3/Time::Local.3perl') diff --git a/upstream/debian-unstable/man3/Time::Local.3perl b/upstream/debian-unstable/man3/Time::Local.3perl new file mode 100644 index 00000000..3c92f7e8 --- /dev/null +++ b/upstream/debian-unstable/man3/Time::Local.3perl @@ -0,0 +1,290 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "Time::Local 3perl" +.TH Time::Local 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +Time::Local \- Efficiently compute time from local and GMT time +.SH VERSION +.IX Header "VERSION" +version 1.30 +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& use Time::Local qw( timelocal_posix timegm_posix ); +\& +\& my $time = timelocal_posix( $sec, $min, $hour, $mday, $mon, $year ); +\& my $time = timegm_posix( $sec, $min, $hour, $mday, $mon, $year ); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This module provides functions that are the inverse of built-in perl functions +\&\f(CWlocaltime()\fR and \f(CWgmtime()\fR. They accept a date as a six-element array, and +return the corresponding \f(CWtime(2)\fR value in seconds since the system epoch +(Midnight, January 1, 1970 GMT on Unix, for example). This value can be +positive or negative, though POSIX only requires support for positive values, +so dates before the system's epoch may not work on all operating systems. +.PP +It is worth drawing particular attention to the expected ranges for the values +provided. The value for the day of the month is the actual day (i.e. 1..31), +while the month is the number of months since January (0..11). This is +consistent with the values returned from \f(CWlocaltime()\fR and \f(CWgmtime()\fR. +.SH FUNCTIONS +.IX Header "FUNCTIONS" +.ie n .SS "timelocal_posix() and timegm_posix()" +.el .SS "\f(CWtimelocal_posix()\fP and \f(CWtimegm_posix()\fP" +.IX Subsection "timelocal_posix() and timegm_posix()" +These functions are the exact inverse of Perl's built-in \f(CW\*(C`localtime\*(C'\fR and +\&\f(CW\*(C`gmtime\*(C'\fR functions. That means that calling \f(CW\*(C`timelocal_posix( +localtime($value) )\*(C'\fR will always give you the same \f(CW$value\fR you started +with. The same applies to \f(CW\*(C`timegm_posix( gmtime($value) )\*(C'\fR. +.PP +The one exception is when the value returned from \f(CWlocaltime()\fR represents an +ambiguous local time because of a DST change. See the documentation below for +more details. +.PP +These functions expect the year value to be the number of years since 1900, +which is what the \f(CWlocaltime()\fR and \f(CWgmtime()\fR built-ins returns. +.PP +They perform range checking by default on the input \f(CW$sec\fR, \f(CW$min\fR, +\&\f(CW$hour\fR, \f(CW$mday\fR, and \f(CW$mon\fR values and will croak (using \f(CWCarp::croak()\fR) +if given a value outside the allowed ranges. +.PP +While it would be nice to make this the default behavior, that would almost +certainly break a lot of code, so you must explicitly import these functions +and use them instead of the default \f(CWtimelocal()\fR and \f(CWtimegm()\fR. +.PP +You are \fBstrongly\fR encouraged to use these functions in any new code which +uses this module. It will almost certainly make your code's behavior less +surprising. +.ie n .SS "timelocal_modern() and timegm_modern()" +.el .SS "\f(CWtimelocal_modern()\fP and \f(CWtimegm_modern()\fP" +.IX Subsection "timelocal_modern() and timegm_modern()" +When \f(CW\*(C`Time::Local\*(C'\fR was first written, it was a common practice to represent +years as a two-digit value like \f(CW99\fR for \f(CW1999\fR or \f(CW1\fR for \f(CW2001\fR. This +caused all sorts of problems (google "Y2K problem" if you're very young) and +developers eventually realized that this was a terrible idea. +.PP +The default exports of \f(CWtimelocal()\fR and \f(CWtimegm()\fR do a complicated +calculation when given a year value less than 1000. This leads to surprising +results in many cases. See "Year Value Interpretation" for details. +.PP +The \f(CW\*(C`time*_modern()\*(C'\fR functions do not do this year munging and simply take +the year value as provided. +.PP +They perform range checking by default on the input \f(CW$sec\fR, \f(CW$min\fR, +\&\f(CW$hour\fR, \f(CW$mday\fR, and \f(CW$mon\fR values and will croak (using \f(CWCarp::croak()\fR) +if given a value outside the allowed ranges. +.ie n .SS "timelocal() and timegm()" +.el .SS "\f(CWtimelocal()\fP and \f(CWtimegm()\fP" +.IX Subsection "timelocal() and timegm()" +This module exports two functions by default, \f(CWtimelocal()\fR and \f(CWtimegm()\fR. +.PP +They perform range checking by default on the input \f(CW$sec\fR, \f(CW$min\fR, +\&\f(CW$hour\fR, \f(CW$mday\fR, and \f(CW$mon\fR values and will croak (using \f(CWCarp::croak()\fR) +if given a value outside the allowed ranges. +.PP +\&\fBWarning: The year value interpretation that these functions and their +nocheck variants use will almost certainly lead to bugs in your code, if not +now, then in the future. You are strongly discouraged from using these in new +code, and you should convert old code to using either the \fR\f(CB*_posix\fR\fB or +\&\fR\f(CB*_modern\fR\fB functions if possible.\fR +.ie n .SS "timelocal_nocheck() and timegm_nocheck()" +.el .SS "\f(CWtimelocal_nocheck()\fP and \f(CWtimegm_nocheck()\fP" +.IX Subsection "timelocal_nocheck() and timegm_nocheck()" +If you are working with data you know to be valid, you can use the "nocheck" +variants, \f(CWtimelocal_nocheck()\fR and \f(CWtimegm_nocheck()\fR. These variants must +be explicitly imported. +.PP +If you supply data which is not valid (month 27, second 1,000) the results +will be unpredictable (so don't do that). +.PP +Note that my benchmarks show that this is just a 3% speed increase over the +checked versions, so unless calling \f(CW\*(C`Time::Local\*(C'\fR is the hottest spot in your +application, using these nocheck variants is unlikely to have much impact on +your application. +.SS "Year Value Interpretation" +.IX Subsection "Year Value Interpretation" +\&\fBThis does not apply to the \fR\f(CB*_posix\fR\fB or \fR\f(CB*_modern\fR\fB functions. Use those +exports if you want to ensure consistent behavior as your code ages.\fR +.PP +Strictly speaking, the year should be specified in a form consistent with +\&\f(CWlocaltime()\fR, i.e. the offset from 1900. In order to make the interpretation +of the year easier for humans, however, who are more accustomed to seeing +years as two-digit or four-digit values, the following conventions are +followed: +.IP \(bu 4 +Years greater than 999 are interpreted as being the actual year, rather than +the offset from 1900. Thus, 1964 would indicate the year Martin Luther King +won the Nobel prize, not the year 3864. +.IP \(bu 4 +Years in the range 100..999 are interpreted as offset from 1900, so that 112 +indicates 2012. This rule also applies to years less than zero (but see note +below regarding date range). +.IP \(bu 4 +Years in the range 0..99 are interpreted as shorthand for years in the rolling +"current century," defined as 50 years on either side of the current +year. Thus, today, in 1999, 0 would refer to 2000, and 45 to 2045, but 55 +would refer to 1955. Twenty years from now, 55 would instead refer to +2055. This is messy, but matches the way people currently think about two +digit dates. Whenever possible, use an absolute four digit year instead. +.PP +The scheme above allows interpretation of a wide range of dates, particularly +if 4\-digit years are used. But it also means that the behavior of your code +changes as time passes, because the rolling "current century" changes each +year. +.SS "Limits of time_t" +.IX Subsection "Limits of time_t" +On perl versions older than 5.12.0, the range of dates that can be actually be +handled depends on the size of \f(CW\*(C`time_t\*(C'\fR (usually a signed integer) on the +given platform. Currently, this is 32 bits for most systems, yielding an +approximate range from Dec 1901 to Jan 2038. +.PP +Both \f(CWtimelocal()\fR and \f(CWtimegm()\fR croak if given dates outside the supported +range. +.PP +As of version 5.12.0, perl has stopped using the time implementation of the +operating system it's running on. Instead, it has its own implementation of +those routines with a safe range of at least +/\- 2**52 (about 142 million +years) +.SS "Ambiguous Local Times (DST)" +.IX Subsection "Ambiguous Local Times (DST)" +Because of DST changes, there are many time zones where the same local time +occurs for two different GMT times on the same day. For example, in the +"Europe/Paris" time zone, the local time of 2001\-10\-28 02:30:00 can represent +either 2001\-10\-28 00:30:00 GMT, \fBor\fR 2001\-10\-28 01:30:00 GMT. +.PP +When given an ambiguous local time, the \fBtimelocal()\fR function will always +return the epoch for the \fIearlier\fR of the two possible GMT times. +.SS "Non-Existent Local Times (DST)" +.IX Subsection "Non-Existent Local Times (DST)" +When a DST change causes a locale clock to skip one hour forward, there will +be an hour's worth of local times that don't exist. Again, for the +"Europe/Paris" time zone, the local clock jumped from 2001\-03\-25 01:59:59 to +2001\-03\-25 03:00:00. +.PP +If the \f(CWtimelocal()\fR function is given a non-existent local time, it will +simply return an epoch value for the time one hour later. +.SS "Negative Epoch Values" +.IX Subsection "Negative Epoch Values" +On perl version 5.12.0 and newer, negative epoch values are fully supported. +.PP +On older versions of perl, negative epoch (\f(CW\*(C`time_t\*(C'\fR) values, which are not +officially supported by the POSIX standards, are known not to work on some +systems. These include MacOS (pre-OSX) and Win32. +.PP +On systems which do support negative epoch values, this module should be able +to cope with dates before the start of the epoch, down the minimum value of +time_t for the system. +.SH IMPLEMENTATION +.IX Header "IMPLEMENTATION" +These routines are quite efficient and yet are always guaranteed to agree with +\&\f(CWlocaltime()\fR and \f(CWgmtime()\fR. We manage this by caching the start times of +any months we've seen before. If we know the start time of the month, we can +always calculate any time within the month. The start times are calculated +using a mathematical formula. Unlike other algorithms that do multiple calls +to \f(CWgmtime()\fR. +.PP +The \f(CWtimelocal()\fR function is implemented using the same cache. We just +assume that we're translating a GMT time, and then fudge it when we're done +for the timezone and daylight savings arguments. Note that the timezone is +evaluated for each date because countries occasionally change their official +timezones. Assuming that \f(CWlocaltime()\fR corrects for these changes, this +routine will also be correct. +.SH "AUTHORS EMERITUS" +.IX Header "AUTHORS EMERITUS" +This module is based on a Perl 4 library, timelocal.pl, that was +included with Perl 4.036, and was most likely written by Tom +Christiansen. +.PP +The current version was written by Graham Barr. +.SH BUGS +.IX Header "BUGS" +The whole scheme for interpreting two-digit years can be considered a bug. +.PP +Bugs may be submitted at . +.PP +There is a mailing list available for users of this distribution, +. +.PP +I am also usually active on IRC as 'autarch' on \f(CW\*(C`irc://irc.perl.org\*(C'\fR. +.SH SOURCE +.IX Header "SOURCE" +The source code repository for Time-Local can be found at . +.SH AUTHOR +.IX Header "AUTHOR" +Dave Rolsky +.SH CONTRIBUTORS +.IX Header "CONTRIBUTORS" +.IP \(bu 4 +Florian Ragwitz +.IP \(bu 4 +J. Nick Koston +.IP \(bu 4 +Unknown +.SH "COPYRIGHT AND LICENSE" +.IX Header "COPYRIGHT AND LICENSE" +This software is copyright (c) 1997 \- 2020 by Graham Barr & Dave Rolsky. +.PP +This is free software; you can redistribute it and/or modify it under +the same terms as the Perl 5 programming language system itself. +.PP +The full text of the license can be found in the +\&\fILICENSE\fR file included with this distribution. -- cgit v1.2.3