DateTime::TimeZone - Time zone object base class and factory


DateTime::TimeZone - Time zone object base class and factory


  use DateTime;
  use DateTime::TimeZone
  my $tz = DateTime::TimeZone->new( name => 'America/Chicago' );
  my $dt = DateTime->now();
  my $offset = $tz->offset_for_datetime($dt);


This class is the base class for all time zone objects. A time zone is represented internally as a set of observances, each of which describes the offset from GMT for a given time period.

Note that without the module, this module does not do much. It's primary interface is through a DateTime object, and most users will not need to directly use DateTime::TimeZone methods.


This class has the following methods:

The ``local'' time zone

If the ``name'' parameter is ``local'', then the module attempts to determine the local time zone for the system.

First it checks $ENV for keys named ``TZ'', ``SYS$TIMEZONE_RULE'', ``SYS$TIMEZONE_NAME'', ``UCX$TZ'', or ``TCPIP$TZC'' (the last 4 are for VMS). If this is defined, and it is not the string ``local'', then it is treated as any other valid name (including ``floating''), and the constructor tries to create a time zone based on that name.

Next, it checks for the existence of a symlink at /etc/localtime. It follows this link to the real file and figures out what the file's name is. It then tries to turn this name into a valid time zone. For example, if this file is linked to /usr/share/zoneinfo/US/Central, it will end up trying ``US/Central'', which will then be converted to ``America/Chicago'' internally.

Some systems just copy the relevant file to /etc/localtime instead of making a symlink. In this case, we look in /usr/share/zoneinfo for a file that has the same size and content as /etc/localtime to determine the local time zone.

Then it checks for a file called /etc/timezone or /etc/TIMEZONE. If one of these exists, it is read and it tries to create a time zone with the name contained in the file.

Finally, it checks for a file called /etc/sysconfig/clock. If this file exists, it looks for a line inside the file matching /^(?:TIME)?ZONE="([^"]+)"/. If this line exists, it tries the value as a time zone name.

If none of these methods work, it gives up and dies.

Object Methods

DateTime::TimeZone objects provide the following methods:

Class Methods

This class provides one class method:

Storable Hooks

This module provides freeze and thaw hooks for Storable so that the huge data structures for Olson time zones are not actually stored in the serialized structure.

If you subclass DateTime::TimeZone, you will inherit its hooks, which may not work for your module, so please test the interaction of your module with Storable.


This class also contains several functions, none of which are exported. Calling these as class methods will also work.


Support for this module is provided via the email list. See for more details.

Please submit bugs to the CPAN RT system at or via email at


Dave Rolsky <>


This module was inspired by Jesse Vincent's work on Date::ICal::Timezone, and written with much help from the list.


Copyright (c) 2003 David Rolsky. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO mailing list

The tools directory of the DateTime::TimeZone distribution includes two scripts that may be of interest to some people. They are parse_olson and tests_from_zdump. Please run them with the --help flag to see what they can be used for.

 DateTime::TimeZone - Time zone object base class and factory