197 lines
10 KiB
Plaintext
197 lines
10 KiB
Plaintext
NEWTZSET(3) Library Functions Manual NEWTZSET(3)
|
|
|
|
NAME
|
|
tzset - initialize time conversion information
|
|
|
|
SYNOPSIS
|
|
#include <time.h>
|
|
|
|
timezone_t tzalloc(char const *TZ);
|
|
|
|
void tzfree(timezone_t tz);
|
|
|
|
void tzset(void);
|
|
|
|
cc ... -ltz
|
|
|
|
DESCRIPTION
|
|
Tzalloc allocates and returns a time zone object described by TZ. If
|
|
TZ is not a valid time zone description, or if the object cannot be
|
|
allocated, tzalloc returns a null pointer and sets errno.
|
|
|
|
Tzfree frees a time zone object tz, which should have been successfully
|
|
allocated by tzalloc. This invalidates any tm_zone pointers that tz
|
|
was used to set.
|
|
|
|
Tzset acts like tzalloc(getenv("TZ")), except it saves any resulting
|
|
time zone object into internal storage that is accessed by localtime,
|
|
localtime_r, and mktime. The anonymous shared time zone object is
|
|
freed by the next call to tzset. If the implied call to tzalloc fails,
|
|
tzset falls back on UTC.
|
|
|
|
If TZ is null, the best available approximation to local wall clock
|
|
time, as specified by the tzfile(5)-format file localtime in the system
|
|
time conversion information directory, is used. If TZ is the empty
|
|
string, Universal Time (UT) is used, with the abbreviation "UTC" and
|
|
without leap second correction; please see newctime(3) for more about
|
|
UT, UTC, and leap seconds. If TZ is nonnull and nonempty:
|
|
|
|
if the value begins with a colon, it is used as a pathname of a
|
|
file from which to read the time conversion information;
|
|
|
|
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.
|
|
|
|
When 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 a
|
|
system time conversion information directory. The file must be in the
|
|
format specified in tzfile(5).
|
|
|
|
When TZ is used directly as a specification of the time conversion
|
|
information, it must have the following syntax (spaces inserted for
|
|
clarity):
|
|
|
|
stdoffset[dst[offset][,rule]]
|
|
|
|
Where:
|
|
|
|
std and dst Three or more bytes that are the designation for
|
|
the standard (std) or summer (dst) time zone.
|
|
Only std is required; if 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 (,), ASCII minus (-), ASCII
|
|
plus (+), and NUL bytes are allowed.
|
|
Alternatively, a designation can be surrounded by
|
|
angle brackets < and >; in this case, the
|
|
designation can contain any characters other than
|
|
> and NUL.
|
|
|
|
offset Indicates the value one must add to the local
|
|
time to arrive at Coordinated Universal Time.
|
|
The offset has the form:
|
|
|
|
hh[:mm[:ss]]
|
|
|
|
The minutes (mm) and seconds (ss) are optional.
|
|
The hour (hh) is required and may be a single
|
|
digit. The offset following std is required. If
|
|
no offset follows 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) - if present - between zero and 59. If
|
|
preceded by a "-", the time zone shall be east of
|
|
the Prime Meridian; otherwise it shall be west
|
|
(which may be indicated by an optional preceding
|
|
"+".
|
|
|
|
rule Indicates when to change to and back from summer
|
|
time. The rule has the form:
|
|
|
|
date/time,date/time
|
|
|
|
where the first date describes when the change
|
|
from standard to summer time occurs and the
|
|
second date describes when the change back
|
|
happens. Each 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 date is one of the following:
|
|
|
|
Jn The Julian day n (1 <= n <= 365). Leap
|
|
days are not counted; that is, in all
|
|
years - including leap years - February
|
|
28 is day 59 and March 1 is day 60. It
|
|
is impossible to explicitly refer to
|
|
the occasional February 29.
|
|
|
|
n The zero-based Julian day
|
|
(0 <= n <= 365). Leap days are
|
|
counted, and it is possible to refer to
|
|
February 29.
|
|
|
|
Mm.n.d The d'th day (0 <= d <= 6) of week n of
|
|
month m of the year (1 <= n <= 5,
|
|
1 <= m <= 12, where week 5 means "the
|
|
last d day in month m" which may occur
|
|
in either the fourth or the fifth
|
|
week). Week 1 is the first week in
|
|
which the d'th day occurs. Day zero is
|
|
Sunday.
|
|
|
|
The time has the same format as offset except
|
|
that POSIX does not allow a leading sign ("-" or
|
|
"+"). As an extension to POSIX, the hours part
|
|
of time can range from -167 through 167; this
|
|
allows for unusual rules such as "the Saturday
|
|
before the first Sunday of March". The default,
|
|
if time is not given, is 02:00:00.
|
|
|
|
Here are some examples of TZ values that directly specify the time zone
|
|
rules; they use some of the extensions to POSIX.
|
|
|
|
EST5 stands for US Eastern Standard Time (EST), 5 hours behind UTC,
|
|
without daylight saving.
|
|
|
|
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).
|
|
|
|
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.
|
|
|
|
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 WART is a placeholder.
|
|
|
|
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).
|
|
|
|
If no rule is present in TZ, the rules specified by the
|
|
tzfile(5)-format file posixrules in the system time conversion
|
|
information directory are used, with the standard and summer time
|
|
offsets from UTC replaced by those specified by the offset values in
|
|
TZ.
|
|
|
|
For compatibility with System V Release 3.1, a semicolon (;) may be
|
|
used to separate the rule from the rest of the specification.
|
|
|
|
FILES
|
|
/usr/local/etc/zoneinfo time zone information directory
|
|
/usr/local/etc/zoneinfo/localtime local time zone file
|
|
/usr/local/etc/zoneinfo/posixrules used with POSIX-style TZ's
|
|
/usr/local/etc/zoneinfo/GMT for UTC leap seconds
|
|
|
|
If /usr/local/etc/zoneinfo/GMT is absent, UTC leap seconds are loaded
|
|
from /usr/local/etc/zoneinfo/posixrules.
|
|
|
|
SEE ALSO
|
|
getenv(3), newctime(3), newstrftime(3), time(2), tzfile(5)
|
|
|
|
NEWTZSET(3)
|