General description
The tzset()
function uses the value of the environment variable TZ to set time
conversion information used by ctime(), localtime(), mktime(), and
strftime(). If TZ is absent from the environment, or it is incorrect,
time-conversion information is obtained from the LC_TOD locale category.
tzset()
also sets the external variable
tzname:
extern char *tzname[2] = {"std", "dst"};
Here, std and dst are
Standard and Daylight Savings time zone names, specified by TZ or
the LC_TOD local category, respectively.
tzset() is called
by ctime(), localtime(), mktime(), setlocale(), and strftime(). It
can also be called explicitly by an application program.
The
format of TZ values recognized by tzset() is as follows:
stdoffset[dst[offset][,rule]]
- std and dst
- Indicate no fewer than three, but not more than TZNAME_MAX, bytes
that are the designation for the standard (std)
and daylight savings (dst) time zones. If
more than TZNAME_MAX bytes are specified for std or dst,
tzset() truncates to TZNAME_MAX bytes. Only std is
required; if dst is missing, daylight savings
time does not apply in this locale. Uppercase and lowercase letters
are explicitly allowed. Any character except a leading colon (:)
or digits, the comma (,), the minus (-), the plus
(+), and the NULL character are permitted to appear in these fields.
The meaning of these letters and characters is unspecified.
- offset
- Indicates the value that must be added to the local time to arrive
at Coordinated Universal Time (UTC). 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. offset following std is
required. If no offset follows dst,
daylight savings time is assumed to be 1 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 0 and 24; minutes and seconds,
if present, between 0 and 59. The difference between
standard time offset and daylight savings
time offset must be greater than or equal
to 0, but the difference may not be greater than 24 hours. Use of
values outside of these ranges causes tzset() to use the LC_TOD category
rather than the TZ environment variable for time conversion information.
An offset preceded by a minus (-) indicates
a time zone east of the Prime Meridian. A plus (+) preceding offset is
optional and indicates the time zone west of the Prime Meridian.
- rule
- Indicates when to change to and back from daylight savings time.
The rule has the form: date[/time],date[/time]
The
first date describes when the change from standard to daylight savings
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.
The format of date must be 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 dth
day (0≤d≤6) of week n of
month m of the year (1≤n≤5,
and 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 dth
day occurs. Day zero is Sunday.
The time has the same format as offset except
that no leading sign, minus (-) or plus (+), is allowed. The default,
if time is not given, is 02:00:00.
If dst is
specified and rule is not specified by TZ
or in LC_TOD category, the default for the daylight savings time start
date is M4.1.0 and for the daylight savings time end date is M10.5.0.
Special behavior for XPG4: The
tzset() function sets the external variable timezone to
the difference, in seconds, between Coordinated Universal Time (UTC) and
local standard time. tzset() sets the external variable daylight to
0 if summer time conversions should never be applied for the time
zone in use; otherwise to nonzero.
Since the external variables
timezone and daylight are global
to the process, they cannot be reliably used in a multithreaded application
or an application running from a DLL. The runtime library provides
two special functions, __tzone() and __dlght(), which return the address
of thread-specific versions of these external variables.
Special
behavior for POSIX C:The tzset() function only parses the TZ environment
variable if it is called from the initial processing thread (IPT)
by a threaded application.
Note: This function is sensitive to
time zone information which is provided by:
- The TZ environmental variable when POSIX(ON) and TZ is correctly
defined, or by the _TZ environmental variable when POSIX(OFF) and
_TZ is correctly defined.
- The LC_TOD category of the current locale if POSIX(OFF) or TZ
is not defined.
- When neither TZ nor _TZ is defined, the current locale is interrogated
for time zone information. If neither TZ nor _TZ is defined and LC_TOD
time zone information is not present in the current locale, a default
value is applied to local time. POSIX programs simply default to Coordinated
Universal Time (UTC), while non-POSIX programs establish an offset
from UTC based on the setting of the system clock. For more information
about customizing a time zone to work with local time, see “Customizing
a time zone” in z/OS XL C/C++ Programming Guide.
The time zone external variables tzname, timezone,
and daylight declarations remain feature test protected
in time.h.