1.\" $NetBSD: tzset.3,v 1.42 2019/07/03 15:50:16 christos Exp $ 2.Dd July 2, 2019 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 timezone 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] . 92The return values for both 93.Fn tzgetname 94and 95.Fn tzgmtoff 96correspond to the latest time for which data is available, even if that 97refers to a future time. 98Finally, the 99.Fn tzgetgmtoff 100function acts like 101.Fn tzgetname 102only it returns the offset in seconds from GMT for the timezone. 103If there is no match, then 104.Dv \-1 105is returned and 106.Va errno 107is set to 108.Dv ESRCH . 109The 110.Fn tzset 111function acts like 112.Dv tzalloc(getenv("TZ")) , 113except it saves any resulting timezone object into internal 114storage that is accessed by 115.Fn localtime , 116.Fn localtime_r , 117and 118.Fn mktime . 119The anonymous shared timezone object is freed by the next call to 120.Fn tzset . 121If the implied call to 122.Fn tzalloc 123fails, 124.Fn tzset 125falls back on Universal Time (UT). 126If 127.Ev TZ 128is 129.Dv NULL , 130the best available approximation to local (wall clock) time, as 131specified by the 132.Xr tzfile 5 133format file 134.Pa /etc/localtime 135is used by 136.Xr localtime 3 . 137If 138.Ev TZ 139appears in the environment but its value is the empty string, 140UT is used, with the abbreviation 141.Dq UTC 142and without leap second correction; please see 143.Xr ctime 3 . 144If 145.Ev TZ 146is nonnull and nonempty: 147.Bl -dash 148.It 149if the value begins with a colon, it is used as a pathname of a file 150from which to read the time conversion information; 151.It 152if the value does not begin with a colon, it is first used as the 153pathname of a file from which to read the time conversion information, 154and, if that file cannot be read, is used directly as a specification 155of the time conversion information. 156.El 157.Pp 158When 159.Ev TZ 160is used as a pathname, if it begins with a slash, it is used as an 161absolute pathname; otherwise, it is used as a pathname relative to 162.Pa /usr/share/zoneinfo . 163The file must be in the format specified in 164.Xr tzfile 5 . 165.Pp 166When 167.Ev TZ 168is used directly as a specification of the time conversion information, 169it must have the following syntax (spaces inserted for clarity): 170.Sm off 171.Bd -literal -offset indent 172.Cm std Cm offset Oo Cm dst Oo Cm offset Oc Oo , Cm rule Oc Oc 173.Ed 174.Sm on 175.Pp 176where: 177.Bl -tag -width "std and dst" -compact 178.It Cm std No and Cm dst 179Three or more bytes that are the designation for the standard 180.Cm ( std ) 181or the alternative 182.Cm ( dst 183such as daylight saving time) 184timezone. 185Only 186.Cm std 187is required; if 188.Cm dst 189is missing, then daylight saving time does not apply in this locale. 190Upper- and lowercase letters are explicitly allowed. 191Any characters except a leading colon (:), digits, comma (,), minus (-), 192plus (+), and NUL bytes are allowed. 193Alternatively, a designation can be surrounded by angle brackets 194.Dv < 195and 196.Dv > ; 197in this case, the designation can contain any characters other than 198.Dv > 199and 200.Dv NUL . 201.It Cm offset 202Indicates the value one must add to the local time to arrive at 203Coordinated Universal Time. 204The 205.Cm offset 206has the form: 207.Sm off 208.Bd -literal -offset indent 209.Cm hh Oo 210.Cm :mm Oo 211.Cm :ss Oc Oc 212.Ed 213.Sm on 214.Pp 215The minutes 216.Cm ( mm ) 217and seconds 218.Cm ( ss ) 219are optional. 220The hour 221.Cm ( hh ) 222is required and may be a single digit. 223The 224.Cm offset 225following 226.Cm std 227is required. 228If no 229.Cm offset 230follows 231.Cm dst , 232daylight saving time is assumed to be one hour ahead of standard time. 233One or more digits may be used; the value is always interpreted as a 234decimal number. 235The hour must be between zero and 24, and the minutes (and 236seconds) \(en if present \(en between zero and 59. 237If preceded by a 238.Dq - 239the timezone shall be east of the Prime Meridian; otherwise it shall be 240west (which may be indicated by an optional preceding 241.Dq + ) . 242.It Cm rule 243Indicates when to change to and back from daylight saving time. 244The 245.Cm rule 246has the form: 247.Sm off 248.Bd -literal -offset indent 249.Xo 250.Cm date No / 251.Cm time , 252.Cm date No / 253.Cm time 254.Xc 255.Ed 256.Sm on 257.Pp 258where the first 259.Cm date 260describes when the change from standard to daylight saving time occurs and the 261second 262.Cm date 263describes when the change back happens. 264Each 265.Cm time 266field describes when, in current local time, the change to the other 267time is made. 268As an extension to POSIX, daylight saving is assumed to be in effect 269all year if it begins January 1 at 00:00 and ends December 31 at 27024:00 plus the difference between daylight saving and standard time, 271leaving no room for standard time in the calendar. 272The format of 273.Fa date 274is one of the following: 275.Bl -tag -width "The Julian day" -compact 276.It Cm J Ns Ar n 277The Julian day 278.Ar n 279(1 \*[Le] 280.Ar n 281\*[Le] 365). 282Leap days are not counted; that is, in all years \(en including leap 283years \(en February 28 is day 59 and March 1 is day 60. 284It is impossible to explicitly refer to the occasional February 29. 285.It Ar n 286The zero-based Julian day (0\ \*[Le] 287.Ar n 288\*[Le]\ 365). 289Leap days are counted, and it is possible to refer to 290February 29. 291.Sm off 292.It Cm M Ns Ar m . Ar n . Ar d 293.Sm on 294The 295.Ar d Ns 'th 296day 297(0 \*[Le] 298.Ar d 299\*[Le]\ 6) of week 300.Ar n 301of month 302.Ar m 303of the year 304(1 \*[Le] 305.Ar n 306\*[Le]\ 5, 1 \*[Le] 307.Ar m 308\*[Le]\ 12, where week 5 means 309.Dq the\ last Ar d No day\ in\ month Ar m 310which may occur in either the fourth or the fifth week). 311Week 1 is the first week in which the 312.Ar d Ns 'th 313day occurs. 314Day zero is Sunday. 315.El 316The 317.Cm time 318has the same format as 319.Cm offset 320except that POSIX does not allow a leading sign 321.Dq - 322or 323.Dq + 324is allowed. 325As an extension to POSIX, the hours part of 326.Cm time 327can range from \-167 through 167; this allows for unusual rules such as 328.Dq the Saturday before the first Sunday of March . 329The default, if 330.Cm time 331is not given, is 332.Cm 02:00:00 . 333.El 334.Pp 335Here are some examples of 336.Va TZ 337values that directly specify the timezone rules; they use some of the 338extensions to POSIX. 339.Bl -tag -width 6n 340.It EST5 341stands for US Eastern Standard 342Time (EST), 5 hours behind UT, without daylight saving. 343.It FJT\-12FJST,M11.1.0,M1.3.4/75 344.It <+12>\-12<+13>,M11.1.0,M1.2.1/147 345stands for Fiji time, 12 hours ahead 346of UT, springing forward on November's first Sunday at 02:00, and 347falling back on January's second Monday at 147:00 (i.e., 03:00 on the 348first Sunday on or after January 14). 349The abbreviations for standard and daylight saving time are 350.Qq +12 351and 352.Qq +13 . 353.It IST\-2IDT,M3.4.4/26,M10.5.0 354stands for Israel Standard Time (IST) and Israel Daylight Time (IDT), 3552 hours ahead of UT, springing forward on March's fourth 356Thursday at 26:00 (i.e., 02:00 on the first Friday on or after March 35723), and falling back on October's last Sunday at 02:00. 358.It <\-04>4<\-03>,J1/0,J365/25 359stands for permanent daylight saving time, 3 hours behind UT with 360abbreviation 361.Qq \-03 . 362There is a dummy fall-back transition on December 31 at 25:00 daylight 363saving time (i.e., 24:00 standard time, equivalent to January 1 at 36400:00 standard time), and a simultaneous spring-forward transition on 365January 1 at 00:00 standard time, so daylight saving time is in effect 366all year and the initial 367.Em <\-04> 368is a placeholder. 369.It <\-03>3<\-02>,M3.5.0/\-2,M10.5.0/\-1 370stands for time in western Greenland, 3 hours behind UT, where clocks 371follow the EU rules of 372springing forward on March's last Sunday at 01:00 UT (\-02:00 local 373time, i.e., 22:00 the previous day) and falling back on October's last 374Sunday at 01:00 UT (\-01:00 local time, i.e., 23:00 the previous day). 375The abbreviations for standard and daylight saving time are 376.Qq \-03 377and 378.Qq \-02 . 379.El 380.Pp 381If no 382.Cm rule 383is present in 384.Ev TZ , 385the rules specified by the 386.Xr tzfile 5 387format file 388.Pa posixrules 389in 390.Pa /usr/share/zoneinfo 391are used, with the standard and daylight saving time offsets from UT replaced 392by those specified by the 393.Cm offset 394values in 395.Ev TZ . 396.Pp 397For compatibility with System V Release 3.1, a semicolon (;) may be 398used to separate the 399.Cm rule 400from the rest of the specification. 401.Sh FILES 402.Bl -tag -width /usr/share/zoneinfo/posixrules -compact 403.It Pa /etc/localtime 404local timezone file 405.It Pa /usr/share/zoneinfo 406local timezone information directory 407.\" .It Pa /usr/share/zoneinfo/localtime 408.\" local timezone file 409.It Pa /usr/share/zoneinfo/posixrules 410used with POSIX-style TZ's 411.It Pa /usr/share/zoneinfo/GMT 412for UTC leap seconds 413.El 414.Pp 415If 416.Pa /usr/share/zoneinfo/GMT 417is absent, UTC leap seconds are loaded from 418.Pa /usr/share/zoneinfo/posixrules . 419.Sh SEE ALSO 420.Xr ctime 3 , 421.Xr getenv 3 , 422.Xr strftime 3 , 423.Xr time 3 , 424.Xr tzfile 5 425.Sh STANDARDS 426The 427.Fn tzset 428function conforms to 429.St -p1003.1-88 . 430.Sh BUGS 431Neither the 432.Fn tzgetname 433nor 434.Fn tzgmtoff 435functions have the ability to specify the point in time for which the 436requested data should be returned. 437.\" @(#)newtzset.3 8.2 438.\" This file is in the public domain, so clarified as of 439.\" 2009-05-17 by Arthur David Olson. 440