408 lines
9.2 KiB
Groff
408 lines
9.2 KiB
Groff
.\" $NetBSD: tzset.3,v 1.34 2015/10/29 22:42:55 wiz Exp $
|
|
.Dd October 29, 2015
|
|
.Dt TZSET 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm tzset ,
|
|
.Nm tzalloc ,
|
|
.Nm tzgetname ,
|
|
.Nm tzgetgmtoff ,
|
|
.Nm tzfree
|
|
.Nd initialize time conversion information
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In time.h
|
|
.Ft timezone_t
|
|
.Fn tzalloc "const char *zone"
|
|
.Ft void
|
|
.Fn tzfree "timezone_t restrict tz"
|
|
.Ft const char *
|
|
.Fn tzgetname "timezone_t restrict tz" "int isdst"
|
|
.Ft long
|
|
.Fn tzgetgmtoff "timezone_t restrict tz" "int isdst"
|
|
.Ft void
|
|
.Fn tzset "void"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn tzalloc
|
|
function takes as an argument a timezone name and returns a
|
|
.Ft timezone_t
|
|
object suitable to be used in the
|
|
.Fn ctime_rz ,
|
|
.Fn localtime_rz ,
|
|
and
|
|
.Fn mktime_z
|
|
functions.
|
|
.Pp
|
|
If
|
|
.Ar tz
|
|
is not a valid time zone description, or if the object cannot be allocated,
|
|
.Fn tzalloc
|
|
returns a
|
|
.Dv NULL
|
|
pointer and sets
|
|
.Va errno .
|
|
.Pp
|
|
A
|
|
.Dv NULL
|
|
pointer may be passed to
|
|
.Fn tzalloc
|
|
instead of a timezone name, to refer to the current system timezone.
|
|
An empty timezone string indicates Coordinated Universal Time
|
|
.Pq Tn UTC .
|
|
.Pp
|
|
Note that instead of setting the environment variable
|
|
.Va TZ ,
|
|
and globally changing the behavior of the calling program, one can use
|
|
multiple timezones at the same time by using separate
|
|
.Ft timezone_t
|
|
objects allocated by
|
|
.Fn tzalloc
|
|
and calling the
|
|
.Dq z
|
|
variants of the functions.
|
|
The
|
|
.Fn tzfree
|
|
function deallocates
|
|
.Fa tz ,
|
|
which was previously allocated by
|
|
.Fn tzalloc .
|
|
This invalidates any
|
|
.Ft tm_zone
|
|
pointers that
|
|
.Fa tz
|
|
was used to set.
|
|
The function
|
|
.Fn tzgetname
|
|
returns the name for the given
|
|
.Fa tz .
|
|
If
|
|
.Fa isdst
|
|
is
|
|
.Va 0 ,
|
|
the call is equivalent to
|
|
.Va tzname[0] .
|
|
If
|
|
.Fa isdst
|
|
is set to
|
|
.Va 1
|
|
the call is equivalent to
|
|
.Va tzname[1] .
|
|
Finally, the
|
|
.Fn tzgetgmtoff
|
|
function acts like
|
|
.Fn tzgetname
|
|
only it returns the offset in seconds from GMT for the timezone.
|
|
If there is no match, then
|
|
.Dv \-1
|
|
is returned and
|
|
.Va errno
|
|
is set to
|
|
.Dv ESRCH .
|
|
The
|
|
.Fn tzset
|
|
function acts like
|
|
.Dv tzalloc(getenv("TZ")) ,
|
|
except it saves any resulting time zone object into internal
|
|
storage that is accessed by
|
|
.Fn localtime ,
|
|
.Fn localtime_r ,
|
|
and
|
|
.Fn mktime .
|
|
The anonymous shared time zone object is freed by the next call to
|
|
.Fn tzset .
|
|
If the implied call to
|
|
.Fn tzalloc
|
|
fails,
|
|
.Fn tzset
|
|
falls back on UTC.
|
|
If
|
|
.Ev TZ
|
|
is
|
|
.Dv NULL ,
|
|
the best available approximation to local wall clock time, as
|
|
specified by the
|
|
.Xr tzfile 5
|
|
format file
|
|
.Pa /etc/localtime
|
|
is used by
|
|
.Xr localtime 3 .
|
|
If
|
|
.Ev TZ
|
|
appears in the environment but its value is the empty string,
|
|
Universal Time (UT) is used, with the abbreviation
|
|
.Dq UTC
|
|
and without leap second correction; please see
|
|
.Xr ctime 3 .
|
|
If
|
|
.Ev TZ
|
|
is nonnull and nonempty:
|
|
.Bl -dash
|
|
.It
|
|
if the value begins with a colon, it is used as a pathname of a file
|
|
from which to read the time conversion information;
|
|
.It
|
|
if the value does not begin with a colon, it is first used as the
|
|
pathname of a file from which to read the time conversion information,
|
|
and, if that file cannot be read, is used directly as a specification
|
|
of the time conversion information.
|
|
.El
|
|
.Pp
|
|
When
|
|
.Ev TZ
|
|
is used as a pathname, if it begins with a slash, it is used as an
|
|
absolute pathname; otherwise, it is used as a pathname relative to
|
|
.Pa /usr/share/zoneinfo .
|
|
The file must be in the format specified in
|
|
.Xr tzfile 5 .
|
|
.Pp
|
|
When
|
|
.Ev TZ
|
|
is used directly as a specification of the time conversion information,
|
|
it must have the following syntax (spaces inserted for clarity):
|
|
.Sm off
|
|
.Bd -literal -offset indent
|
|
.Cm std Cm offset Oo
|
|
.Cm dst Oo
|
|
.Cm offset Oc Oo
|
|
.No , Cm rule Oc Oc
|
|
.Ed
|
|
.Sm on
|
|
.Pp
|
|
where:
|
|
.Bl -tag -width "std and dst" -compact
|
|
.It Cm std No and Cm dst
|
|
Three or more bytes that are the designation for the standard
|
|
.Cm ( std )
|
|
or summer
|
|
.Cm ( dst )
|
|
time zone.
|
|
Only
|
|
.Cm std
|
|
is required; if
|
|
.Cm dst
|
|
is missing, then summer time does not apply in this locale.
|
|
Upper- and lowercase letters are explicitly allowed.
|
|
Any characters except a leading colon (:), digits, comma (,), minus (-),
|
|
plus (+), and NUL bytes are allowed.
|
|
.It Cm offset
|
|
Indicates the value one must add to the local time to arrive at
|
|
Coordinated Universal Time.
|
|
The
|
|
.Cm offset
|
|
has the form:
|
|
.Sm off
|
|
.Bd -literal -offset indent
|
|
.Cm hh Oo
|
|
.Cm :mm Oo
|
|
.Cm :ss Oc Oc
|
|
.Ed
|
|
.Sm on
|
|
.Pp
|
|
The minutes
|
|
.Cm ( mm )
|
|
and seconds
|
|
.Cm ( ss )
|
|
are optional.
|
|
The hour
|
|
.Cm ( hh )
|
|
is required and may be a single digit.
|
|
The
|
|
.Cm offset
|
|
following
|
|
.Cm std
|
|
is required.
|
|
If no
|
|
.Cm offset
|
|
follows
|
|
.Cm dst ,
|
|
summer time is assumed to be one hour ahead of standard time.
|
|
One or more digits may be used; the value is always interpreted as a
|
|
decimal number.
|
|
The hour must be between zero and 24, and the minutes (and
|
|
seconds) \*(en if present \*(en between zero and 59.
|
|
If preceded by a
|
|
.Dq -
|
|
the time zone shall be east of the Prime Meridian; otherwise it shall be
|
|
west (which may be indicated by an optional preceding
|
|
.Dq + ) .
|
|
.It Cm rule
|
|
Indicates when to change to and back from summer time.
|
|
The
|
|
.Cm rule
|
|
has the form:
|
|
.Sm off
|
|
.Bd -literal -offset indent
|
|
.Xo
|
|
.Cm date No /
|
|
.Cm time No ,
|
|
.Cm date No /
|
|
.Cm time
|
|
.Xc
|
|
.Ed
|
|
.Sm on
|
|
.Pp
|
|
where the first
|
|
.Cm date
|
|
describes when the change from standard to summer time occurs and the
|
|
second
|
|
.Cm date
|
|
describes when the change back happens.
|
|
Each
|
|
.Cm time
|
|
field describes when, in current local time, the change to the other
|
|
time is made.
|
|
As an extension to POSIX, daylight saving is assumed to be in effect
|
|
all year if it begins January 1 at 00:00 and ends December 31 at
|
|
24:00 plus the difference between daylight saving and standard time,
|
|
leaving no room for standard time in the calendar.
|
|
The format of
|
|
.Fa date
|
|
is one of the following:
|
|
.Bl -tag -width "The Julian day" -compact
|
|
.It Cm J Ns Ar n
|
|
The Julian day
|
|
.Ar n
|
|
(1 \*[Le]
|
|
.Ar n
|
|
\*[Le] 365).
|
|
Leap days are not counted; that is, in all years \*(en including leap
|
|
years \*(en February 28 is day 59 and March 1 is day 60.
|
|
It is impossible to explicitly refer to the occasional February 29.
|
|
.It Ar n
|
|
The zero-based Julian day (0\ \*[Le]
|
|
.Ar n
|
|
\*[Le]\ 365).
|
|
Leap days are counted, and it is possible to refer to
|
|
February 29.
|
|
.Sm off
|
|
.It Cm M Ns Ar m No . Ar n No . Ar d
|
|
.Sm on
|
|
The
|
|
.Ar d Ns 'th
|
|
day
|
|
(0 \*[Le]
|
|
.Ar d
|
|
\*[Le]\ 6) of week
|
|
.Ar n
|
|
of month
|
|
.Ar m
|
|
of the year
|
|
(1 \*[Le]
|
|
.Ar n
|
|
\*[Le]\ 5, 1 \*[Le]
|
|
.Ar m
|
|
\*[Le]\ 12, where week 5 means
|
|
.Dq the\ last Ar d No day\ in\ month Ar m
|
|
which may occur in either the fourth or the fifth week).
|
|
Week 1 is the first week in which the
|
|
.Ar d Ns 'th
|
|
day occurs.
|
|
Day zero is Sunday.
|
|
.El
|
|
The
|
|
.Cm time
|
|
has the same format as
|
|
.Cm offset
|
|
except that POSIX does not allow a leading sign
|
|
.Dq -
|
|
or
|
|
.Dq +
|
|
is allowed.
|
|
As an extension to POSIX, the hours part of
|
|
.Cm time
|
|
can range from \-167 through 167; this allows for unusual rules such as
|
|
.Dq the Saturday before the first Sunday of March .
|
|
The default, if
|
|
.Cm time
|
|
is not given, is
|
|
.Cm 02:00:00 .
|
|
.El
|
|
.Pp
|
|
Here are some examples of
|
|
.Va TZ
|
|
values that directly specify the time zone rules; they use some of the
|
|
extensions to POSIX.
|
|
.Bl -tag
|
|
.It EST5
|
|
stands for US Eastern Standard
|
|
Time (EST), 5 hours behind UTC, without daylight saving.
|
|
.It FJT\-12FJST,M11.1.0,M1.3.4/75
|
|
stands for Fiji Time (FJT) and Fiji Summer Time (FJST), 12 hours ahead
|
|
of UTC, springing forward on November's first Sunday at 02:00, and
|
|
falling back on January's third Thursday at 75:00 (i.e., 03:00 on the
|
|
first Sunday on or after January 18).
|
|
.It IST\-2IDT,M3.4.4/26,M10.5.0
|
|
stands for Israel Standard Time (IST) and Israel Daylight Time (IDT),
|
|
2 hours ahead of UTC, springing forward on March's fourth
|
|
Thursday at 26:00 (i.e., 02:00 on the first Friday on or after March
|
|
23), and falling back on October's last Sunday at 02:00.
|
|
.It WART4WARST,J1/0,J365/25
|
|
stands for Western Argentina Summer Time (WARST), 3 hours behind UTC.
|
|
There is a dummy fall-back transition on December 31 at 25:00 daylight
|
|
saving time (i.e., 24:00 standard time, equivalent to January 1 at
|
|
00:00 standard time), and a simultaneous spring-forward transition on
|
|
January 1 at 00:00 standard time, so daylight saving time is in effect
|
|
all year and the initial
|
|
.Em WART
|
|
is a placeholder.
|
|
.It WGT3WGST,M3.5.0/\-2,M10.5.0/\-1
|
|
stands for Western Greenland Time (WGT) and Western Greenland Summer
|
|
Time (WGST), 3 hours behind UTC, where clocks follow the EU rules of
|
|
springing forward on March's last Sunday at 01:00 UTC (\-02:00 local
|
|
time) and falling back on October's last Sunday at 01:00 UTC
|
|
(\-01:00 local time).
|
|
.El
|
|
.Pp
|
|
If no
|
|
.Cm rule
|
|
is present in
|
|
.Ev TZ ,
|
|
the rules specified by the
|
|
.Xr tzfile 5
|
|
format file
|
|
.Pa posixrules
|
|
in
|
|
.Pa /usr/share/zoneinfo
|
|
are used, with the standard and summer time offsets from UTC replaced
|
|
by those specified by the
|
|
.Cm offset
|
|
values in
|
|
.Ev TZ .
|
|
.Pp
|
|
For compatibility with System V Release 3.1, a semicolon (;) may be
|
|
used to separate the
|
|
.Cm rule
|
|
from the rest of the specification.
|
|
.Sh FILES
|
|
.Bl -tag -width /usr/share/zoneinfo/posixrules -compact
|
|
.It Pa /etc/localtime
|
|
local time zone file
|
|
.It Pa /usr/share/zoneinfo
|
|
time zone information directory
|
|
.It Pa /usr/share/zoneinfo/posixrules
|
|
used with POSIX-style TZ's
|
|
.It Pa /usr/share/zoneinfo/GMT
|
|
for UTC leap seconds
|
|
.El
|
|
.Pp
|
|
If
|
|
.Pa /usr/share/zoneinfo/GMT
|
|
is absent, UTC leap seconds are loaded from
|
|
.Pa /usr/share/zoneinfo/posixrules .
|
|
.Sh SEE ALSO
|
|
.Xr ctime 3 ,
|
|
.Xr getenv 3 ,
|
|
.Xr strftime 3 ,
|
|
.Xr time 3 ,
|
|
.Xr tzfile 5
|
|
.Sh STANDARDS
|
|
The
|
|
.Fn tzset
|
|
function conforms to
|
|
.St -p1003.1-88 .
|
|
.\" @(#)newtzset.3 8.2
|
|
.\" This file is in the public domain, so clarified as of
|
|
.\" 2009-05-17 by Arthur David Olson.
|