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