man3/tzset.3

   1 '\" t
   2 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" References consulted:
   7 .\"     Linux libc source code
   8 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   9 .\"     386BSD man pages
  10 .\" Modified Sun Jul 25 11:01:58 1993 by Rik Faith (faith@cs.unc.edu)
  11 .\" Modified 2001-11-13, aeb
  12 .\" Modified 2004-12-01 mtk and Martin Schulze <joey@infodrom.org>
  13 .\"
  14 .TH tzset 3 (date) "Linux man-pages (unreleased)"
  15 .SH NAME
  16 tzset, tzname, timezone, daylight \- initialize time conversion information
  17 .SH LIBRARY
  18 Standard C library
  19 .RI ( libc ", " \-lc )
  20 .SH SYNOPSIS
  21 .nf
  22 .B #include <time.h>
  23 .P
  24 .B void tzset(void);
  25 .P
  26 .BI "extern char *" tzname [2];
  27 .BI "extern long " timezone ;
  28 .BI "extern int " daylight ;
  29 .fi
  30 .P
  31 .RS -4
  32 Feature Test Macro Requirements for glibc (see
  33 .BR feature_test_macros (7)):
  34 .RE
  35 .P
  36 .BR tzset ():
  37 .nf
  38     _POSIX_C_SOURCE
  39 .fi
  40 .P
  41 .IR tzname :
  42 .nf
  43     _POSIX_C_SOURCE
  44 .fi
  45 .P
  46 .IR timezone ,
  47 .IR daylight :
  48 .nf
  49     _XOPEN_SOURCE
  50         || /* glibc >= 2.19: */ _DEFAULT_SOURCE
  51         || /* glibc <= 2.19: */ _SVID_SOURCE
  52 .fi
  53 .SH DESCRIPTION
  54 The
  55 .BR tzset ()
  56 function initializes the \fItzname\fP variable from the
  57 .B TZ
  58 environment variable.
  59 This function is automatically called by the
  60 other time conversion functions that depend on the timezone.
  61 In a System-V-like environment, it will also set the variables \fItimezone\fP
  62 (seconds West of UTC) and \fIdaylight\fP (to 0 if this timezone does not
  63 have any daylight saving time rules, or to nonzero if there is a time,
  64 past, present, or future when daylight saving time applies).
  65 .P
  66 If the
  67 .B TZ
  68 variable does not appear in the environment, the system timezone is used.
  69 The system timezone is configured by copying, or linking, a file in the
  70 .BR tzfile (5)
  71 format to
  72 .IR /etc/localtime .
  73 A timezone database of these files may be located in the system
  74 timezone directory (see the \fBFILES\fP section below).
  75 .P
  76 If the
  77 .B TZ
  78 variable does appear in the environment, but its value is empty,
  79 or its value cannot be interpreted using any of the formats specified
  80 below, then Coordinated Universal Time (UTC) is used.
  81 .P
  82 The value of
  83 .B TZ
  84 can be one of two formats.
  85 The first format is a string of characters that directly represent the
  86 timezone to be used:
  87 .P
  88 .in +4n
  89 .EX
  90 .IR "std offset" [ dst [ offset ][, start [ /time ], end [ /time ]]]
  91 .EE
  92 .in
  93 .P
  94 There are no spaces in the specification.
  95 The \fIstd\fP string specifies an abbreviation for the timezone and must be
  96 three or more alphabetic characters.
  97 When enclosed between the less-than (<) and greater-than (>) signs, the
  98 character set is expanded to include the plus (+) sign, the minus (\-)
  99 sign, and digits.
 100 The \fIoffset\fP string immediately
 101 follows \fIstd\fP and specifies the time value to be added to the local
 102 time to get Coordinated Universal Time (UTC).
 103 The \fIoffset\fP is positive
 104 if the local timezone is west of the Prime Meridian and negative if it is
 105 east.
 106 The hour must be between 0 and 24, and the minutes and seconds 00 and 59:
 107 .P
 108 .in +4n
 109 .EX
 110 .RI [ + | \- ] hh [ :mm [ :ss ]]
 111 .EE
 112 .in
 113 .P
 114 The \fIdst\fP string and \fIoffset\fP specify the name and offset for the
 115 corresponding daylight saving timezone.
 116 If the offset is omitted,
 117 it defaults to one hour ahead of standard time.
 118 .P
 119 The \fIstart\fP field specifies when daylight saving time goes into
 120 effect and the \fIend\fP field specifies when the change is made back to
 121 standard time.
 122 These fields may have the following formats:
 123 .TP
 124 J\fIn\fP
 125 This specifies the Julian day with \fIn\fP between 1 and 365.
 126 Leap days are not counted.
 127 In this format, February 29 can't be represented;
 128 February 28 is day 59, and March 1 is always day 60.
 129 .TP
 130 .I n
 131 This specifies the zero-based Julian day with \fIn\fP between 0 and 365.
 132 February 29 is counted in leap years.
 133 .TP
 134 M\fIm\fP.\fIw\fP.\fId\fP
 135 This specifies day \fId\fP (0 <= \fId\fP <= 6) of week \fIw\fP
 136 (1 <= \fIw\fP <= 5) of month \fIm\fP (1 <= \fIm\fP <= 12).
 137 Week 1 is
 138 the first week in which day \fId\fP occurs and week 5 is the last week
 139 in which day \fId\fP occurs.
 140 Day 0 is a Sunday.
 141 .P
 142 The \fItime\fP fields specify when, in the local time currently in effect,
 143 the change to the other time occurs.
 144 If omitted, the default is 02:00:00.
 145 .P
 146 Here is an example for New Zealand,
 147 where the standard time (NZST) is 12 hours ahead of UTC,
 148 and daylight saving time (NZDT), 13 hours ahead of UTC,
 149 runs from the first Sunday in October to the third Sunday in March,
 150 and the changeovers happen at the default time of 02:00:00:
 151 .P
 152 .in +4n
 153 .EX
 154 TZ="NZST\-12:00:00NZDT\-13:00:00,M10.1.0,M3.3.0"
 155 .EE
 156 .in
 157 .P
 158 The second format specifies that the timezone information should be read
 159 from a file:
 160 .P
 161 .in +4n
 162 .EX
 163 :[filespec]
 164 .EE
 165 .in
 166 .P
 167 If the file specification \fIfilespec\fP is omitted, or its value cannot
 168 be interpreted, then Coordinated Universal Time (UTC) is used.
 169 If \fIfilespec\fP is given, it specifies another
 170 .BR tzfile (5)-format
 171 file to read the timezone information from.
 172 If \fIfilespec\fP does not begin with a \[aq]/\[aq], the file specification is
 173 relative to the system timezone directory.
 174 If the colon is omitted each
 175 of the above \fBTZ\fP formats will be tried.
 176 .P
 177 Here's an example, once more for New Zealand:
 178 .P
 179 .in +4n
 180 .EX
 181 TZ=":Pacific/Auckland"
 182 .EE
 183 .in
 184 .SH ENVIRONMENT
 185 .TP
 186 .B TZ
 187 If this variable is set its value takes precedence over the system
 188 configured timezone.
 189 .TP
 190 .B TZDIR
 191 If this variable is set its value takes precedence over the system
 192 configured timezone database directory path.
 193 .SH FILES
 194 .TP
 195 .I /etc/localtime
 196 The system timezone file.
 197 .TP
 198 .I /usr/share/zoneinfo/
 199 The system timezone database directory.
 200 .TP
 201 .I /usr/share/zoneinfo/posixrules
 202 When a TZ string includes a dst timezone without anything following it,
 203 then this file is used for the start/end rules.
 204 It is in the
 205 .BR tzfile (5)
 206 format.
 207 By default, the zoneinfo Makefile hard links it to the
 208 .IR America/New_York " tzfile."
 209 .P
 210 Above are the current standard file locations, but they are
 211 configurable when glibc is compiled.
 212 .SH ATTRIBUTES
 213 For an explanation of the terms used in this section, see
 214 .BR attributes (7).
 215 .TS
 216 allbox;
 217 lbx lb lb
 218 l l l.
 219 Interface       Attribute       Value
 220 T{
 221 .na
 222 .nh
 223 .BR tzset ()
 224 T}      Thread safety   MT-Safe env locale
 225 .TE
 226 .SH STANDARDS
 227 POSIX.1-2008.
 228 .SH HISTORY
 229 POSIX.1-2001, SVr4, 4.3BSD.
 230 .P
 231 4.3BSD had a function
 232 .BI "char *timezone(" zone ", " dst )
 233 that returned the
 234 name of the timezone corresponding to its first argument (minutes
 235 West of UTC).
 236 If the second argument was 0, the standard name was used,
 237 otherwise the daylight saving time version.
 238 .SH SEE ALSO
 239 .BR date (1),
 240 .BR gettimeofday (2),
 241 .BR time (2),
 242 .BR ctime (3),
 243 .BR getenv (3),
 244 .BR tzfile (5)