/ 
Tie-TZ-9
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 tzset() (see POSIX) 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'} and 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 -- 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.

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. Of course setting the environment variable might or might not affect the timezone in force (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. Here are some cases where you do need it,

  • Using Perl-level localtime in threaded Perl 5.8.8 (whether using threads or not). Normally Perl arranges to call tzset if the C library doesn't (based on a configure test, see Config). But in 5.8.8 and earlier Perl didn't do that on localtime_r, and in some versions of GNU C that function needed an explicit tzset.

  • Using localtime from C code on older systems which don't check for a new TZ each time. Even if Perl's configure test does the right thing for Perl level calls you may not be so lucky deep in external libraries.

  • When using the global variables timezone, daylight and tzname, either from C code or from the POSIX module tzname function.

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 (there's only $TZ at the moment)

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

OTHER NOTES

The Env module can make a tied $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'}, eg. 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 (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, "Time and Date" in perlport, DateTime::TimeZone

HOME PAGE

http://user42.tuxfamily.org/tie-tz/index.html

COPYRIGHT

Copyright 2008, 2009, 2010, 2011 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/>.