.TH TZ 5
.SH NAME
TZ \- Time zone environment variable
.SH SYNOPSIS
.nf
\fBTZ=\fIzone\fR[\fB\-\fR]\fIoffset\fR[\fIdst\fR[\fIoffset\fR][\fB,\fIstart\fR[\fB/\fItime\fR]\fB,\fIend\fR[\fB/\fItime\fR]]]
\fBTZ=\fR[\fB:\fR]\fIzoneinfo\fR
\fBTZ=\fB:\fIzoneinfo\fB:\fIzone\fR[\fB\-\fR]\fIoffset\fR[\fIdst\fR[\fIoffset\fR][\fB,\fIstart\fR[\fB/\fItime\fR]\fB,\fIend\fR[\fB/\fItime\fR]]]
.fi
.SH DESCRIPTION
.de SP
.if t .sp 0.4
.if n .sp
..
.de XS
.PP
.RS
.ft B
.nf
..
.de XE
.fi
.ft R
.RE
.PP
..
The
.B TZ
environment variable tells functions such as the
.BR ctime (3)
family and programs like
.B date
what the time zone and daylight saving rules are.  The value of
.B TZ
can be in one of three forms:
.PP
The \s-2POSIX\s+2 standardized form shown in the first line of the synopsis.
This form specifies the zone names, offsets from GMT, and daylight saving
changeover times for at least the current year.
.PP
The second synopsis form is for the BSD zoneinfo data files found in
.BR /usr/lib/zoneinfo .
These files contain all the information needed to compute the offsets and
daylight saving changeover times for the past years in many different time
zones.  Almost all large \s-2UNIX\s+2 systems use this info.
.PP
Under Minix-vmd one should always use a \s-2POSIX\s+2 style
.B TZ
value that is valid this year.  It is needed at boot time to set the clock.
Once the zoneinfo library is available the time functions will first try to
use a zoneinfo file named by the first part of the standard form,
"\fIzone\fR[\fB\-\fR]\fIoffset\fR[\fIdst\fR[\fIoffset\fR]]".  If that fails
then "\fIzone\fR" is tried.  One has to make sure that the zoneinfo file
selected is the correct one.  If not then one can either add a link in the
zoneinfo directory to the correct file, or one can use the third synopsis
form, a Minix specific new form that gives both a zoneinfo file name and a
standard string.
.SS "\s-2POSIX\s+2 standard form"
.TP
.I zone
A three or more letter name for the time zone in normal (winter) time.
.TP
.BI [\-] offset
A signed time telling the offset of the time zone westwards from Greenwich.
The time has the form
.I hh[:mm[:ss]]
with a one of two digit hour, and optional two digit minutes and seconds.
.TP
.I dst
The name of the time zone when daylight saving is in effect.  It may
be followed by an offset telling how big the clock correction is other than
the default of 1 hour.
.TP
\fIstart\fR/\fItime\fR,\fIend\fR/\fItime\fR
Specifies the start and end of the daylight saving period.  The
.I start
and
.I end
fields indicate on what day the changeover occurs.  They must be in one of
the following formats:
.SP
.ta +5
.in +5
.ti -5
\fBJ\fIn\fR	The Julian day
.I n
(1 <=
.I n
<= 365) ignoring leap days, i.e. there is no February 29.
.SP
.ti -5
\fIn\fR	The zero-based Julian day
(0 <=
.I n
<= 365).  Leap days are not ignored.
.SP
.ti -5
.BI M m . n . d
.br
This indicates month
.IR m ,
the
.IR n -th
occurrence of day
.I d
(1 <=
.I m
<= 12, 1 <=
.I n
<= 5, 0 <=
.I d
<= 6, 0=Sunday).  The 5-th occurrence means the last occurrence of that day
in a month.  So
.B M4.1.0
is the first Sunday in April,
.B M9.5.0
is the last Sunday in September.
.in -5
.SP
The
.I time
field indicates the time the changeover occurs on the given day.
.SH EXAMPLES
Greenwich Mean Time:
.XS
TZ=GMT0
.XE
Central European Time, 1 hour east from Greenwich, daylight saving starts on
the last Sunday in March at 2 AM and ends on the last Sunday in October
at 3 AM:
.XS
TZ='CET\-1CEST,M3.5.0/2,M10.5.0/3'
.XE
British time, daylight saving starts and ends at the same moment as CET,
but in an earlier time zone:
.XS
TZ=GMT0BST,M3.5.0/1,M10.5.0/2
.XE
Note that only a few European and North-American time zone names are
present in
.BR /usr/lib/zoneinfo ,
so for the above definition one must add a link from
.B Europe/London
to
.B GMT0BST
in the zoneinfo directory.  Otherwise one needs to use the following
Minix specific definition to let the time library find the zoneinfo file:
.XS
TZ=:Europe/London:GMT0BST,M3.5.0/1,M10.5.0/2
.XE
U.S. Eastern Standard Time, 5 hours west from Greenwich, daylight saving
starts on the first Sunday in April at 2 AM and ends on the last Sunday in
October at 2 AM:
.XS
TZ=EST5EDT,M4.1.0/2,M10.5.0/2
.XE
It shouldn't surprise you that daylight saving in New Zealand is observed
in the months opposite from the previous examples.  It starts on the first
Sunday in October at 2 AM and ends on the third Sunday in March at 3 AM:
.XS
TZ=:Pacific/Auckland:NZST\-12NZDT,M10.1.0/2,M3.3.0/3
.XE
Using
.B "ln Pacific/Auckland NZST\-12NZDT"
in
.B /usr/lib/zoneinfo
will allow one to use the POSIX standard form.
.PP
The command
.BR zdump (8)
can be used to check the
.B TZ
you are trying to put together:
.XS
zdump -v '\fITZ-string\fP' | more
.XE
First check what the timezone library has to offer, let's try Moscow:
.XS
zdump -v Europe/Moscow | more
.XE
Then test your timezone definition with timezone names that are not in
the library, e.g.
.XS
zdump -v www-3sss,M3.5.0/2,M10.5.0/3 | more
.XE
to make sure that the definition is correct at boot time.  Next make a link
if necessary and try the proper definition:
.XS
ln Europe/Moscow MOST
zdump -v MOST-3MOSST,M3.5.0/2,M10.5.0/3 | more
.XE
That definition should be put in
.BR /etc/timeinfo .
.PP
The source files used to create the time zone library are also in
.B /usr/lib/timeinfo
in files like "europe", "asia", etc.  They contain lots of interesting
comments next to the time rules.
.SH "SEE ALSO"
.BR readclock (8),
.BR date (1),
.BR utime (1),
.BR ctime (3),
.BR zic (8).
.SH BUGS
You may have noticed that many fields are optional.  Do no omit them,
because the defaults are bogus.  If you need daylight saving then fully
specify the changeovers.
.PP
West is negative, east is positive, ask any sailor.
.PP
Next year's time zone and daylight saving time are determined by politicians.
.SH AUTHOR
Kees J. Bot (kjb@cs.vu.nl)