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