332 lines
7 KiB
Groff
332 lines
7 KiB
Groff
.\" $OpenBSD: tzset.3,v 1.26 2022/10/04 13:33:57 millert Exp $
|
|
.Dd $Mdocdate: October 4 2022 $
|
|
.Dt TZSET 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm tzset ,
|
|
.Nm tzsetwall
|
|
.Nd initialize time conversion information
|
|
.Sh SYNOPSIS
|
|
.In time.h
|
|
.Vt extern char *tzname[2];
|
|
.Vt extern long timezone;
|
|
.Vt extern long daylight;
|
|
.Ft void
|
|
.Fn tzset "void"
|
|
.Ft void
|
|
.Fn tzsetwall "void"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn tzset
|
|
function uses the value of the environment variable
|
|
.Ev TZ
|
|
to set the time conversion information used by
|
|
.Xr localtime 3 .
|
|
It also sets the following external variables:
|
|
.Bl -tag -width "tzname[2]"
|
|
.It Vt tzname[2]
|
|
the designations for standard and daylight saving time; see the description of
|
|
.Ar std No and Ar dst
|
|
below
|
|
.It Vt timezone
|
|
the number of seconds west of UTC
|
|
.It Vt daylight
|
|
0 if the time zone has never observed daylight saving time, otherwise
|
|
non-zero
|
|
.El
|
|
.Pp
|
|
Most programs do not need to call
|
|
.Fn tzset
|
|
directly; it will be called automatically as needed by the functions
|
|
described in
|
|
.Xr localtime 3 .
|
|
Privileged processes that use
|
|
.Xr chroot 2
|
|
may wish to call
|
|
.Fn tzset
|
|
to initialize the time conversion information before changing to
|
|
a restricted root directory that does not include time conversion
|
|
data files.
|
|
.Pp
|
|
If
|
|
.Ev TZ
|
|
does not appear in the environment, or if the calling process has
|
|
changed its user or group ID, the system time zone file,
|
|
.Pa /etc/localtime ,
|
|
is used.
|
|
.Pp
|
|
If
|
|
.Ev TZ
|
|
appears in the environment it may be one of two formats:
|
|
.Bl -bullet
|
|
.It
|
|
the pathname of a
|
|
.Xr tzfile 5
|
|
format file from which to read the time conversion information,
|
|
optionally prefixed with a colon
|
|
.Pq Ql \&: ,
|
|
such as
|
|
.Dq :America/Denver
|
|
or
|
|
.Dq Europe/Berlin
|
|
.It
|
|
a string that directly specifies the time conversion information
|
|
(see below) which may not begin with a colon
|
|
.Pq Ql \&:
|
|
.El
|
|
.Pp
|
|
If
|
|
.Ev TZ
|
|
appears in the environment and its value does not begin with a colon,
|
|
it is first used as the
|
|
pathname of a
|
|
.Xr tzfile 5
|
|
format 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.
|
|
A value beginning with a colon
|
|
.Pq Ql \&:
|
|
is always treated as a pathname.
|
|
.Pp
|
|
If
|
|
.Ev TZ
|
|
is set to the empty string, Coordinated Universal Time (UTC) is
|
|
used (without leap second correction).
|
|
.Pp
|
|
When
|
|
.Ev TZ
|
|
is used as a pathname, it must either be a path relative to the system time
|
|
conversion information directory,
|
|
.Pa /usr/share/zoneinfo ,
|
|
or an absolute path that begins with
|
|
.Pa /usr/share/zoneinfo/ .
|
|
Other absolute paths, or paths that contain
|
|
.Ql \&../ ,
|
|
will be ignored and the system local time zone file,
|
|
.Pa /etc/localtime ,
|
|
will be used instead.
|
|
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 (without whitespace between
|
|
.Ar std
|
|
and
|
|
.Ar offset ) :
|
|
.Bd -ragged -offset indent
|
|
.Ar std
|
|
.Sm off
|
|
.Ar offset
|
|
.Op Ar dst Op Ar offset
|
|
.Op , Ar rule
|
|
.Sm on
|
|
.Ed
|
|
.Pp
|
|
Where:
|
|
.Bl -tag -width "std and dst"
|
|
.It Ar std No and Ar dst
|
|
Three or more bytes that are the designation for the standard
|
|
.Pq Ar std
|
|
or the daylight saving
|
|
.Pq Ar dst
|
|
time zone.
|
|
Only
|
|
.Ar std
|
|
is required; if
|
|
.Ar dst
|
|
is missing, then daylight saving time does not apply in this locale.
|
|
Upper and lowercase letters are explicitly allowed.
|
|
Any characters except a leading colon
|
|
.Pq Ql \&: ,
|
|
digits, comma
|
|
.Pq Ql \&, ,
|
|
minus
|
|
.Pq Ql \&- ,
|
|
plus
|
|
.Pq Ql \&+ ,
|
|
and ASCII NUL are allowed.
|
|
.It Ar offset
|
|
Indicates the value one must add to the local time to arrive at
|
|
Coordinated Universal Time.
|
|
.Ar offset
|
|
has the form:
|
|
.Pp
|
|
.D1 Ar hh Ns Op : Ns Ar mm Ns Op : Ns Ar ss
|
|
.Pp
|
|
The minutes
|
|
.Pq Ar mm
|
|
and seconds
|
|
.Pq Ar ss
|
|
are optional.
|
|
The hour
|
|
.Pq Ar hh
|
|
is required and may be a single digit.
|
|
The
|
|
.Ar offset
|
|
following
|
|
.Ar std
|
|
is required.
|
|
If no
|
|
.Ar offset
|
|
follows
|
|
.Ar dst ,
|
|
daylight saving 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) \(em if present \(em 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 Ar rule
|
|
Indicates when to change to and back from daylight saving time.
|
|
.Ar rule
|
|
has the form:
|
|
.Pp
|
|
.D1 Ar date Ns / Ns Ar time , Ns Ar date Ns / Ns Ar time
|
|
.Pp
|
|
where the first
|
|
.Ar date
|
|
describes when the change from standard to daylight saving time occurs and the
|
|
second
|
|
.Ar date
|
|
describes when the change back happens.
|
|
Each
|
|
.Ar time
|
|
field describes when, in current local time, the change to the other
|
|
time is made.
|
|
.Pp
|
|
The format of
|
|
.Ar date
|
|
is one of the following:
|
|
.Bl -tag -width Ds
|
|
.It Cm J Ns Ar n
|
|
The Julian day
|
|
.Ar n
|
|
.Pq 1 <= Ar n No <= 365 .
|
|
Leap days are not counted; that is, in all years \(em including leap
|
|
years \(em 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
|
|
.Pq 0 <= Ar n No <= 365 .
|
|
Leap days are counted, and it is possible to refer to February 29.
|
|
.It Cm M Ns Ar m . Ns Ar n . Ns Ar d
|
|
Day
|
|
.Ar d
|
|
.Pq 1 <= Ar d No <= 6
|
|
of week
|
|
.Ar n
|
|
.Pq 1 <= Ar n No <= 5
|
|
of month
|
|
.Ar m
|
|
.Pq 1 <= Ar m No <= 12 ,
|
|
where week 5 means
|
|
.Do
|
|
the last
|
|
.Ar d
|
|
day in month
|
|
.Ar m
|
|
.Dc
|
|
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
|
|
.Pp
|
|
The
|
|
.Ar time
|
|
has the same format as
|
|
.Ar offset
|
|
except that no leading sign
|
|
.Po
|
|
.Dq \&-
|
|
or
|
|
.Dq \&+
|
|
.Pc
|
|
is allowed.
|
|
The default, if
|
|
.Ar time
|
|
is not given, is
|
|
.Cm 02:00:00 .
|
|
.El
|
|
.Pp
|
|
If no
|
|
.Ar rule
|
|
is present in
|
|
.Ev TZ ,
|
|
the rules specified
|
|
by the
|
|
.Xr tzfile 5
|
|
format
|
|
file
|
|
.Cm posixrules
|
|
in the system time conversion information directory are used, with the
|
|
standard and daylight saving time offsets from UTC replaced by those
|
|
specified by the
|
|
.Ar offset
|
|
values in
|
|
.Ev TZ .
|
|
.Pp
|
|
For compatibility with System V Release 3.1, a semicolon
|
|
.Pq Ql \&;
|
|
may be used to separate the
|
|
.Ar rule
|
|
from the rest of the specification.
|
|
.Pp
|
|
If the
|
|
.Ev TZ
|
|
environment variable does not specify a
|
|
.Xr tzfile 5
|
|
format file
|
|
and cannot be interpreted as a direct specification,
|
|
UTC is used.
|
|
.Pp
|
|
.Fn tzsetwall
|
|
behaves identically to
|
|
.Fn tzset
|
|
but it only uses the
|
|
.Pa /etc/localtime
|
|
file (that is, it ignores the
|
|
.Ev TZ
|
|
environment variable).
|
|
.Sh FILES
|
|
.Bl -tag -width "/usr/share/zoneinfo/posixrules" -compact
|
|
.It Pa /usr/share/zoneinfo
|
|
time zone information directory
|
|
.It Pa /etc/localtime
|
|
local time zone file
|
|
.It Pa /usr/share/zoneinfo/posixrules
|
|
used with POSIX-style
|
|
.Ev TZ Ns 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-2008 .
|
|
The
|
|
.Fn tzsetwall
|
|
function is an extension to that specification.
|
|
.\" This file is in the public domain, so clarified as of
|
|
.\" 2009-05-17 by Arthur David Olson.
|