Time::Zone::Olsen - Provides an interface to the Olsen timezone database
Version 0.01
use Time::Zone::Olsen(); my $time_zone = Time::Zone::Olsen->new({ timezone => 'Australia/Melbourne' }); # set timezone at creation time my $now = $time_zone->time_local($seconds, $minutes, $hours, $day, $month, $year); # convert from Australia/Melbourne time foreach my $area (Time::Zone::Olsen->areas()) { foreach my $location (Time::Zone::Olsen->locations($area)) { $time_zone->timezone("$area/$location"); print scalar $time_zone->local_time($now); # output time in $area/$location local time warn scalar localtime($now) . " log message for sysadmin"; # but log in system local time } }
Time::Zone::Olsen is intended to provide a simple but well tested interface to the Olsen database that is available on most UNIX systems. It provides an interface to list common time zones, such as Australia/Melbourne that are stored in the zone.tab file, and localtime/Time::Local::timelocal replacements to translate times to and from the users timezone, without changing the timezone used by Perl. This allows logging/etc to be conducted in the system's local time.
Time::Zone::Olsen was designed to produce the same result as a 64bit copy of the date(1) command.
Time::Zone::Olsen->new() will return a new timezone object. It accepts a hash reference as a parameter with an optional timezone key, which contains an Olsen timezone value, such as 'Australia/Melbourne'. The hash reference also allows a directory key, with the file system location of the Olsen timezone database as a value.
timezone
directory
Both of these parameters default to $ENV{TZ} and $ENV{TZDIR} respectively.
$ENV{TZ}
$ENV{TZDIR}
Time::Zone::Olsen->areas() will return a list of the areas (such as Asia, Australia, Africa, America, Europe) from the zone.tab file. The areas will be sorted alphabetically.
Time::Zone::Olsen->locations($area) will return a list of the locations (such as Melbourne, Perth, Hobart) for a specified area from the zone.tab file. The locations will be sorted alphabetically.
Time::Zone::Olsen->comment($timezone) will return the matching comment from the zone.tab file for the timezone parameter. For example, if "Australia/Melbourne" was passed as a parameter, the "comment" function would return "Victoria"
"Australia/Melbourne"
"Victoria"
This object method can be used to get or set the root directory of the Olsen database, usually located at /usr/share/zoneinfo.
This object method can be used to get or set the timezone, which will affect all future calls to "local_time" or "time_local". The parameter for this method should be in the Olsen format of a timezone, such as "Australia/Melbourne".
This object method has the same signature as the 64 bit version of the localtime function. That is, it accepts up to a 64 bit signed integer as the sole argument and returns the (seconds, minutes, hours, day, month, year, wday, yday, isdst) definition for the timezone for the object. The timezone used to calculate the local_time may be specified as a parameter to the "new" method or via the "timezone" method.
localtime
(seconds, minutes, hours, day, month, year, wday, yday, isdst)
This object method has the same signature as the 64 bit version of the Time::Local::timelocal function. That is, it accepts (seconds, minutes, hours, day, month, year, wday, yday, isdst) as parameters in a list and returns the correct UNIX time in seconds according to the current timezone for the object. The timezone used to calculate the local_time may be specified as a parameter to the "new" method or via the "timezone" method. It may not return the same values as Time::Local::timelocal though, especially during timezone changes.
Time::Local::timelocal
This object method can be used to get the list of transition times for the current timezone. This method is only intended for testing the results of Time::Zone::Olsen.
This object method can be used to get the list of leap seconds for the current timezone. This method is only intended for testing the results of Time::Zone::Olsen.
%s is not a TZ file
The designated path did not have the TZif prefix at the start of the file. Maybe either the directory or the timezone name is incorrect?
TZif
Failed to read header from %s:%s
The designated file encountered an error reading either the V1 or V2 headers
Failed to read entire header from %s. %d bytes were read instead of the expected %d
The designated file is shorter than expected
%s is not an timezone in the existing Olsen database
The designated timezone could not be found on the file system. The timezone is expected to be in the designated directory + the timezone name, for example, /usr/share/zoneinfo/Australia/Melbourne
%s does not have a valid format for a TZ timezone
The designated timezone name could not be matched by the regular expression for a timezone in Time::Zone::Olsen
Failed to close %s:%s
There has been a file system error while reading or closing the designated path
Failed to open %s for reading:%s
There has been a file system error while opening the the designated path. This could be permissions related, or the timezone in question doesn't exist?
Failed to read %s from %s:%s
There has been a file system error while reading from the designated path. The file could be corrupt?
Failed to read all the %s from %s. %d bytes were read instead of the expected %d
The designated file is shorter than expected. The file could be corrupt?
The tz defintion at the end of %s could not be read in %d bytes
The designated file is longer than expected. Maybe the timezone version is greater than the currently recognized 3?
Failed to read tz definition from %s:%
Failed to parse the tz defintion of %s from %s
This is probably a bug in Time::Zone::Olsen in failing to parse the TZ variable at the end of the file.
TZ
Time::Zone::Olsen requires no configuration files or environment variables. However, it will use the values of $ENV{TZ} and $ENV{TZDIR} as defaults for missing parameters.
Time::Zone::Olsen requires Perl 5.10 or better. For environments where the unpack 'q' parameter is not supported, the following module is also required
Math::Int64
None reported
Please report any bugs or feature requests to bug-time-zone-olsen at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Time-Zone-Olsen. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-time-zone-olsen at rt.cpan.org
David Dick, <ddick at cpan.org>
<ddick at cpan.org>
Copyright 2015 David Dick.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.
To install Time::Zone::Olsen, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Time::Zone::Olsen
CPAN shell
perl -MCPAN -e shell install Time::Zone::Olsen
For more information on module installation, please visit the detailed CPAN module installation guide.