1.\" $OpenBSD: tzset.3,v 1.26 2022/10/04 13:33:57 millert Exp $ 2.Dd $Mdocdate: October 4 2022 $ 3.Dt TZSET 3 4.Os 5.Sh NAME 6.Nm tzset , 7.Nm tzsetwall 8.Nd initialize time conversion information 9.Sh SYNOPSIS 10.In time.h 11.Vt extern char *tzname[2]; 12.Vt extern long timezone; 13.Vt extern long daylight; 14.Ft void 15.Fn tzset "void" 16.Ft void 17.Fn tzsetwall "void" 18.Sh DESCRIPTION 19The 20.Fn tzset 21function uses the value of the environment variable 22.Ev TZ 23to set the time conversion information used by 24.Xr localtime 3 . 25It also sets the following external variables: 26.Bl -tag -width "tzname[2]" 27.It Vt tzname[2] 28the designations for standard and daylight saving time; see the description of 29.Ar std No and Ar dst 30below 31.It Vt timezone 32the number of seconds west of UTC 33.It Vt daylight 340 if the time zone has never observed daylight saving time, otherwise 35non-zero 36.El 37.Pp 38Most programs do not need to call 39.Fn tzset 40directly; it will be called automatically as needed by the functions 41described in 42.Xr localtime 3 . 43Privileged processes that use 44.Xr chroot 2 45may wish to call 46.Fn tzset 47to initialize the time conversion information before changing to 48a restricted root directory that does not include time conversion 49data files. 50.Pp 51If 52.Ev TZ 53does not appear in the environment, or if the calling process has 54changed its user or group ID, the system time zone file, 55.Pa /etc/localtime , 56is used. 57.Pp 58If 59.Ev TZ 60appears in the environment it may be one of two formats: 61.Bl -bullet 62.It 63the pathname of a 64.Xr tzfile 5 65format file from which to read the time conversion information, 66optionally prefixed with a colon 67.Pq Ql \&: , 68such as 69.Dq :America/Denver 70or 71.Dq Europe/Berlin 72.It 73a string that directly specifies the time conversion information 74(see below) which may not begin with a colon 75.Pq Ql \&: 76.El 77.Pp 78If 79.Ev TZ 80appears in the environment and its value does not begin with a colon, 81it is first used as the 82pathname of a 83.Xr tzfile 5 84format file from which to read the time conversion information 85and, if that file cannot be read, is used directly as a specification of 86the time conversion information. 87A value beginning with a colon 88.Pq Ql \&: 89is always treated as a pathname. 90.Pp 91If 92.Ev TZ 93is set to the empty string, Coordinated Universal Time (UTC) is 94used (without leap second correction). 95.Pp 96When 97.Ev TZ 98is used as a pathname, it must either be a path relative to the system time 99conversion information directory, 100.Pa /usr/share/zoneinfo , 101or an absolute path that begins with 102.Pa /usr/share/zoneinfo/ . 103Other absolute paths, or paths that contain 104.Ql \&../ , 105will be ignored and the system local time zone file, 106.Pa /etc/localtime , 107will be used instead. 108The file must be in the format specified in 109.Xr tzfile 5 . 110.Pp 111When 112.Ev TZ 113is used directly as a specification of the time conversion information, 114it must have the following syntax (without whitespace between 115.Ar std 116and 117.Ar offset ) : 118.Bd -ragged -offset indent 119.Ar std 120.Sm off 121.Ar offset 122.Op Ar dst Op Ar offset 123.Op , Ar rule 124.Sm on 125.Ed 126.Pp 127Where: 128.Bl -tag -width "std and dst" 129.It Ar std No and Ar dst 130Three or more bytes that are the designation for the standard 131.Pq Ar std 132or the daylight saving 133.Pq Ar dst 134time zone. 135Only 136.Ar std 137is required; if 138.Ar dst 139is missing, then daylight saving time does not apply in this locale. 140Upper and lowercase letters are explicitly allowed. 141Any characters except a leading colon 142.Pq Ql \&: , 143digits, comma 144.Pq Ql \&, , 145minus 146.Pq Ql \&- , 147plus 148.Pq Ql \&+ , 149and ASCII NUL are allowed. 150.It Ar offset 151Indicates the value one must add to the local time to arrive at 152Coordinated Universal Time. 153.Ar offset 154has the form: 155.Pp 156.D1 Ar hh Ns Op : Ns Ar mm Ns Op : Ns Ar ss 157.Pp 158The minutes 159.Pq Ar mm 160and seconds 161.Pq Ar ss 162are optional. 163The hour 164.Pq Ar hh 165is required and may be a single digit. 166The 167.Ar offset 168following 169.Ar std 170is required. 171If no 172.Ar offset 173follows 174.Ar dst , 175daylight saving time is assumed to be one hour ahead of standard time. 176One or more digits may be used; the value is always interpreted as a 177decimal number. 178The hour must be between zero and 24, and the minutes (and 179seconds) \(em if present \(em between zero and 59. 180If preceded by a 181.Dq \&- , 182the time zone shall be east of the Prime Meridian; otherwise it shall be 183west (which may be indicated by an optional preceding 184.Dq \&+ ) . 185.It Ar rule 186Indicates when to change to and back from daylight saving time. 187.Ar rule 188has the form: 189.Pp 190.D1 Ar date Ns / Ns Ar time , Ns Ar date Ns / Ns Ar time 191.Pp 192where the first 193.Ar date 194describes when the change from standard to daylight saving time occurs and the 195second 196.Ar date 197describes when the change back happens. 198Each 199.Ar time 200field describes when, in current local time, the change to the other 201time is made. 202.Pp 203The format of 204.Ar date 205is one of the following: 206.Bl -tag -width Ds 207.It Cm J Ns Ar n 208The Julian day 209.Ar n 210.Pq 1 <= Ar n No <= 365 . 211Leap days are not counted; that is, in all years \(em including leap 212years \(em February 28 is day 59 and March 1 is day 60. 213It is impossible to explicitly refer to the occasional February 29. 214.It Ar n 215The zero-based Julian day 216.Pq 0 <= Ar n No <= 365 . 217Leap days are counted, and it is possible to refer to February 29. 218.It Cm M Ns Ar m . Ns Ar n . Ns Ar d 219Day 220.Ar d 221.Pq 1 <= Ar d No <= 6 222of week 223.Ar n 224.Pq 1 <= Ar n No <= 5 225of month 226.Ar m 227.Pq 1 <= Ar m No <= 12 , 228where week 5 means 229.Do 230the last 231.Ar d 232day in month 233.Ar m 234.Dc 235which may occur in either the fourth or the fifth week. 236Week 1 is the first week in which the 237.Ar d Ns th 238day occurs. 239Day zero is Sunday. 240.El 241.Pp 242The 243.Ar time 244has the same format as 245.Ar offset 246except that no leading sign 247.Po 248.Dq \&- 249or 250.Dq \&+ 251.Pc 252is allowed. 253The default, if 254.Ar time 255is not given, is 256.Cm 02:00:00 . 257.El 258.Pp 259If no 260.Ar rule 261is present in 262.Ev TZ , 263the rules specified 264by the 265.Xr tzfile 5 266format 267file 268.Cm posixrules 269in the system time conversion information directory are used, with the 270standard and daylight saving time offsets from UTC replaced by those 271specified by the 272.Ar offset 273values in 274.Ev TZ . 275.Pp 276For compatibility with System V Release 3.1, a semicolon 277.Pq Ql \&; 278may be used to separate the 279.Ar rule 280from the rest of the specification. 281.Pp 282If the 283.Ev TZ 284environment variable does not specify a 285.Xr tzfile 5 286format file 287and cannot be interpreted as a direct specification, 288UTC is used. 289.Pp 290.Fn tzsetwall 291behaves identically to 292.Fn tzset 293but it only uses the 294.Pa /etc/localtime 295file (that is, it ignores the 296.Ev TZ 297environment variable). 298.Sh FILES 299.Bl -tag -width "/usr/share/zoneinfo/posixrules" -compact 300.It Pa /usr/share/zoneinfo 301time zone information directory 302.It Pa /etc/localtime 303local time zone file 304.It Pa /usr/share/zoneinfo/posixrules 305used with POSIX-style 306.Ev TZ Ns s 307.It Pa /usr/share/zoneinfo/GMT 308for UTC leap seconds 309.El 310.Pp 311If 312.Pa /usr/share/zoneinfo/GMT 313is absent, 314UTC leap seconds are loaded from 315.Pa /usr/share/zoneinfo/posixrules . 316.Sh SEE ALSO 317.Xr ctime 3 , 318.Xr getenv 3 , 319.Xr strftime 3 , 320.Xr time 3 , 321.Xr tzfile 5 322.Sh STANDARDS 323The 324.Fn tzset 325function 326conforms to 327.St -p1003.1-2008 . 328The 329.Fn tzsetwall 330function is an extension to that specification. 331.\" This file is in the public domain, so clarified as of 332.\" 2009-05-17 by Arthur David Olson. 333