1.\" $NetBSD: tzset.3,v 1.26 2013/09/20 19:06:54 christos Exp $ 2.Dd September 20, 2013 3.Dt TZSET 3 4.Os 5.Sh NAME 6.Nm tzset 7.Nd initialize time conversion information 8.Sh LIBRARY 9.Lb libc 10.Sh SYNOPSIS 11.In time.h 12.Ft void 13.Fn tzset "void" 14.Sh DESCRIPTION 15The 16.Fn tzset 17function uses the value of the environment variable 18.Ev TZ 19to set time conversion information used by 20.Xr localtime 3 . 21If 22.Ev TZ 23does not appear in the environment, 24the best available approximation to local wall clock time, as 25specified by the 26.Xr tzfile 5 27format file 28.Pa /etc/localtime 29is used by 30.Xr localtime 3 . 31If 32.Ev TZ 33appears in the environment but its value is a null string, 34Universal Time (UT) is used, with the abbreviation 35.Dq UTC 36and without leap second correction; please see 37.Xr ctime 3 . 38If 39.Ev TZ 40appears in the environment and its value is not a null string: 41.Bl -dash 42.It 43if the value begins with a colon, it is used as a pathname of a file 44from which to read the time conversion information; 45.It 46if the value does not begin with a colon, it is first used as the 47pathname of a file from which to read the time conversion information, 48and, if that file cannot be read, is used directly as a specification 49of the time conversion information. 50.El 51.Pp 52When 53.Ev TZ 54is used as a pathname, if it begins with a slash, it is used as an 55absolute pathname; otherwise, it is used as a pathname relative to 56.Pa /usr/share/zoneinfo . 57The file must be in the format specified in 58.Xr tzfile 5 . 59.Pp 60When 61.Ev TZ 62is used directly as a specification of the time conversion information, 63it must have the following syntax (spaces inserted for clarity): 64.Sm off 65.Bd -literal -offset indent 66.Cm std Cm offset Oo 67.Cm dst Oo 68.Cm offset Oc Oo 69.No , Cm rule Oc Oc 70.Ed 71.Sm on 72.Pp 73where: 74.Bl -tag -width "std and dst" -compact 75.It Cm std No and Cm dst 76Three or more bytes that are the designation for the standard 77.Cm ( std ) 78or summer 79.Cm ( dst ) 80time zone. 81Only 82.Cm std 83is required; if 84.Cm dst 85is missing, then summer time does not apply in this locale. 86Upper- and lowercase letters are explicitly allowed. 87Any characters except a leading colon (:), digits, comma (,), minus (-), 88plus (+), and ASCII NUL are allowed. 89.It Cm offset 90Indicates the value one must add to the local time to arrive at 91Coordinated Universal Time. 92The 93.Cm offset 94has the form: 95.Sm off 96.Bd -literal -offset indent 97.Cm hh Oo 98.Cm :mm Oo 99.Cm :ss Oc Oc 100.Ed 101.Sm on 102.Pp 103The minutes 104.Cm ( mm ) 105and seconds 106.Cm ( ss ) 107are optional. 108The hour 109.Cm ( hh ) 110is required and may be a single digit. 111The 112.Cm offset 113following 114.Cm std 115is required. 116If no 117.Cm offset 118follows 119.Cm dst , 120summer time is assumed to be one hour ahead of standard time. 121One or more digits may be used; the value is always interpreted as a 122decimal number. 123The hour must be between zero and 24, and the minutes (and 124seconds) \(em if present \(em between zero and 59. 125If preceded by a 126.Dq - 127the time zone shall be east of the Prime Meridian; otherwise it shall be 128west (which may be indicated by an optional preceding 129.Dq + ) . 130.It Cm rule 131Indicates when to change to and back from summer time. 132The 133.Cm rule 134has the form: 135.Sm off 136.Bd -literal -offset indent 137.Xo 138.Cm date No / 139.Cm time No , 140.Cm date No / 141.Cm time 142.Xc 143.Ed 144.Sm on 145.Pp 146where the first 147.Cm date 148describes when the change from standard to summer time occurs and the 149second 150.Cm date 151describes when the change back happens. 152Each 153.Cm time 154field describes when, in current local time, the change to the other 155time is made. 156As an extension to POSIX, daylight saving is assumed to be in effect 157all year if it begins January 1 at 00:00 and ends December 31 at 15824:00 plus the difference between daylight saving and standard time, 159leaving no room for standard time in the calendar. 160The format of 161.Fa date 162is one of the following: 163.Bl -tag -width "The Julian day" -compact 164.It Cm J Ns Ar n 165The Julian day 166.Ar n 167(1 \*[Le] 168.Ar n 169\*[Le] 365). 170Leap days are not counted; that is, in all years \(em including leap 171years \(em February 28 is day 59 and March 1 is day 60. 172It is impossible to explicitly refer to the occasional February 29. 173.It Ar n 174The zero-based Julian day (0\ \*[Le] 175.Ar n 176\*[Le]\ 365). 177Leap days are counted, and it is possible to refer to 178February 29. 179.Sm off 180.It Cm M Ns Ar m No . Ar n No . Ar d 181.Sm on 182The 183.Ar d Ns 'th 184day 185(0 \*[Le] 186.Ar d 187\*[Le]\ 6) of week 188.Ar n 189of month 190.Ar m 191of the year 192(1 \*[Le] 193.Ar n 194\*[Le]\ 5, 1 \*[Le] 195.Ar m 196\*[Le]\ 12, where week 5 means 197.Dq the\ last Ar d No day\ in\ month Ar m 198which may occur in either the fourth or the fifth week). 199Week 1 is the first week in which the 200.Ar d Ns 'th 201day occurs. 202Day zero is Sunday. 203.El 204The 205.Cm time 206has the same format as 207.Cm offset 208except that POSIX does not allow a leading sign 209.Dq - 210or 211.Dq + 212is allowed. 213As an extension to POSIX, the hours part of 214.Cm time 215can range from \(mi167 through 167; this allows for unusual rules such as 216.Dq the Saturday before the first Sunday of March . 217The default, if 218.Cm time 219is not given, is 220.Cm 02:00:00 . 221.El 222.Pp 223Here are some examples of 224.Va TZ 225values that directly specify the time zone rules; they use some of the 226extensions to POSIX. 227.Bl -tag 228.It EST5 229stands for US eastern 230time (EST), 5 hours behind UTC, without daylight saving. 231.It FJT\(mi12FJST,M10.3.1/146,M1.3.4/75 232stands for Fiji Time (FJT) and Fiji Summer Time (FJST), 12 hours ahead 233of UTC, springing forward on October's third Monday at 234146:00 (i.e., 02:00 on the first Sunday on or after October 21), and 235falling back on January's third Thursday at 75:00 (i.e., 03:00 on the 236first Sunday on or after January 18). 237.It IST\(mi2IDT,M3.4.4/26,M10.5.0 238stands for Israel Standard Time (IST) and Israel Daylight Time (IDT), 2392 hours ahead of UTC, springing forward on March's fourth 240Tuesday at 26:00 (i.e., 02:00 on the first Friday on or after March 24123), and falling back on October's last Sunday at 02:00. 242.It WART4WARST,J1/0,J365/25 243stands for Western Argentina Summer Time (WARST), 3 hours behind UTC. 244There is a dummy fall-back transition on December 31 at 25:00 daylight 245saving time (i.e., 24:00 standard time, equivalent to January 1 at 24600:00 standard time), and a simultaneous spring-forward transition on 247January 1 at 00:00 standard time, so daylight saving time is in effect 248all year and the initial 249.Em WART 250is a placeholder. 251.It WGT3WGST,M3.5.0/\(mi2,M10.5.0/\(mi1 252stands for Western Greenland time (WGT) and Western Greenland Summer 253Time (WGST), 3 hours behind UTC, where clocks follow the EU rules of 254springing forward on March's last Sunday at 01:00 UTC (\(mi02:00 local 255time) and falling back on October's last Sunday at 01:00 UTC 256(\(mi01:00 local time). 257.El 258.Pp 259If no 260.Cm rule 261is present in 262.Ev TZ , 263the rules specified by the 264.Xr tzfile 5 265format file 266.Pa posixrules 267in 268.Pa /usr/share/zoneinfo 269are used, with the standard and summer time offsets from UTC replaced 270by those specified by the 271.Cm offset 272values in 273.Ev TZ . 274.Pp 275For compatibility with System V Release 3.1, a semicolon (;) may be 276used to separate the 277.Cm rule 278from the rest of the specification. 279.Pp 280If the 281.Ev TZ 282environment variable does not specify a 283.Xr tzfile 5 284format file and cannot be interpreted as a direct specification, UTC 285is used. 286.Sh FILES 287.Bl -tag -width /usr/share/zoneinfo/posixrules -compact 288.It Pa /etc/localtime 289local time zone file 290.It Pa /usr/share/zoneinfo 291time zone information directory 292.It Pa /usr/share/zoneinfo/posixrules 293used with POSIX-style TZ's 294.It Pa /usr/share/zoneinfo/GMT 295for UTC leap seconds 296.El 297.Pp 298If 299.Pa /usr/share/zoneinfo/GMT 300is absent, UTC leap seconds are loaded from 301.Pa /usr/share/zoneinfo/posixrules . 302.Sh SEE ALSO 303.Xr ctime 3 , 304.Xr getenv 3 , 305.Xr strftime 3 , 306.Xr time 3 , 307.Xr tzfile 5 308.Sh STANDARDS 309The 310.Fn tzset 311function conforms to 312.St -p1003.1-88 . 313.\" @(#)newtzset.3 8.2 314.\" This file is in the public domain, so clarified as of 315.\" 2009-05-17 by Arthur David Olson. 316