mirror of
https://git.FreeBSD.org/src.git
synced 2024-10-18 02:19:39 +00:00
234 lines
12 KiB
Plaintext
234 lines
12 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);
|
|
|
|
/* Optional and obsolescent: */
|
|
extern char *tzname[];
|
|
extern long timezone;
|
|
extern int daylight;
|
|
|
|
cc ... -ltz
|
|
|
|
DESCRIPTION
|
|
The tzalloc function allocates and returns a timezone object described
|
|
by TZ.
|
|
|
|
If TZ is a null pointer, tzalloc uses 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.
|
|
|
|
If TZ is the empty string, tzalloc uses Universal Time (UT), 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 contents are used as a pathname, a pathname beginning with "/"
|
|
is used as-is; otherwise the pathname is 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:
|
|
|
|
stdoffset[dst[offset][,rule]]
|
|
|
|
Where:
|
|
|
|
std and dst
|
|
Three or more bytes that are the designation for the
|
|
standard (std) or the alternative (dst, such as daylight
|
|
saving time) time zone. Only std is required; if 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 (:),
|
|
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,
|
|
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) -
|
|
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 daylight saving
|
|
time. The rule has the form:
|
|
|
|
date/time,date/time
|
|
|
|
where the first date describes when the change from
|
|
standard to daylight saving 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. 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 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 timezone.
|
|
|
|
EST5 stands for US Eastern Standard Time (EST), 5 hours behind UT,
|
|
without daylight saving.
|
|
|
|
<+12>-12<+13>,M11.1.0,M1.2.1/147
|
|
stands for Fiji time, 12 hours ahead of UT, springing forward on
|
|
November's first Sunday at 02:00, and falling back on January's
|
|
second Monday at 147:00 (i.e., 03:00 on the first Sunday on or
|
|
after January 14). The abbreviations for standard and daylight
|
|
saving time are "+12" and "+13".
|
|
|
|
IST-2IDT,M3.4.4/26,M10.5.0
|
|
stands for Israel Standard Time (IST) and Israel Daylight Time
|
|
(IDT), 2 hours ahead of UT, 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.
|
|
|
|
<-04>4<-03>,J1/0,J365/25
|
|
stands for permanent daylight saving time, 3 hours behind UT
|
|
with abbreviation "-03". 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 <-04> is a placeholder.
|
|
|
|
<-03>3<-02>,M3.5.0/-2,M10.5.0/-1
|
|
stands for time in western Greenland, 3 hours behind UT, where
|
|
clocks follow the EU rules of springing forward on March's last
|
|
Sunday at 01:00 UT (-02:00 local time, i.e., 22:00 the previous
|
|
day) and falling back on October's last Sunday at 01:00 UT
|
|
(-01:00 local time, i.e., 23:00 the previous day). The
|
|
abbreviations for standard and daylight saving time are "-03"
|
|
and "-02".
|
|
|
|
If TZ specifies daylight saving time but does not specify a rule, and
|
|
the optional tzfile(5)-format file posixrules is present in the system
|
|
time conversion information directory, the rules in posixrules are
|
|
used, with the posixrules standard and daylight saving time offsets
|
|
from UT replaced by those specified by the offset values in TZ.
|
|
However, the posixrules file is obsolete: if it is present it is only
|
|
for backward compatibility, and it does not work reliably. Therefore,
|
|
if a TZ string directly specifies a timezone with daylight saving time,
|
|
it should specify the daylight saving rules explicitly.
|
|
|
|
For compatibility with System V Release 3.1, a semicolon (;) may be
|
|
used to separate the rule from the rest of the specification; this is
|
|
an extension to POSIX.
|
|
|
|
The tzfree function frees a timezone object tz, which should have been
|
|
successfully allocated by tzalloc. This invalidates any tm_zone
|
|
pointers that tz was used to set.
|
|
|
|
The tzset function acts like tzalloc(getenv("TZ")), except it saves any
|
|
resulting timezone object into internal storage that is accessed by
|
|
localtime, localtime_r, and mktime. The anonymous shared timezone
|
|
object is freed by the next call to tzset. If the implied call to
|
|
getenv fails, tzset acts like tzalloc(nullptr); if the implied call to
|
|
tzalloc fails, tzset falls back on UT.
|
|
|
|
As a side effect, the tzset function sets some external variables if
|
|
the platform defines them. It sets tzname[0] and tzname[1] to pointers
|
|
to strings that are time zone abbreviations to be used with standard
|
|
and daylight saving time, respectively. It also sets timezone to be
|
|
the number of seconds that standard time is west of the Prime Meridian,
|
|
and daylight to be zero if daylight saving time is never in effect,
|
|
non-zero otherwise.
|
|
|
|
RETURN VALUE
|
|
If successful, the tzalloc function returns a nonnull pointer to the
|
|
newly allocated object. Otherwise, it returns a null pointer and sets
|
|
errno.
|
|
|
|
ERRORS
|
|
EOVERFLOW
|
|
TZ directly specifies time conversion information, and contains
|
|
an integer out of machine range or a time zone abbreviation that
|
|
is too long for this platform.
|
|
|
|
The tzalloc function may also fail and set errno for any of the errors
|
|
specified for the routines access(2), close(2), malloc(3), open(2), and
|
|
read(2).
|
|
|
|
FILES
|
|
/etc/localtime local timezone file
|
|
/usr/share/zoneinfo timezone directory
|
|
/usr/share/zoneinfo/posixrules default DST rules (obsolete)
|
|
/usr/share/zoneinfo/GMT for UTC leap seconds
|
|
|
|
If /usr/share/zoneinfo/GMT is absent, UTC leap seconds are loaded from
|
|
/usr/share/zoneinfo/GMT0 if present.
|
|
|
|
SEE ALSO
|
|
getenv(3), newctime(3), newstrftime(3), time(2), tzfile(5).
|
|
|
|
NOTES
|
|
Portable code should not rely on the contents of the external variables
|
|
tzname, timezone and daylight as their contents are unspecified (and do
|
|
not make sense in general) when a geographical TZ is used. In
|
|
multithreaded applications behavior is undefined if one thread accesses
|
|
one of these variables while another thread invokes tzset. A future
|
|
version of POSIX is planned to remove these variables; callers can
|
|
instead use the tm_gmtoff and tm_zone members of struct tm, or use
|
|
strftime with "%z" or "%Z".
|
|
|
|
Time Zone Database newtzset(3)
|