MirOS Manual: Time::Local(3p)


Time::Local(3p) Perl Programmers Reference Guide  Time::Local(3p)

NAME

     Time::Local - efficiently compute time from local and GMT
     time

SYNOPSIS

         $time = timelocal($sec,$min,$hour,$mday,$mon,$year);
         $time = timegm($sec,$min,$hour,$mday,$mon,$year);

DESCRIPTION

     These routines are the inverse of built-in perl functions
     localtime() and gmtime().  They accept a date as a six-
     element array, and return the corresponding time(2) 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.

     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 (ie 1..31), while the month is
     the number of months since January (0..11). This is con-
     sistent with the values returned from localtime() and
     gmtime().

     The timelocal() and timegm() functions perform range check-
     ing on the input $sec, $min, $hour, $mday, and $mon values
     by default.  If you'd rather they didn't, you can explicitly
     import the timelocal_nocheck() and timegm_nocheck() func-
     tions.

             use Time::Local 'timelocal_nocheck';

             {
                 # The 365th day of 1999
                 print scalar localtime timelocal_nocheck 0,0,0,365,0,99;

                 # The twenty thousandth day since 1970
                 print scalar localtime timelocal_nocheck 0,0,0,20000,0,70;

                 # And even the 10,000,000th second since 1999!
                 print scalar localtime timelocal_nocheck 10000000,0,0,1,0,99;
             }

     Your mileage may vary when trying these with minutes and
     hours, and it doesn't work at all for months.

     Strictly speaking, the year should also be specified in a
     form consistent with localtime(), 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

perl v5.8.8                2005-02-05                           1

Time::Local(3p) Perl Programmers Reference Guide  Time::Local(3p)

     are followed:

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

     +   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).

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

     The scheme above allows interpretation of a wide range of
     dates, particularly if 4-digit years are used.

     Please note, however, that the range of dates that can be
     actually be handled depends on the size of an integer
     (time_t) on a given platform. Currently, this is 32 bits for
     most systems, yielding an approximate range from Dec 1901 to
     Jan 2038.

     Both timelocal() and timegm() croak if given dates outside
     the supported range.

     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, or 2001-10-28 01:30:00 GMT.

     When given an ambiguous local time, the timelocal() function
     should always return the epoch for the earlier of the two
     possible GMT times.

     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

perl v5.8.8                2005-02-05                           2

Time::Local(3p) Perl Programmers Reference Guide  Time::Local(3p)

     03:00:00.

     If the timelocal() function is given a non-existent local
     time, it will simply return an epoch value for the time one
     hour later.

     Negative Epoch Values

     Negative epoch (time_t) values are not officially supported
     by the POSIX standards, so this module's tests do not test
     them.  On some systems, they are known not to work.  These
     include MacOS (pre-OSX) and Win32.

     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.

IMPLEMENTATION

     These routines are quite efficient and yet are always
     guaranteed to agree with localtime() and gmtime().  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 gmtime().

     timelocal() 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 argu-
     ments.  Note that the timezone is evaluated for each date
     because countries occasionally change their official
     timezones. Assuming that localtime() corrects for these
     changes, this routine will also be correct.

BUGS

     The whole scheme for interpreting two-digit years can be
     considered a bug.

SUPPORT

     Support for this module is provided via the
     datetime@perl.org email list.  See http://lists.perl.org/
     for more details.

     Please submit bugs using the RT system at rt.cpan.org, or as
     a last resort, to the datetime@perl.org list.

AUTHOR

     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.

perl v5.8.8                2005-02-05                           3

Time::Local(3p) Perl Programmers Reference Guide  Time::Local(3p)

     The current version was written by Graham Barr.

     It is now being maintained separately from the Perl core by
     Dave Rolsky, <autarch@urth.org>.

perl v5.8.8                2005-02-05                           4

Generated on 2014-07-04 21:17:45 by $MirOS: src/scripts/roff2htm,v 1.79 2014/02/10 00:36:11 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002‒2014 The MirOS Project, Germany.
This product includes material provided by Thorsten Glaser.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.