1.\" $NetBSD: tzset.3,v 1.37 2018/01/25 22:48:42 christos Exp $ 2.Dd January 25, 2018 3.Dt TZSET 3 4.Os 5.Sh NAME 6.Nm tzset , 7.Nm tzalloc , 8.Nm tzgetname , 9.Nm tzgetgmtoff , 10.Nm tzfree 11.Nd initialize time conversion information 12.Sh LIBRARY 13.Lb libc 14.Sh SYNOPSIS 15.In time.h 16.Ft timezone_t 17.Fn tzalloc "const char *zone" 18.Ft void 19.Fn tzfree "timezone_t restrict tz" 20.Ft const char * 21.Fn tzgetname "timezone_t restrict tz" "int isdst" 22.Ft long 23.Fn tzgetgmtoff "timezone_t restrict tz" "int isdst" 24.Ft void 25.Fn tzset "void" 26.Sh DESCRIPTION 27The 28.Fn tzalloc 29function takes as an argument a timezone name and returns a 30.Ft timezone_t 31object suitable to be used in the 32.Fn ctime_rz , 33.Fn localtime_rz , 34and 35.Fn mktime_z 36functions. 37.Pp 38If 39.Ar tz 40is not a valid time zone description, or if the object cannot be allocated, 41.Fn tzalloc 42returns a 43.Dv NULL 44pointer and sets 45.Va errno . 46.Pp 47A 48.Dv NULL 49pointer may be passed to 50.Fn tzalloc 51instead of a timezone name, to refer to the current system timezone. 52An empty timezone string indicates Coordinated Universal Time 53.Pq Tn UTC . 54.Pp 55Note that instead of setting the environment variable 56.Va TZ , 57and globally changing the behavior of the calling program, one can use 58multiple timezones at the same time by using separate 59.Ft timezone_t 60objects allocated by 61.Fn tzalloc 62and calling the 63.Dq z 64variants of the functions. 65The 66.Fn tzfree 67function deallocates 68.Fa tz , 69which was previously allocated by 70.Fn tzalloc . 71This invalidates any 72.Ft tm_zone 73pointers that 74.Fa tz 75was used to set. 76The function 77.Fn tzgetname 78returns the name for the given 79.Fa tz . 80If 81.Fa isdst 82is 83.Va 0 , 84the call is equivalent to 85.Va tzname[0] . 86If 87.Fa isdst 88is set to 89.Va 1 90the call is equivalent to 91.Va tzname[1] . 92Finally, the 93.Fn tzgetgmtoff 94function acts like 95.Fn tzgetname 96only it returns the offset in seconds from GMT for the timezone. 97If there is no match, then 98.Dv \-1 99is returned and 100.Va errno 101is set to 102.Dv ESRCH . 103The 104.Fn tzset 105function acts like 106.Dv tzalloc(getenv("TZ")) , 107except it saves any resulting time zone object into internal 108storage that is accessed by 109.Fn localtime , 110.Fn localtime_r , 111and 112.Fn mktime . 113The anonymous shared time zone object is freed by the next call to 114.Fn tzset . 115If the implied call to 116.Fn tzalloc 117fails, 118.Fn tzset 119falls back on Universal Time (UT). 120If 121.Ev TZ 122is 123.Dv NULL , 124the best available approximation to local wall clock time, as 125specified by the 126.Xr tzfile 5 127format file 128.Pa /etc/localtime 129is used by 130.Xr localtime 3 . 131If 132.Ev TZ 133appears in the environment but its value is the empty string, 134UT is used, with the abbreviation 135.Dq UTC 136and without leap second correction; please see 137.Xr ctime 3 . 138If 139.Ev TZ 140is nonnull and nonempty: 141.Bl -dash 142.It 143if the value begins with a colon, it is used as a pathname of a file 144from which to read the time conversion information; 145.It 146if the value does not begin with a colon, it is first used as the 147pathname of a file from which to read the time conversion information, 148and, if that file cannot be read, is used directly as a specification 149of the time conversion information. 150.El 151.Pp 152When 153.Ev TZ 154is used as a pathname, if it begins with a slash, it is used as an 155absolute pathname; otherwise, it is used as a pathname relative to 156.Pa /usr/share/zoneinfo . 157The file must be in the format specified in 158.Xr tzfile 5 . 159.Pp 160When 161.Ev TZ 162is used directly as a specification of the time conversion information, 163it must have the following syntax (spaces inserted for clarity): 164.Sm off 165.Bd -literal -offset indent 166.Cm std Cm offset Oo 167.Cm dst Oo 168.Cm offset Oc Oo 169.No , Cm rule Oc Oc 170.Ed 171.Sm on 172.Pp 173where: 174.Bl -tag -width "std and dst" -compact 175.It Cm std No and Cm dst 176Three or more bytes that are the designation for the standard 177.Cm ( std ) 178or summer 179.Cm ( dst ) 180time zone. 181Only 182.Cm std 183is required; if 184.Cm dst 185is missing, then summer time does not apply in this locale. 186Upper- and lowercase letters are explicitly allowed. 187Any characters except a leading colon (:), digits, comma (,), minus (-), 188plus (+), and NUL bytes are allowed. 189Alternatively, a designation can be surrounded by angle brackets 190.Dv < 191and 192.Dv > ; 193in this case, the designation can contain any characters other than 194.Dv > 195and 196.Dv NUL . 197.It Cm offset 198Indicates the value one must add to the local time to arrive at 199Coordinated Universal Time. 200The 201.Cm offset 202has the form: 203.Sm off 204.Bd -literal -offset indent 205.Cm hh Oo 206.Cm :mm Oo 207.Cm :ss Oc Oc 208.Ed 209.Sm on 210.Pp 211The minutes 212.Cm ( mm ) 213and seconds 214.Cm ( ss ) 215are optional. 216The hour 217.Cm ( hh ) 218is required and may be a single digit. 219The 220.Cm offset 221following 222.Cm std 223is required. 224If no 225.Cm offset 226follows 227.Cm dst , 228summer time is assumed to be one hour ahead of standard time. 229One or more digits may be used; the value is always interpreted as a 230decimal number. 231The hour must be between zero and 24, and the minutes (and 232seconds) \*(en if present \*(en between zero and 59. 233If preceded by a 234.Dq - 235the time zone shall be east of the Prime Meridian; otherwise it shall be 236west (which may be indicated by an optional preceding 237.Dq + ) . 238.It Cm rule 239Indicates when to change to and back from summer time. 240The 241.Cm rule 242has the form: 243.Sm off 244.Bd -literal -offset indent 245.Xo 246.Cm date No / 247.Cm time No , 248.Cm date No / 249.Cm time 250.Xc 251.Ed 252.Sm on 253.Pp 254where the first 255.Cm date 256describes when the change from standard to summer time occurs and the 257second 258.Cm date 259describes when the change back happens. 260Each 261.Cm time 262field describes when, in current local time, the change to the other 263time is made. 264As an extension to POSIX, daylight saving is assumed to be in effect 265all year if it begins January 1 at 00:00 and ends December 31 at 26624:00 plus the difference between daylight saving and standard time, 267leaving no room for standard time in the calendar. 268The format of 269.Fa date 270is one of the following: 271.Bl -tag -width "The Julian day" -compact 272.It Cm J Ns Ar n 273The Julian day 274.Ar n 275(1 \*[Le] 276.Ar n 277\*[Le] 365). 278Leap days are not counted; that is, in all years \*(en including leap 279years \*(en February 28 is day 59 and March 1 is day 60. 280It is impossible to explicitly refer to the occasional February 29. 281.It Ar n 282The zero-based Julian day (0\ \*[Le] 283.Ar n 284\*[Le]\ 365). 285Leap days are counted, and it is possible to refer to 286February 29. 287.Sm off 288.It Cm M Ns Ar m No . Ar n No . Ar d 289.Sm on 290The 291.Ar d Ns 'th 292day 293(0 \*[Le] 294.Ar d 295\*[Le]\ 6) of week 296.Ar n 297of month 298.Ar m 299of the year 300(1 \*[Le] 301.Ar n 302\*[Le]\ 5, 1 \*[Le] 303.Ar m 304\*[Le]\ 12, where week 5 means 305.Dq the\ last Ar d No day\ in\ month Ar m 306which may occur in either the fourth or the fifth week). 307Week 1 is the first week in which the 308.Ar d Ns 'th 309day occurs. 310Day zero is Sunday. 311.El 312The 313.Cm time 314has the same format as 315.Cm offset 316except that POSIX does not allow a leading sign 317.Dq - 318or 319.Dq + 320is allowed. 321As an extension to POSIX, the hours part of 322.Cm time 323can range from \-167 through 167; this allows for unusual rules such as 324.Dq the Saturday before the first Sunday of March . 325The default, if 326.Cm time 327is not given, is 328.Cm 02:00:00 . 329.El 330.Pp 331Here are some examples of 332.Va TZ 333values that directly specify the time zone rules; they use some of the 334extensions to POSIX. 335.Bl -tag 336.It EST5 337stands for US Eastern Standard 338Time (EST), 5 hours behind UT, without daylight saving. 339.It FJT\-12FJST,M11.1.0,M1.3.4/75 340stands for Fiji Time (FJT) and Fiji Summer Time (FJST), 12 hours ahead 341of UT, springing forward on November's first Sunday at 02:00, and 342falling back on January's third Thursday at 75:00 (i.e., 03:00 on the 343first Sunday on or after January 18). 344.It IST\-2IDT,M3.4.4/26,M10.5.0 345stands for Israel Standard Time (IST) and Israel Daylight Time (IDT), 3462 hours ahead of UT, springing forward on March's fourth 347Thursday at 26:00 (i.e., 02:00 on the first Friday on or after March 34823), and falling back on October's last Sunday at 02:00. 349.It WART4WARST,J1/0,J365/25 350stands for Western Argentina Summer Time (WARST), 3 hours behind UT. 351There is a dummy fall-back transition on December 31 at 25:00 daylight 352saving time (i.e., 24:00 standard time, equivalent to January 1 at 35300:00 standard time), and a simultaneous spring-forward transition on 354January 1 at 00:00 standard time, so daylight saving time is in effect 355all year and the initial 356.Em WART 357is a placeholder. 358.It WGT3WGST,M3.5.0/\-2,M10.5.0/\-1 359stands for Western Greenland Time (WGT) and Western Greenland Summer 360Time (WGST), 3 hours behind UT, where clocks follow the EU rules of 361springing forward on March's last Sunday at 01:00 UT (\-02:00 local 362time) and falling back on October's last Sunday at 01:00 UT 363(\-01:00 local time). 364.El 365.Pp 366If no 367.Cm rule 368is present in 369.Ev TZ , 370the rules specified by the 371.Xr tzfile 5 372format file 373.Pa posixrules 374in 375.Pa /usr/share/zoneinfo 376are used, with the standard and summer time offsets from UT replaced 377by those specified by the 378.Cm offset 379values in 380.Ev TZ . 381.Pp 382For compatibility with System V Release 3.1, a semicolon (;) may be 383used to separate the 384.Cm rule 385from the rest of the specification. 386.Sh FILES 387.Bl -tag -width /usr/share/zoneinfo/posixrules -compact 388.It Pa /etc/localtime 389local time zone file 390.It Pa /usr/share/zoneinfo 391time zone information directory 392\" .It Pa /usr/share/zoneinfo/localtime 393\" local time zone file 394.It Pa /usr/share/zoneinfo/posixrules 395used with POSIX-style TZ's 396.It Pa /usr/share/zoneinfo/GMT 397for UTC leap seconds 398.El 399.Pp 400If 401.Pa /usr/share/zoneinfo/GMT 402is absent, UTC leap seconds are loaded from 403.Pa /usr/share/zoneinfo/posixrules . 404.Sh SEE ALSO 405.Xr ctime 3 , 406.Xr getenv 3 , 407.Xr strftime 3 , 408.Xr time 3 , 409.Xr tzfile 5 410.Sh STANDARDS 411The 412.Fn tzset 413function conforms to 414.St -p1003.1-88 . 415.\" @(#)newtzset.3 8.2 416.\" This file is in the public domain, so clarified as of 417.\" 2009-05-17 by Arthur David Olson. 418