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 October 19, 2008 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, Coordinated 70Universal Time 71.Pq Tn UTC 72is used (without leap second correction). 73.Pp 74If 75.Ev TZ 76appears in the environment and its value begins with a colon 77.Pq Ql \&: , 78the rest of its value is used as a pathname of a 79.Xr tzfile 5 Ns -format 80file from which to read the time conversion information. 81If the first character of the pathname is a slash 82.Pq Ql / 83it is used as 84an absolute pathname; otherwise, it is used as a pathname relative to 85the system time conversion information directory. 86.Pp 87If its value does not begin with a colon, it is first used as the pathname 88of a file (as described above) from which to read the time conversion 89information. 90If that file cannot be read, the value is then interpreted as a direct 91specification (the format is described below) of the time conversion 92information. 93.Pp 94If the 95.Ev TZ 96environment variable does not specify a 97.Xr tzfile 5 Ns -format 98file and cannot be interpreted as a direct specification, 99.Tn UTC 100is used. 101.Pp 102The 103.Fn tzsetwall 104function 105sets things up so that 106.Xr localtime 3 107returns the best available approximation of local wall clock time. 108.Sh SPECIFICATION FORMAT 109When 110.Ev TZ 111is used directly as a specification of the time conversion information, 112it must have the following syntax (spaces inserted for clarity): 113.Bd -ragged -offset indent 114.Em std offset 115.Bo 116.Em dst 117.Bq Em offset 118.Bq , Em rule 119.Bc 120.Ed 121.Pp 122Where: 123.Bl -tag -width std_and_dst -offset indent 124.It Em std No and Em dst 125Three or more bytes that are the designation for the standard 126.Pq Em std 127or summer 128.Pq Em dst 129time zone. Only 130.Em std 131is required; if 132.Em dst 133is missing, then summer time does not apply in this locale. 134Upper and lowercase letters are explicitly allowed. Any characters 135except a leading colon 136.Pq Ql \&: , 137digits, comma 138.Pq Ql \&, , 139minus 140.Pq Ql \- , 141plus 142.Pq Ql + , 143and 144.Tn ASCII 145.Dv NUL 146are allowed. 147.It Em offset 148Indicates the value one must add to the local time to arrive at 149Coordinated Universal Time. The 150.Em offset 151has the form: 152.Bd -ragged -offset indent 153.Sm off 154.Em hh Bo 155.Em : mm 156.Bq Em : ss 157.Bc 158.Sm on 159.Ed 160.Pp 161The minutes 162.Pq Em mm 163and seconds 164.Pq Em ss 165are optional. The hour 166.Pq Em hh 167is required and may be a single digit. The 168.Em offset 169following 170.Em std 171is required. If no 172.Em offset 173follows 174.Em dst , 175summer time is assumed to be one hour ahead of standard time. One or 176more digits may be used; the value is always interpreted as a decimal 177number. The hour must be between zero and 24, and the minutes (and 178seconds) \(em if present \(em between zero and 59. If preceded by a 179.Pq Ql \- 180the time zone shall be east of the Prime Meridian; otherwise it shall be 181west (which may be indicated by an optional preceding 182.Pq Ql + ) . 183.It Em rule 184Indicates when to change to and back from summer time. The 185.Em rule 186has the form: 187.Bd -ragged -offset indent 188.Em date/time,date/time 189.Ed 190.Pp 191where the first 192.Em date 193describes when the change from standard to summer time occurs and the 194second 195.Em date 196describes when the change back happens. Each 197.Em time 198field describes when, in current local time, the change to the other 199time is made. 200.Pp 201The format of 202.Em date 203is one of the following: 204.Bl -tag -width "M.m.n.d" 205.It Sy J Em n 206The Julian day 207.Em n 208(1 \*(Le 209.Em n 210\*(Le 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. It is 213impossible to explicitly refer to the occasional February 29. 214.It Em n 215The zero-based Julian day 216(0 \*(Le 217.Em n 218\*(Le 365 ) . 219Leap days are counted, and it is possible to refer to February 29. 220.It Sy M Em m.n.d 221The 222.Em d Ns 'th 223day (0 \*(Le 224.Em d 225\*(Le 6) 226of week 227.Em n 228of month 229.Em m 230of the year 231(1 \*(Le 232.Em n 233\*(Le 5), 234(1 \*(Le 235.Em m 236\*(Le 12), 237where week 5 means 238.Do 239the last 240.Em d 241day in month 242.Em m 243.Dc 244which may occur in either the fourth or the fifth week). Week 1 is the 245first week in which the 246.Em d Ns 'th 247day occurs. Day zero is Sunday. 248.Pp 249The 250.Em time 251has the same format as 252.Em offset 253except that no leading sign 254.Pq Ql \- 255or 256.Pq Ql + 257is allowed. The default, if 258.Em time 259is not given, is 260.Sy 02:00:00 . 261.El 262.Pp 263If no 264.Em rule 265is present in the 266.Ev TZ 267specification, the rules specified 268by the 269.Xr tzfile 5 Ns -format 270file 271.Em posixrules 272in the system time conversion information directory are used, with the 273standard and summer time offsets from 274.Tn UTC 275replaced by those specified by 276the 277.Em offset 278values in 279.Ev TZ . 280.El 281.Pp 282For compatibility with System V Release 3.1, a semicolon 283.Pq Ql \&; 284may be used to separate the 285.Em rule 286from the rest of the specification. 287.Sh FILES 288.Bl -tag -width /usr/share/zoneinfo/posixrules -compact 289.It Pa /etc/localtime 290local time zone file 291.It Pa /usr/share/zoneinfo 292time zone directory 293.It Pa /usr/share/zoneinfo/posixrules 294rules for 295.Tn POSIX Ns -style 296.Tn TZ Ns 's 297.It Pa /usr/share/zoneinfo/GMT 298for 299.Tn UTC 300leap seconds 301.El 302.Pp 303If the file 304.Pa /usr/share/zoneinfo/GMT 305does not exist, 306.Tn UTC 307leap seconds are loaded from 308.Pa /usr/share/zoneinfo/posixrules . 309.Sh SEE ALSO 310.Xr date 1 , 311.Xr gettimeofday 2 , 312.Xr ctime 3 , 313.Xr getenv 3 , 314.Xr strftime 3 , 315.Xr time 3 , 316.Xr tzfile 5 317.Sh HISTORY 318The 319.Fn tzset 320and 321.Fn tzsetwall 322functions first appeared in 323.Bx 4.4 . 324