1.\" $NetBSD: tzset.3,v 1.34 2015/10/29 22:42:55 wiz Exp $ 2.Dd October 29, 2015 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 UTC. 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, 134Universal Time (UT) 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. 189.It Cm offset 190Indicates the value one must add to the local time to arrive at 191Coordinated Universal Time. 192The 193.Cm offset 194has the form: 195.Sm off 196.Bd -literal -offset indent 197.Cm hh Oo 198.Cm :mm Oo 199.Cm :ss Oc Oc 200.Ed 201.Sm on 202.Pp 203The minutes 204.Cm ( mm ) 205and seconds 206.Cm ( ss ) 207are optional. 208The hour 209.Cm ( hh ) 210is required and may be a single digit. 211The 212.Cm offset 213following 214.Cm std 215is required. 216If no 217.Cm offset 218follows 219.Cm dst , 220summer time is assumed to be one hour ahead of standard time. 221One or more digits may be used; the value is always interpreted as a 222decimal number. 223The hour must be between zero and 24, and the minutes (and 224seconds) \*(en if present \*(en between zero and 59. 225If preceded by a 226.Dq - 227the time zone shall be east of the Prime Meridian; otherwise it shall be 228west (which may be indicated by an optional preceding 229.Dq + ) . 230.It Cm rule 231Indicates when to change to and back from summer time. 232The 233.Cm rule 234has the form: 235.Sm off 236.Bd -literal -offset indent 237.Xo 238.Cm date No / 239.Cm time No , 240.Cm date No / 241.Cm time 242.Xc 243.Ed 244.Sm on 245.Pp 246where the first 247.Cm date 248describes when the change from standard to summer time occurs and the 249second 250.Cm date 251describes when the change back happens. 252Each 253.Cm time 254field describes when, in current local time, the change to the other 255time is made. 256As an extension to POSIX, daylight saving is assumed to be in effect 257all year if it begins January 1 at 00:00 and ends December 31 at 25824:00 plus the difference between daylight saving and standard time, 259leaving no room for standard time in the calendar. 260The format of 261.Fa date 262is one of the following: 263.Bl -tag -width "The Julian day" -compact 264.It Cm J Ns Ar n 265The Julian day 266.Ar n 267(1 \*[Le] 268.Ar n 269\*[Le] 365). 270Leap days are not counted; that is, in all years \*(en including leap 271years \*(en February 28 is day 59 and March 1 is day 60. 272It is impossible to explicitly refer to the occasional February 29. 273.It Ar n 274The zero-based Julian day (0\ \*[Le] 275.Ar n 276\*[Le]\ 365). 277Leap days are counted, and it is possible to refer to 278February 29. 279.Sm off 280.It Cm M Ns Ar m No . Ar n No . Ar d 281.Sm on 282The 283.Ar d Ns 'th 284day 285(0 \*[Le] 286.Ar d 287\*[Le]\ 6) of week 288.Ar n 289of month 290.Ar m 291of the year 292(1 \*[Le] 293.Ar n 294\*[Le]\ 5, 1 \*[Le] 295.Ar m 296\*[Le]\ 12, where week 5 means 297.Dq the\ last Ar d No day\ in\ month Ar m 298which may occur in either the fourth or the fifth week). 299Week 1 is the first week in which the 300.Ar d Ns 'th 301day occurs. 302Day zero is Sunday. 303.El 304The 305.Cm time 306has the same format as 307.Cm offset 308except that POSIX does not allow a leading sign 309.Dq - 310or 311.Dq + 312is allowed. 313As an extension to POSIX, the hours part of 314.Cm time 315can range from \-167 through 167; this allows for unusual rules such as 316.Dq the Saturday before the first Sunday of March . 317The default, if 318.Cm time 319is not given, is 320.Cm 02:00:00 . 321.El 322.Pp 323Here are some examples of 324.Va TZ 325values that directly specify the time zone rules; they use some of the 326extensions to POSIX. 327.Bl -tag 328.It EST5 329stands for US Eastern Standard 330Time (EST), 5 hours behind UTC, without daylight saving. 331.It FJT\-12FJST,M11.1.0,M1.3.4/75 332stands for Fiji Time (FJT) and Fiji Summer Time (FJST), 12 hours ahead 333of UTC, springing forward on November's first Sunday at 02:00, and 334falling back on January's third Thursday at 75:00 (i.e., 03:00 on the 335first Sunday on or after January 18). 336.It IST\-2IDT,M3.4.4/26,M10.5.0 337stands for Israel Standard Time (IST) and Israel Daylight Time (IDT), 3382 hours ahead of UTC, springing forward on March's fourth 339Thursday at 26:00 (i.e., 02:00 on the first Friday on or after March 34023), and falling back on October's last Sunday at 02:00. 341.It WART4WARST,J1/0,J365/25 342stands for Western Argentina Summer Time (WARST), 3 hours behind UTC. 343There is a dummy fall-back transition on December 31 at 25:00 daylight 344saving time (i.e., 24:00 standard time, equivalent to January 1 at 34500:00 standard time), and a simultaneous spring-forward transition on 346January 1 at 00:00 standard time, so daylight saving time is in effect 347all year and the initial 348.Em WART 349is a placeholder. 350.It WGT3WGST,M3.5.0/\-2,M10.5.0/\-1 351stands for Western Greenland Time (WGT) and Western Greenland Summer 352Time (WGST), 3 hours behind UTC, where clocks follow the EU rules of 353springing forward on March's last Sunday at 01:00 UTC (\-02:00 local 354time) and falling back on October's last Sunday at 01:00 UTC 355(\-01:00 local time). 356.El 357.Pp 358If no 359.Cm rule 360is present in 361.Ev TZ , 362the rules specified by the 363.Xr tzfile 5 364format file 365.Pa posixrules 366in 367.Pa /usr/share/zoneinfo 368are used, with the standard and summer time offsets from UTC replaced 369by those specified by the 370.Cm offset 371values in 372.Ev TZ . 373.Pp 374For compatibility with System V Release 3.1, a semicolon (;) may be 375used to separate the 376.Cm rule 377from the rest of the specification. 378.Sh FILES 379.Bl -tag -width /usr/share/zoneinfo/posixrules -compact 380.It Pa /etc/localtime 381local time zone file 382.It Pa /usr/share/zoneinfo 383time zone information directory 384.It Pa /usr/share/zoneinfo/posixrules 385used with POSIX-style TZ's 386.It Pa /usr/share/zoneinfo/GMT 387for UTC leap seconds 388.El 389.Pp 390If 391.Pa /usr/share/zoneinfo/GMT 392is absent, UTC leap seconds are loaded from 393.Pa /usr/share/zoneinfo/posixrules . 394.Sh SEE ALSO 395.Xr ctime 3 , 396.Xr getenv 3 , 397.Xr strftime 3 , 398.Xr time 3 , 399.Xr tzfile 5 400.Sh STANDARDS 401The 402.Fn tzset 403function conforms to 404.St -p1003.1-88 . 405.\" @(#)newtzset.3 8.2 406.\" This file is in the public domain, so clarified as of 407.\" 2009-05-17 by Arthur David Olson. 408