/ 
Tie-TZ-4
River stage one • 2 direct dependents • 2 total dependents
/ Tie::TZ

NAME

Tie::TZ - tied $TZ setting %ENV and calling tzset()

SYNOPSIS

use Tie::TZ qw($TZ);
$TZ = 'GMT';
{
  local $TZ = 'EST+10';
  ...
}

DESCRIPTION

Tie::TZ provides a tied $TZ variable which gets and sets the TZ environment variable $ENV{'TZ'}. When it changes %ENV it calls POSIX::tzset() (if available) ensuring the C library notices the change for subsequent localtime etc.

$TZ = 'GMT';
# does  $ENV{'TZ'}='GMT'; POSIX::tzset();

For a plain set you can just as easily store and tzset yourself (or have a function do the combo). The power of a tied variable comes when using local to have a different timezone temporarily. Any goto, return, die, etc, exiting the block will restore the old setting, including a tzset for it.

{ local $TZ = 'GMT';
  print ctime();
  # TZ restored at block exit
}

{ local $TZ = 'GMT';
  die 'Something';
  # TZ restored when the die unwinds
}

Storing undef to $TZ deletes $ENV{'TZ'}, which unsets the environment variable. This generally means the timezone goes back to the system default (/etc/timezone or wherever).

As an optimization, if a store to $TZ is already what $ENV{'TZ'} contains then POSIX::tzset() is not called. This is helpful if some of the settings you're using might be the same, you can just store to $TZ and it notices when there's no change. If you never store anything different from the startup value then the POSIX module is not even loaded at all.

If tzset is not implemented on your system then Tie::TZ just sets the environment variable. This is only likely on a very old or very limited C library. Setting the environment variable alone might still affect the timezone in force or it might not (see "Time and Date" in perlport).

Uses

Quite often tzset is not actually needed. Decent C libraries look for a new TZ each time in the various localtime etc functions. But tzset keeps you out of trouble on older systems, or with any external libraries directly accessing the C global variables timezone, daylight and tzname.

Perl's own calls to localtime etc do a tzset themselves where necessary to cope with old C libraries (based on a configure test, see Config). However in 5.8.8 and earlier Perl didn't do that on localtime_r, and the latter in some versions of GNU C needed an explicit tzset; the net result being that you should tzset in threaded Perl 5.8.8 (whether using threads or not). Of course even when Perl recognises C library limitations you may not be so lucky deep in external libraries.

EXPORTS

By default nothing is exported and you can use the full name $Tie::TZ::TZ,

use Tie::TZ;
$Tie::TZ::TZ = 'GMT';

Import $TZ in the usual way (see Exporter) as a shorthand, either by name

use Tie::TZ '$TZ';
$TZ = 'GMT';

or ":all" imports everything (not that there's anything except $TZ at the moment)

use Tie::TZ ':all';
$TZ = 'GMT';

OTHER NOTES

The Env module can tie a $TZ in a similar way if you're confident you don't need tzset. The local trick above works equally well with Env. You can also apply local directly to $ENV{'TZ'}, like local $ENV{'TZ'} = 'EST+10', except you can't unset that way. (Attempting to store undef provokes a warning before Perl 5.10 and comes out as the empty string, which might be subtly different to unset.)

When you get sick of the C library timezone handling have a look at DateTime::TimeZone. Its copy of the Olson timezone database makes it big (though no doubt you could turf what you don't use) but it's all Perl and is much friendlier for calculations in multiple zones.

SEE ALSO

POSIX, Env, DateTime::TimeZone, "Time and Date" in perlport

HOME PAGE

http://www.geocities.com/user42_kevin/tie-tz/index.html

COPYRIGHT

Copyright 2008, 2009 Kevin Ryde

Tie-TZ is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Tie-TZ is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Tie-TZ. If not, see http://www.gnu.org/licenses.