Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 290 insertions, 0 deletions

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 <https://github.com/houseabsolute/Time\-Local/issues>.
+.PP
+There is a mailing list available for users of this distribution,
+<mailto:datetime@perl.org>.
+.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 <https://github.com/houseabsolute/Time\-Local>.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Dave Rolsky <autarch@urth.org>
+.SH CONTRIBUTORS
+.IX Header "CONTRIBUTORS"
+.IP \(bu 4
+Florian Ragwitz <rafl@debian.org>
+.IP \(bu 4
+J. Nick Koston <nick@cpanel.net>
+.IP \(bu 4
+Unknown <unknown@example.com>
+.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.