1.\" Copyright (c) 1989, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" Arthur Olson. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" $FreeBSD: src/lib/libc/gen/tzset.3,v 1.6.2.5 2001/12/14 18:33:51 ru Exp $ 32.\" 33.Dd December 1, 2013 34.Dt TZSET 3 35.Os 36.Sh NAME 37.Nm tzset , 38.Nm tzsetwall 39.Nd initialize time conversion information 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In time.h 44.Ft void 45.Fn tzset void 46.Ft void 47.Fn tzsetwall void 48.Sh DESCRIPTION 49The 50.Fn tzset 51function 52initializes time conversion information used by the library routine 53.Xr localtime 3 . 54The environment variable 55.Ev TZ 56specifies how this is done. 57.Pp 58If 59.Ev TZ 60does not appear in the environment, the best available approximation to 61local wall clock time, as specified by the 62.Xr tzfile 5 Ns -format 63file 64.Pa /etc/localtime 65is used. 66.Pp 67If 68.Ev TZ 69appears in the environment but its value is a null string 70Universal Time 71.Pq UT 72is used, with the abbreviation 73.Dq UTC 74and without leap second correction; please see 75.Xr ctime 3 76for more about UT, UTC, and leap seconds. 77.Pp 78If 79.Ev TZ 80appears in the environment and its value begins with a colon 81.Pq Ql \&: , 82the rest of its value is used as a pathname of a 83.Xr tzfile 5 Ns -format 84file from which to read the time conversion information. 85If the first character of the pathname is a slash 86.Pq Ql / 87it is used as 88an absolute pathname; otherwise, it is used as a pathname relative to 89the system time conversion information directory. 90.Pp 91If its value does not begin with a colon, it is first used as the pathname 92of a file (as described above) from which to read the time conversion 93information. 94If that file cannot be read, the value is then interpreted as a direct 95specification (the format is described below) of the time conversion 96information. 97.Pp 98If the 99.Ev TZ 100environment variable does not specify a 101.Xr tzfile 5 Ns -format 102file and cannot be interpreted as a direct specification, 103.Tn UTC 104is used. 105.Pp 106The 107.Fn tzsetwall 108function 109sets things up so that 110.Xr localtime 3 111returns the best available approximation of local wall clock time. 112.Sh SPECIFICATION FORMAT 113When 114.Ev TZ 115is used directly as a specification of the time conversion information, 116it must have the following syntax (spaces inserted for clarity): 117.Bd -ragged -offset indent 118.Em std offset 119.Bo 120.Em dst 121.Bq Em offset 122.Bq , Em rule 123.Bc 124.Ed 125.Pp 126Where: 127.Bl -tag -width std_and_dst -offset indent 128.It Em std No and Em dst 129Three or more bytes that are the designation for the standard 130.Pq Em std 131or summer 132.Pq Em dst 133time zone. Only 134.Em std 135is required; if 136.Em dst 137is missing, then summer time does not apply in this locale. 138Upper and lowercase letters are explicitly allowed. Any characters 139except a leading colon 140.Pq Ql \&: , 141digits, comma 142.Pq Ql \&, , 143minus 144.Pq Ql \- , 145plus 146.Pq Ql + , 147and 148.Tn ASCII 149.Dv NUL 150are allowed. 151.It Em offset 152Indicates the value one must add to the local time to arrive at 153Coordinated Universal Time. The 154.Em offset 155has the form: 156.Bd -ragged -offset indent 157.Sm off 158.Em hh Bo 159.Em : mm 160.Bq Em : ss 161.Bc 162.Sm on 163.Ed 164.Pp 165The minutes 166.Pq Em mm 167and seconds 168.Pq Em ss 169are optional. The hour 170.Pq Em hh 171is required and may be a single digit. The 172.Em offset 173following 174.Em std 175is required. If no 176.Em offset 177follows 178.Em dst , 179summer time is assumed to be one hour ahead of standard time. One or 180more digits may be used; the value is always interpreted as a decimal 181number. The hour must be between zero and 24, and the minutes (and 182seconds) \(em if present \(em between zero and 59. If preceded by a 183.Pq Ql \- 184the time zone shall be east of the Prime Meridian; otherwise it shall be 185west (which may be indicated by an optional preceding 186.Pq Ql + ) . 187.It Em rule 188Indicates when to change to and back from summer time. The 189.Em rule 190has the form: 191.Bd -ragged -offset indent 192.Em date/time,date/time 193.Ed 194.Pp 195where the first 196.Em date 197describes when the change from standard to summer time occurs and the 198second 199.Em date 200describes when the change back happens. Each 201.Em time 202field describes when, in current local time, the change to the other 203time is made. 204As an extension to POSIX, daylight saving is assumed to be in effect 205all year if it begins January 1 at 00:00 and ends December 31 at 20624:00 plus the difference between daylight saving and standard time, 207leaving no room for standard time in the calendar. 208.Pp 209The format of 210.Em date 211is one of the following: 212.Bl -tag -width "M.m.n.d" 213.It Sy J Em n 214The Julian day 215.Em n 216(1 \*(Le 217.Em n 218\*(Le 365). 219Leap days are not counted; that is, in all years \(em including leap 220years \(em February 28 is day 59 and March 1 is day 60. It is 221impossible to explicitly refer to the occasional February 29. 222.It Em n 223The zero-based Julian day 224(0 \*(Le 225.Em n 226\*(Le 365 ) . 227Leap days are counted, and it is possible to refer to February 29. 228.It Sy M Em m.n.d 229The 230.Em d Ns 'th 231day (0 \*(Le 232.Em d 233\*(Le 6) 234of week 235.Em n 236of month 237.Em m 238of the year 239(1 \*(Le 240.Em n 241\*(Le 5), 242(1 \*(Le 243.Em m 244\*(Le 12), 245where week 5 means 246.Do 247the last 248.Em d 249day in month 250.Em m 251.Dc 252which may occur in either the fourth or the fifth week). Week 1 is the 253first week in which the 254.Em d Ns 'th 255day occurs. Day zero is Sunday. 256.El 257.Pp 258The 259.Em time 260has the same format as 261.Em offset 262except that POSIX does not allow a leading sign 263.Pq Ql \- 264or 265.Pq Ql + . 266As an extension to POSIX, the hours part of 267.Em time 268can range from -167 through 167; this allows for unusual rules such 269as 270.Dq the Saturday before the first Sunday of March . 271The default, if 272.Em time 273is not given, is 274.Sy 02:00:00 . 275.El 276.Pp 277Here are some examples of 278.Ev TZ 279values that directly specify the time zone rules; they use some of the 280extensions to POSIX. 281.Bl -tag -width ".Sy EST5X" 282.It Sy EST5 283stands for US Eastern Standard 284Time (EST), 5 hours behind UTC, without daylight saving. 285.It Sy FJT-12FJST,M10.3.1/146,M1.3.4/75 286stands for Fiji Time (FJT) and Fiji Summer Time (FJST), 12 hours ahead 287of UTC, springing forward on October's third Monday at 288146:00 (i.e., 02:00 on the first Sunday on or after October 21), and 289falling back on January's third Thursday at 75:00 (i.e., 03:00 on the 290first Sunday on or after January 18). 291.It Sy IST-2IDT,M3.4.4/26,M10.5.0 292stands for Israel Standard Time (IST) and Israel Daylight Time (IDT), 2932 hours ahead of UTC, springing forward on March's fourth 294Tuesday at 26:00 (i.e., 02:00 on the first Friday on or after March 29523), and falling back on October's last Sunday at 02:00. 296.It Sy WART4WARST,J1/0,J365/25 297stands for Western Argentina Summer Time (WARST), 3 hours behind UTC. 298There is a dummy fall-back transition on December 31 at 25:00 daylight 299saving time (i.e., 24:00 standard time, equivalent to January 1 at 30000:00 standard time), and a simultaneous spring-forward transition on 301January 1 at 00:00 standard time, so daylight saving time is in effect 302all year and the initial 303.Sy WART 304is a placeholder. 305.It Sy WGT3WGST,M3.5.0/-2,M10.5.0/-1 306stands for Western Greenland Time (WGT) and Western Greenland Summer 307Time (WGST), 3 hours behind UTC, where clocks follow the EU rules of 308springing forward on March's last Sunday at 01:00 UTC (\(mi02:00 local 309time) and falling back on October's last Sunday at 01:00 UTC 310(-01:00 local time). 311.El 312.Pp 313If no 314.Em rule 315is present in the 316.Ev TZ 317specification, the rules specified 318by the 319.Xr tzfile 5 Ns -format 320file 321.Em posixrules 322in the system time conversion information directory are used, with the 323standard and summer time offsets from 324.Tn UTC 325replaced by those specified by 326the 327.Em offset 328values in 329.Ev TZ . 330.Pp 331For compatibility with System V Release 3.1, a semicolon 332.Pq Ql \&; 333may be used to separate the 334.Em rule 335from the rest of the specification. 336.Sh FILES 337.Bl -tag -width /usr/share/zoneinfo/posixrules -compact 338.It Pa /etc/localtime 339local time zone file 340.It Pa /usr/share/zoneinfo 341time zone directory 342.It Pa /usr/share/zoneinfo/posixrules 343rules for 344.Tn POSIX Ns -style 345.Tn TZ Ns 's 346.It Pa /usr/share/zoneinfo/GMT 347for 348.Tn UTC 349leap seconds 350.El 351.Pp 352If the file 353.Pa /usr/share/zoneinfo/GMT 354does not exist, 355.Tn UTC 356leap seconds are loaded from 357.Pa /usr/share/zoneinfo/posixrules . 358.Sh SEE ALSO 359.Xr date 1 , 360.Xr gettimeofday 2 , 361.Xr ctime 3 , 362.Xr getenv 3 , 363.Xr strftime 3 , 364.Xr time 3 , 365.Xr tzfile 5 366.Sh HISTORY 367The 368.Fn tzset 369and 370.Fn tzsetwall 371functions first appeared in 372.Bx 4.4 . 373