mirror of https://github.com/mkerrisk/man-pages
251 lines
7.5 KiB
Groff
251 lines
7.5 KiB
Groff
.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" References consulted:
|
|
.\" Linux libc source code
|
|
.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
|
|
.\" 386BSD man pages
|
|
.\" Modified Sun Jul 25 11:01:58 1993 by Rik Faith (faith@cs.unc.edu)
|
|
.\" Modified 2001-11-13, aeb
|
|
.\" Modified 2004-12-01 mtk and Martin Schulze <joey@infodrom.org>
|
|
.\"
|
|
.TH TZSET 3 2017-09-15 "" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
tzset, tzname, timezone, daylight \- initialize time conversion information
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <time.h>
|
|
.PP
|
|
.B void tzset (void);
|
|
.PP
|
|
.BI "extern char *" tzname [2];
|
|
.BI "extern long " timezone ;
|
|
.BI "extern int " daylight ;
|
|
.fi
|
|
.PP
|
|
.in -4n
|
|
Feature Test Macro Requirements for glibc (see
|
|
.BR feature_test_macros (7)):
|
|
.in
|
|
.PP
|
|
.BR tzset ():
|
|
_POSIX_C_SOURCE
|
|
.br
|
|
.IR tzname :
|
|
_POSIX_C_SOURCE
|
|
.br
|
|
.IR timezone ,
|
|
.IR daylight :
|
|
_XOPEN_SOURCE
|
|
|| /* Glibc since 2.19: */ _DEFAULT_SOURCE
|
|
|| /* Glibc versions <= 2.19: */ _SVID_SOURCE
|
|
.SH DESCRIPTION
|
|
The
|
|
.BR tzset ()
|
|
function initializes the \fItzname\fP variable from the
|
|
.B TZ
|
|
environment variable.
|
|
This function is automatically called by the
|
|
other time conversion functions that depend on the timezone.
|
|
In a System-V-like environment, it will also set the variables \fItimezone\fP
|
|
(seconds West of UTC) and \fIdaylight\fP (to 0 if this timezone does not
|
|
have any daylight saving time rules, or to nonzero if there is a time,
|
|
past, present or future when daylight saving time applies).
|
|
.PP
|
|
If the
|
|
.B TZ
|
|
variable does not appear in the environment, the system timezone is used.
|
|
The system timezone is configured by copying, or linking, a file in the
|
|
.BR tzfile (5)
|
|
format to
|
|
.IR /etc/localtime .
|
|
A timezone database of these files may be located in the system
|
|
timezone directory (see the \fBFILES\fP section below).
|
|
.PP
|
|
If the
|
|
.B TZ
|
|
variable does appear in the environment, but its value is empty,
|
|
or its value cannot be interpreted using any of the formats specified
|
|
below, then Coordinated Universal Time (UTC) is used.
|
|
.PP
|
|
The value of
|
|
.B TZ
|
|
can be one of two formats.
|
|
The first format is a string of characters that directly represent the
|
|
timezone to be used:
|
|
.PP
|
|
.in +4n
|
|
.EX
|
|
.IR "std offset" [ dst [ offset ][, start [ /time ], end [ /time ]]]
|
|
.EE
|
|
.in
|
|
.PP
|
|
There are no spaces in the specification.
|
|
The \fIstd\fP string specifies an abbreviation for the timezone and must be
|
|
three or more alphabetic characters.
|
|
When enclosed between the less-than (<) and greater-than (>) signs, the
|
|
characters set is expanded to include the plus (+) sign, the minus (-)
|
|
sign, and digits.
|
|
The \fIoffset\fP string immediately
|
|
follows \fIstd\fP and specifies the time value to be added to the local
|
|
time to get Coordinated Universal Time (UTC).
|
|
The \fIoffset\fP is positive
|
|
if the local timezone is west of the Prime Meridian and negative if it is
|
|
east.
|
|
The hour must be between 0 and 24, and the minutes and seconds 00 and 59:
|
|
.PP
|
|
.in +4n
|
|
.EX
|
|
.RI [ + | - ] hh [ :mm [ :ss ]]
|
|
.EE
|
|
.in
|
|
.PP
|
|
The \fIdst\fP string and \fIoffset\fP specify the name and offset for the
|
|
corresponding daylight saving timezone.
|
|
If the offset is omitted,
|
|
it defaults to one hour ahead of standard time.
|
|
.PP
|
|
The \fIstart\fP field specifies when daylight saving time goes into
|
|
effect and the \fIend\fP field specifies when the change is made back to
|
|
standard time.
|
|
These fields may have the following formats:
|
|
.TP
|
|
J\fIn\fP
|
|
This specifies the Julian day with \fIn\fP between 1 and 365.
|
|
Leap days are not counted.
|
|
In this format, February 29 can't be represented;
|
|
February 28 is day 59, and March 1 is always day 60.
|
|
.TP
|
|
.I n
|
|
This specifies the zero-based Julian day with \fIn\fP between 0 and 365.
|
|
February 29 is counted in leap years.
|
|
.TP
|
|
M\fIm\fP.\fIw\fP.\fId\fP
|
|
This specifies day \fId\fP (0 <= \fId\fP <= 6) of week \fIw\fP
|
|
(1 <= \fIw\fP <= 5) of month \fIm\fP (1 <= \fIm\fP <= 12).
|
|
Week 1 is
|
|
the first week in which day \fId\fP occurs and week 5 is the last week
|
|
in which day \fId\fP occurs.
|
|
Day 0 is a Sunday.
|
|
.PP
|
|
The \fItime\fP fields specify when, in the local time currently in effect,
|
|
the change to the other time occurs.
|
|
If omitted, the default is 02:00:00.
|
|
.PP
|
|
Here is an example for New Zealand,
|
|
where the standard time (NZST) is 12 hours ahead of UTC,
|
|
and daylight saving time (NZDT), 13 hours ahead of UTC,
|
|
runs from the first Sunday in October to the third Sunday in March,
|
|
and the changeovers happen at the default time of 02:00:00:
|
|
.in +4n
|
|
.EX
|
|
TZ="NZST-12:00:00NZDT-13:00:00,M10.1.0,M3.3.0"
|
|
.EE
|
|
.in
|
|
.PP
|
|
The second format specifies that the timezone information should be read
|
|
from a file:
|
|
.PP
|
|
.in +4n
|
|
.EX
|
|
:[filespec]
|
|
.EE
|
|
.in
|
|
.PP
|
|
If the file specification \fIfilespec\fP is omitted, or its value cannot
|
|
be interpreted, then Coordinated Universal Time (UTC) is used.
|
|
If \fIfilespec\fP is given, it specifies another
|
|
.BR tzfile (5)-format
|
|
file to read the timezone information from.
|
|
If \fIfilespec\fP does not begin with a \(aq/\(aq, the file specification is
|
|
relative to the system timezone directory.
|
|
If the colon is omitted each
|
|
of the above \fBTZ\fP formats will be tried.
|
|
.PP
|
|
Here's an example, once more for New Zealand:
|
|
.PP
|
|
.in +4n
|
|
.EX
|
|
TZ=":Pacific/Auckland"
|
|
.EE
|
|
.in
|
|
.SH ENVIRONMENT
|
|
.TP
|
|
.B TZ
|
|
If this variable is set its value takes precedence over the system
|
|
configured timezone.
|
|
.TP
|
|
.B TZDIR
|
|
If this variable is set its value takes precedence over the system
|
|
configured timezone database directory path.
|
|
.SH FILES
|
|
.TP
|
|
.I /etc/localtime
|
|
The system timezone file.
|
|
.TP
|
|
.I /usr/share/zoneinfo/
|
|
The system timezone database directory.
|
|
.TP
|
|
.I /usr/share/zoneinfo/posixrules
|
|
When a TZ string includes a dst timezone without anything following it,
|
|
then this file is used for the start/end rules.
|
|
It is in the
|
|
.BR tzfile (5)
|
|
format.
|
|
By default, the zoneinfo Makefile hard links it to the
|
|
.IR America/New_York " tzfile."
|
|
.PP
|
|
Above are the current standard file locations, but they are
|
|
configurable when glibc is compiled.
|
|
.SH ATTRIBUTES
|
|
For an explanation of the terms used in this section, see
|
|
.BR attributes (7).
|
|
.TS
|
|
allbox;
|
|
lb lb lb
|
|
l l l.
|
|
Interface Attribute Value
|
|
T{
|
|
.BR tzset ()
|
|
T} Thread safety MT-Safe env locale
|
|
.TE
|
|
.SH CONFORMING TO
|
|
POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.
|
|
.SH NOTES
|
|
.PP
|
|
4.3BSD had a function
|
|
.BI "char *timezone(" zone ", " dst )
|
|
that returned the
|
|
name of the timezone corresponding to its first argument (minutes
|
|
West of UTC).
|
|
If the second argument was 0, the standard name was used,
|
|
otherwise the daylight saving time version.
|
|
.SH SEE ALSO
|
|
.BR date (1),
|
|
.BR gettimeofday (2),
|
|
.BR time (2),
|
|
.BR ctime (3),
|
|
.BR getenv (3),
|
|
.BR tzfile (5)
|