timezone(3)timezone(3)NAME
daylight, timezone, tzname, tzset - sets and accesses time zone conver‐
sion information
SYNOPSIS
#include <time.h>
void tzset(void);
extern int daylight; extern long timezone; extern char *tzname[];
LIBRARY
Standard C Library (libc.so, libc.a)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
tzset(): POSIX.1, XSH4.2
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
DESCRIPTION
The tzset() function uses the value of the environment variable TZ to
set time conversion information used by several other functions,
including ctime(), ctime_r(), getdate(), getdate_r(), localtime(),
localtime_r(), mktime(), strftime(), and strptime().
If the TZ variable is not set, tzset() uses implementation-dependent
default time zone information. This information is located in the
/etc/zoneinfo/localtime file. See the section Time Zone Handling for
details.
The tzset() function sets the external variable tzname as follows:
tzname0 = "std"; tzname1 = "dst";
where std indicates the standard time zone and dst designates the
alternative time zone (such as Daylight Savings Time). (These variables
are described below in the section TZ Environment Variable.)
The tzset() function also sets the external variable daylight to 0 if
Daylight Savings Time conversions should never be applied for the time
zone in use. Otherwise, daylight is set to a nonzero value.
The external variable timezone is set to the difference, in seconds,
between Coordinated Universal Time (UTC) and local standard time. For
example:
───────────────
TZ timezone
───────────────
EST 5*60*60
GMT 0*60*60
JST -9*60*60
MET -1*60*60
MST 7*60*60
PST 8*60*60
───────────────
Time Zone Handling
The operating system uses a public-domain time zone handling package
that puts time zone conversion rules in easily accessible and modifi‐
able files. These files are in the directory /etc/zoneinfo/sources.
The time zone compiler zic(8) converts these files to a special format
described in tzfile(4) and places them in the /etc/zoneinfo directory.
This format is readable by the C library functions that handle time
zone information.
The tzset() function uses the tzfile-formatted file linked by
/etc/zoneinfo/localtime to set the time zone conversion information.
The /etc/zoneinfo/localtime link is set during installation to a file
in the /etc/zoneinfo directory. For example, for time zone information
consistent with the city of New York on the American continent,
/etc/zoneinfo/localtime is linked to /etc/zoneinfo/America/New_York.
If the TZ environment variable is defined, the defined value overrides
the time zone information in /etc/zoneinfo/localtime. TZ can be set by
a user as a regular environment variable for converting to alternate
time zones. See the section TZ Environment Variable for details.
Getting Time Zone Information
The libc routines ctime() and localtime() return the local time and
time zone information. The ctime() routine returns a string that corre‐
sponds to the local time; for example, Tue Oct 27 13:35:29 1992.
The localtime() routine returns a pointer to a tm structure (defined in
<sys/time.h>) that contains the local time expressed in fields of the
tm structure. For time zone information, there are three relevant
fields: A option that is set to 1 if daylight savings time is currently
in effect. Otherwise, the option is set to 0. Seconds east of Green‐
wich. For example, -18000 means 5 hours west of Greenwich. Abbrevia‐
tion for the current time zone (for example, EST, PDT, GMT).
Setting Time Zone Information
The /etc/zoneinfo/localtime link can be changed by the system adminis‐
trator to any file in the /etc/zoneinfo directory.
For example, the following command changes the local time zone to be
consistent with the city of New York on the American continent:
# ln -sf /etc/zoneinfo/America/New_York /etc/zoneinfo/localtime
Subsequent calls to the time zone related functions in libc (ctime()
and localtime()) use this link for the default time zone information.
If the time zone and daylight savings time information in the
/etc/zoneinfo/sources directory is incorrect for your time zone, you
can change the information in the source files and then use the zic
command to generate a corresponding /etc/zoneinfo file.
A user can override the default time zone information by setting the TZ
environment variable as described in the section TZ Environment Vari‐
able.
TZ Environment Variable
When TZ appears in the environment and its value is not a null string,
the value has one of three formats:
: :pathname stdoffset[dst[offset][,start[/time],end[/time]]]
[Tru64 UNIX] If TZ has the single colon format (:), Coordinated Uni‐
versal Time (UTC) is used.
[Tru64 UNIX] If TZ has the colon-pathname format (:pathname), the
characters following the colon specify the pathname of a tzfile(4) for‐
mat file from which to read the time conversion information. A path‐
name beginning with a slash (/) represents an absolute pathname; other‐
wise, the pathname is relative to the system time conversion informa‐
tion directory /etc/zoneinfo.
If TZ does not begin with a colon (:), the components of the string are
as follows: Three or more characters that are the designation for the
standard (std) or alternative (dst) time zone (such as Daylight Savings
Time). Only std is required. If dst is not supplied, the alternative
time does not apply to the locale. Upper- and lowercase letters are
explicitly allowed. Any characters, except digits, a leading colon (:),
comma (,), minus (-), plus (+), and ASCII NUL, are allowed. Indicates
the value to be added to the local time to arrive at GMT. The offset
has the form:
hh[:mm[:ss]]
The minutes (mm) and seconds (ss) are optional. The hour (hh) is
required and can be either one or two digits. The offset follow‐
ing std is required. If no offset follows dst, the alternative
time is assumed to be one hour ahead of standard time. One or
more digits can be used; the value is always interpreted as a
decimal number. The hour value must be between zero and 24. The
value for the minutes and seconds, if present, must be between
zero and 59. If preceded by a minus sign (-), the time zone is
east of the Prime Meridian; otherwise it is west, which can be
indicated by a preceding plus sign (+). Indicates when to
change to and return from alternative time. The start argument
is the date when the change from standard to alternative time
occurs; end is the date for changing back. If start and end are
not specified, the default is the US Daylight Saving Time start
and end dates. The format for start and end must be one of the
following: 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 explic‐
itly refer to February 29. The zero-based Julian day (0 <=n <=
365). Leap days are counted making it possible to refer to Feb‐
ruary 29. The dth day (0 <= d <= 6) of week n of month m of the
year (1 <= n <= 5, 1 <= m <= 12). When n is 5, it refers to the
last d day of month m which may occur in either the fourth or
fifth week. Week 1 is the first week in which the dth day
occurs. Day zero is Sunday. Describes the time when, in current
time, the change to or return from alternative time occurs. The
time parameter has the same format as offset, except that there
can be no leading minus (-) or plus (+) sign. If time is not
specified, the default is 02:00:00.
As an example, the TZ variable value EST5EDT4,M4.1.0,M10.5.0 describes
the rule defined in 1987 for the Eastern time zone in the US. EST
(Eastern Standard Time) is the designation for standard time, which is
5 hours behind GMT. EDT (Eastern Daylight Time) is the designation for
alternative time, which is 4 hours behind GMT. EDT starts on the first
Sunday in April and ends on the last Sunday in October. In both cases,
since time was not specified, the changes occur at the default time,
which is 2:00 A.M. Note that the start and end dates did not need to be
specified since they are the defaults.
NOTES
[Tru64 UNIX] For users of the SVID2 habitat, TZ is defined by default
in the following format:
stdoffset[dst[offset]]
[Tru64 UNIX] For users of the SVID3 habitat, TZ is defined by default
in the following format:
:pathname
See the section TZ Environment Variable for definitions of the parame‐
ters used in these formats.
SEE ALSO
Functions: ctime(3), ctime_r(3), difftime(3), getdate(3), getdate_r(3),
getenv(3), localtime(3), localtime_r(3), mktime(3), strftime(3), strp‐
time(3), time(3)
Commands: date(1), zdump(8), zic(8)
Files: tzfile(4)
Standards: standards(5)timezone(3)