VERSION Version 0.01 SYNOPSIS use Time::Zone::Olson(); my $time_zone = Time::Zone::Olson->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::Olson->areas()) { foreach my $location (Time::Zone::Olson->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 } } DESCRIPTION Time::Zone::Olson is intended to provide a simple but well tested interface to the Olson 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::Olson was designed to produce the same result as a 64bit copy of the date(1) command. SUBROUTINES/METHODS new Time::Zone::Olson->new() will return a new timezone object. It accepts a hash reference as a parameter with an optional `timezone' key, which contains an Olson timezone value, such as 'Australia/Melbourne'. The hash reference also allows a `directory' key, with the file system location of the Olson timezone database as a value. Both of these parameters default to `$ENV{TZ}' and `$ENV{TZDIR}' respectively. areas Time::Zone::Olson->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. locations Time::Zone::Olson->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. comment Time::Zone::Olson->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"' directory This object method can be used to get or set the root directory of the Olson database, usually located at /usr/share/zoneinfo. timezone 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 Olson format of a timezone, such as `"Australia/Melbourne"'. local_time 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. time_local 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. transition_times 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::Olson. leap_seconds 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::Olson. DIAGNOSTICS `%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? `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 Olson 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::Olson `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:%' There has been a file system error while reading from the designated path. The file could be corrupt? `Failed to parse the tz defintion of %s from %s' This is probably a bug in Time::Zone::Olson in failing to parse the `TZ' variable at the end of the file. CONFIGURATION AND ENVIRONMENT Time::Zone::Olson requires no configuration files or environment variables. However, it will use the values of `$ENV{TZ}' and `$ENV{TZDIR}' as defaults for missing parameters. DEPENDENCIES Time::Zone::Olson requires Perl 5.10 or better. For environments where the unpack 'q' parameter is not supported, the following module is also required * Math::Int64 INCOMPATIBILITIES None reported BUGS AND LIMITATIONS Please report any bugs or feature requests to `bug-time-zone-olson at rt.cpan.org', or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Time-Zone-Olson. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. SEE ALSO * DateTime::TimeZone * DateTime::TimeZone::Tzfile AUTHOR David Dick, `' LICENSE AND COPYRIGHT 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.