newtzset.3

   1 .TH NEWTZSET 3
   2 .SH NAME
   3 tzset \- initialize time conversion information
   4 .SH SYNOPSIS
   5 .nf
   6 .ie \n(.g .ds - \f(CW-\fP
   7 .el ds - \-
   8 .B #include <time.h>
   9 .PP
  10 .B timezone_t tzalloc(char const *TZ);
  11 .PP
  12 .B void tzfree(timezone_t tz);
  13 .PP
  14 .B void tzset(void);
  15 .PP
  16 .B cc ... \*-ltz
  17 .fi
  18 .SH DESCRIPTION
  19 .ie '\(en'' .ds en \-
  20 .el .ds en \(en
  21 .ie '\(lq'' .ds lq \&"\"
  22 .el .ds lq \(lq\"
  23 .ie '\(rq'' .ds rq \&"\"
  24 .el .ds rq \(rq\"
  25 .de q
  26 \\$3\*(lq\\$1\*(rq\\$2
  27 ..
  28 .I Tzalloc
  29 allocates and returns a time zone object described by
  30 .BR TZ .
  31 If
  32 .B TZ
  33 is not a valid time zone description, or if the object cannot be allocated,
  34 .I tzalloc
  35 returns a null pointer and sets
  36 .BR errno .
  37 .PP
  38 .I Tzfree
  39 frees a time zone object
  40 .BR tz ,
  41 which should have been successfully allocated by
  42 .IR tzalloc .
  43 This invalidates any
  44 .B tm_zone
  45 pointers that
  46 .B tz
  47 was used to set.
  48 .PP
  49 .I Tzset
  50 acts like
  51 .BR tzalloc(getenv("TZ")) ,
  52 except it saves any resulting time zone object into internal
  53 storage that is accessed by
  54 .IR localtime ,
  55 .IR localtime_r ,
  56 and
  57 .IR mktime .
  58 The anonymous shared time zone object is freed by the next call to
  59 .IR tzset .
  60 If the implied call to
  61 .B tzalloc
  62 fails,
  63 .I tzset
  64 falls back on UTC.
  65 .PP
  66 If
  67 .B TZ
  68 is null, the best available approximation to local wall
  69 clock time, as specified by the
  70 .IR tzfile (5)-format
  71 file
  72 .B localtime
  73 in the system time conversion information directory, is used.
  74 If
  75 .B TZ
  76 is the empty string,
  77 Universal Time (UT) is used, with the abbreviation "UTC"
  78 and without leap second correction; please see
  79 .IR newctime (3)
  80 for more about UT, UTC, and leap seconds.  If
  81 .B TZ
  82 is nonnull and nonempty:
  83 .IP
  84 if the value begins with a colon, it is used as a pathname of a file
  85 from which to read the time conversion information;
  86 .IP
  87 if the value does not begin with a colon, it is first used as the
  88 pathname of a file from which to read the time conversion information,
  89 and, if that file cannot be read, is used directly as a specification of
  90 the time conversion information.
  91 .PP
  92 When
  93 .B TZ
  94 is used as a pathname, if it begins with a slash,
  95 it is used as an absolute pathname; otherwise,
  96 it is used as a pathname relative to a system time conversion information
  97 directory.
  98 The file must be in the format specified in
  99 .IR tzfile (5).
 100 .PP
 101 When
 102 .B TZ
 103 is used directly as a specification of the time conversion information,
 104 it must have the following syntax (spaces inserted for clarity):
 105 .IP
 106 \fIstd\|offset\fR[\fIdst\fR[\fIoffset\fR][\fB,\fIrule\fR]]
 107 .PP
 108 Where:
 109 .RS
 110 .TP 15
 111 .IR std " and " dst
 112 Three or more bytes that are the designation for the standard
 113 .RI ( std )
 114 or summer
 115 .RI ( dst )
 116 time zone.  Only
 117 .I std
 118 is required; if
 119 .I dst
 120 is missing, then summer time does not apply in this locale.
 121 Upper- and lowercase letters are explicitly allowed.  Any characters
 122 except a leading colon
 123 .RB ( : ),
 124 digits, comma
 125 .RB ( , ),
 126 ASCII minus
 127 .RB ( \*- ),
 128 ASCII plus
 129 .RB ( + ),
 130 and NUL bytes are allowed.
 131 Alternatively, a designation can be surrounded by angle brackets
 132 .B <
 133 and
 134 .BR > ;
 135 in this case, the designation can contain any characters other than
 136 .B >
 137 and NUL.
 138 .TP
 139 .I offset
 140 Indicates the value one must add to the local time to arrive at
 141 Coordinated Universal Time.  The
 142 .I offset
 143 has the form:
 144 .RS
 145 .IP
 146 \fIhh\fR[\fB:\fImm\fR[\fB:\fIss\fR]]
 147 .RE
 148 .IP
 149 The minutes
 150 .RI ( mm )
 151 and seconds
 152 .RI ( ss )
 153 are optional.  The hour
 154 .RI ( hh )
 155 is required and may be a single digit.  The
 156 .I offset
 157 following
 158 .I std
 159 is required.  If no
 160 .I offset
 161 follows
 162 .IR dst ,
 163 summer time is assumed to be one hour ahead of standard time.  One or
 164 more digits may be used; the value is always interpreted as a decimal
 165 number.  The hour must be between zero and 24, and the minutes (and
 166 seconds) \*(en if present \*(en between zero and 59.  If preceded by a
 167 .q "\*-" ,
 168 the time zone shall be east of the Prime Meridian; otherwise it shall be
 169 west (which may be indicated by an optional preceding
 170 .q "+" .
 171 .TP
 172 .I rule
 173 Indicates when to change to and back from summer time.  The
 174 .I rule
 175 has the form:
 176 .RS
 177 .IP
 178 \fIdate\fB/\fItime\fB,\fIdate\fB/\fItime\fR
 179 .RE
 180 .IP
 181 where the first
 182 .I date
 183 describes when the change from standard to summer time occurs and the
 184 second
 185 .I date
 186 describes when the change back happens.  Each
 187 .I time
 188 field describes when, in current local time, the change to the other
 189 time is made.
 190 As an extension to POSIX, daylight saving is assumed to be in effect
 191 all year if it begins January 1 at 00:00 and ends December 31 at
 192 24:00 plus the difference between daylight saving and standard time,
 193 leaving no room for standard time in the calendar.
 194 .IP
 195 The format of
 196 .I date
 197 is one of the following:
 198 .RS
 199 .TP 10
 200 .BI J n
 201 The Julian day
 202 .I n
 203 .RI "(1\ \(<=" "\ n\ " "\(<=\ 365).
 204 Leap days are not counted; that is, in all years \*(en including leap
 205 years \*(en February 28 is day 59 and March 1 is day 60.  It is
 206 impossible to explicitly refer to the occasional February 29.
 207 .TP
 208 .I n
 209 The zero-based Julian day
 210 .RI "(0\ \(<=" "\ n\ " "\(<=\ 365).
 211 Leap days are counted, and it is possible to refer to February 29.
 212 .TP
 213 .BI M m . n . d
 214 The
 215 .IR d' th
 216 day
 217 .RI "(0\ \(<=" "\ d\ " "\(<=\ 6)
 218 of week
 219 .I n
 220 of month
 221 .I m
 222 of the year
 223 .RI "(1\ \(<=" "\ n\ " "\(<=\ 5,
 224 .RI "1\ \(<=" "\ m\ " "\(<=\ 12,
 225 where week 5 means
 226 .q "the last \fId\fP day in month \fIm\fP"
 227 which may occur in either the fourth or the fifth week).  Week 1 is the
 228 first week in which the
 229 .IR d' th
 230 day occurs.  Day zero is Sunday.
 231 .RE
 232 .IP "" 15
 233 The
 234 .I time
 235 has the same format as
 236 .I offset
 237 except that POSIX does not allow a leading sign (\c
 238 .q "\*-"
 239 or
 240 .q "+" ).
 241 As an extension to POSIX, the hours part of
 242 .I time
 243 can range from \-167 through 167; this allows for unusual rules such
 244 as
 245 .q "the Saturday before the first Sunday of March" .
 246 The default, if
 247 .I time
 248 is not given, is
 249 .BR 02:00:00 .
 250 .RE
 251 .LP
 252 Here are some examples of
 253 .B TZ
 254 values that directly specify the time zone rules; they use some of the
 255 extensions to POSIX.
 256 .TP
 257 .B EST5
 258 stands for US Eastern Standard
 259 Time (EST), 5 hours behind UTC, without daylight saving.
 260 .TP
 261 .B FJT\*-12FJST,M11.1.0,M1.3.4/75
 262 stands for Fiji Time (FJT) and Fiji Summer Time (FJST), 12 hours ahead
 263 of UTC, springing forward on November's first Sunday at 02:00, and
 264 falling back on January's third Thursday at 75:00 (i.e., 03:00 on the
 265 first Sunday on or after January 18).
 266 .TP
 267 .B IST\*-2IDT,M3.4.4/26,M10.5.0
 268 stands for Israel Standard Time (IST) and Israel Daylight Time (IDT),
 269 2 hours ahead of UTC, springing forward on March's fourth
 270 Thursday at 26:00 (i.e., 02:00 on the first Friday on or after March
 271 23), and falling back on October's last Sunday at 02:00.
 272 .TP
 273 .B WART4WARST,J1/0,J365/25
 274 stands for Western Argentina Summer Time (WARST), 3 hours behind UTC.
 275 There is a dummy fall-back transition on December 31 at 25:00 daylight
 276 saving time (i.e., 24:00 standard time, equivalent to January 1 at
 277 00:00 standard time), and a simultaneous spring-forward transition on
 278 January 1 at 00:00 standard time, so daylight saving time is in effect
 279 all year and the initial
 280 .B WART
 281 is a placeholder.
 282 .TP
 283 .B WGT3WGST,M3.5.0/\*-2,M10.5.0/\*-1
 284 stands for Western Greenland Time (WGT) and Western Greenland Summer
 285 Time (WGST), 3 hours behind UTC, where clocks follow the EU rules of
 286 springing forward on March's last Sunday at 01:00 UTC (\-02:00 local
 287 time) and falling back on October's last Sunday at 01:00 UTC
 288 (\-01:00 local time).
 289 .PP
 290 If no
 291 .I rule
 292 is present in
 293 .BR TZ ,
 294 the rules specified
 295 by the
 296 .IR tzfile (5)-format
 297 file
 298 .B posixrules
 299 in the system time conversion information directory are used, with the
 300 standard and summer time offsets from UTC replaced by those specified by
 301 the
 302 .I offset
 303 values in
 304 .BR TZ .
 305 .PP
 306 For compatibility with System V Release 3.1, a semicolon
 307 .RB ( ; )
 308 may be used to separate the
 309 .I rule
 310 from the rest of the specification.
 311 .SH FILES
 312 .ta \w'/usr/local/etc/zoneinfo/posixrules\0\0'u
 313 /usr/local/etc/zoneinfo time zone information directory
 314 .br
 315 /usr/local/etc/zoneinfo/localtime       local time zone file
 316 .br
 317 /usr/local/etc/zoneinfo/posixrules      used with POSIX-style TZ's
 318 .br
 319 /usr/local/etc/zoneinfo/GMT     for UTC leap seconds
 320 .sp
 321 If
 322 .B /usr/local/etc/zoneinfo/GMT
 323 is absent,
 324 UTC leap seconds are loaded from
 325 .BR /usr/local/etc/zoneinfo/posixrules .
 326 .SH SEE ALSO
 327 getenv(3),
 328 newctime(3),
 329 newstrftime(3),
 330 time(2),
 331 tzfile(5)
 332 .\" This file is in the public domain, so clarified as of
 333 .\" 2009-05-17 by Arthur David Olson.