diff options
Diffstat (limited to 'man3/tzset.3')
| -rw-r--r-- | man3/tzset.3 | 245 |
1 files changed, 245 insertions, 0 deletions
diff --git a/man3/tzset.3 b/man3/tzset.3 new file mode 100644 index 0000000..4027bb3 --- /dev/null +++ b/man3/tzset.3 @@ -0,0 +1,245 @@ +'\" t +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 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 2023-07-20 "Linux man-pages 6.05.01" +.SH NAME +tzset, tzname, timezone, daylight \- initialize time conversion information +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.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 +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.BR tzset (): +.nf + _POSIX_C_SOURCE +.fi +.PP +.IR tzname : +.nf + _POSIX_C_SOURCE +.fi +.PP +.IR timezone , +.IR daylight : +.nf + _XOPEN_SOURCE + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE +.fi +.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 +character 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: +.PP +.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; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tzset () +T} Thread safety MT-Safe env locale +.TE +.sp 1 +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.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) |