xref: /dragonfly/lib/libc/gen/tzset.3 (revision 7bc7e232) 
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. All advertising materials mentioning features or use of this software
16.\"    must display the following acknowledgement:
17.\"	This product includes software developed by the University of
18.\"	California, Berkeley and its contributors.
19.\" 4. Neither the name of the University nor the names of its contributors
20.\"    may be used to endorse or promote products derived from this software
21.\"    without specific prior written permission.
22.\"
23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33.\" SUCH DAMAGE.
34.\"
35.\"	@(#)tzset.3	8.2 (Berkeley) 11/17/93
36.\" $FreeBSD: src/lib/libc/gen/tzset.3,v 1.6.2.5 2001/12/14 18:33:51 ru Exp $
37.\" $DragonFly: src/lib/libc/gen/tzset.3,v 1.3 2006/04/08 08:17:06 swildner Exp $
38.\"
39.Dd November 17, 1993
40.Dt TZSET 3
41.Os
42.Sh NAME
43.Nm tzset ,
44.Nm tzsetwall
45.Nd initialize time conversion information
46.Sh LIBRARY
47.Lb libc
48.Sh SYNOPSIS
49.In time.h
50.Ft void
51.Fn tzset void
52.Ft void
53.Fn tzsetwall void
54.Sh DESCRIPTION
55The
56.Fn tzset
57function
58initializes time conversion information used by the library routine
59.Xr localtime 3 .
60The environment variable
61.Ev TZ
62specifies how this is done.
63.Pp
64If
65.Ev TZ
66does not appear in the environment, the best available approximation to
67local wall clock time, as specified by the
68.Xr tzfile 5 Ns -format
69file
70.Pa /etc/localtime
71is used.
72.Pp
73If
74.Ev TZ
75appears in the environment but its value is a null string, Coordinated
76Universal Time
77.Pq Tn UTC
78is used (without leap second correction).
79.Pp
80If
81.Ev TZ
82appears in the environment and its value begins with a colon
83.Pq Ql \&: ,
84the rest of its value is used as a pathname of a
85.Xr tzfile 5 Ns -format
86file from which to read the time conversion information.
87If the first character of the pathname is a slash
88.Pq Ql /
89it is used as
90an absolute pathname; otherwise, it is used as a pathname relative to
91the system time conversion information directory.
92.Pp
93If its value does not begin with a colon, it is first used as the pathname
94of a file (as described above) from which to read the time conversion
95information.
96If that file cannot be read, the value is then interpreted as a direct
97specification (the format is described below) of the time conversion
98information.
99.Pp
100If the
101.Ev TZ
102environment variable does not specify a
103.Xr tzfile 5 Ns -format
104file and cannot be interpreted as a direct specification,
105.Tn UTC
106is used.
107.Pp
108The
109.Fn tzsetwall
110function
111sets things up so that
112.Xr localtime 3
113returns the best available approximation of local wall clock time.
114.Sh SPECIFICATION FORMAT
115When
116.Ev TZ
117is used directly as a specification of the time conversion information,
118it must have the following syntax (spaces inserted for clarity):
119.Bd -ragged -offset indent
120.Em std offset
121.Bo
122.Em dst
123.Bq Em offset
124.Bq , Em rule
125.Bc
126.Ed
127.Pp
128Where:
129.Bl -tag -width std_and_dst -offset indent
130.It Em std No and Em dst
131Three or more bytes that are the designation for the standard
132.Pq Em std
133or summer
134.Pq Em dst
135time zone.  Only
136.Em std
137is required; if
138.Em dst
139is missing, then summer time does not apply in this locale.
140Upper and lowercase letters are explicitly allowed.  Any characters
141except a leading colon
142.Pq Ql \&: ,
143digits, comma
144.Pq Ql \&, ,
145minus
146.Pq Ql \- ,
147plus
148.Pq Ql + ,
149and
150.Tn ASCII
151.Dv NUL
152are allowed.
153.It Em offset
154Indicates the value one must add to the local time to arrive at
155Coordinated Universal Time.  The
156.Em offset
157has the form:
158.Bd -ragged -offset indent
159.Sm off
160.Em hh Bo
161.Em : mm
162.Bq Em : ss
163.Bc
164.Sm on
165.Ed
166.Pp
167The minutes
168.Pq Em mm
169and seconds
170.Pq Em ss
171are optional.  The hour
172.Pq Em hh
173is required and may be a single digit.  The
174.Em offset
175following
176.Em std
177is required.  If no
178.Em offset
179follows
180.Em dst ,
181summer time is assumed to be one hour ahead of standard time.  One or
182more digits may be used; the value is always interpreted as a decimal
183number.  The hour must be between zero and 24, and the minutes (and
184seconds) \(em if present \(em between zero and 59.  If preceded by a
185.Pq Ql \-
186the time zone shall be east of the Prime Meridian; otherwise it shall be
187west (which may be indicated by an optional preceding
188.Pq Ql + ) .
189.It Em rule
190Indicates when to change to and back from summer time.  The
191.Em rule
192has the form:
193.Bd -ragged -offset indent
194.Em date/time,date/time
195.Ed
196.Pp
197where the first
198.Em date
199describes when the change from standard to summer time occurs and the
200second
201.Em date
202describes when the change back happens.  Each
203.Em time
204field describes when, in current local time, the change to the other
205time is made.
206.Pp
207The format of
208.Em date
209is one of the following:
210.Bl -tag -width "M.m.n.d"
211.It Sy J Em n
212The Julian day
213.Em n
214(1 \*(Le
215.Em n
216\*(Le 365).
217Leap days are not counted; that is, in all years \(em including leap
218years \(em February 28 is day 59 and March 1 is day 60.  It is
219impossible to explicitly refer to the occasional February 29.
220.It Em n
221The zero-based Julian day
222(0 \*(Le
223.Em n
224\*(Le 365 ) .
225Leap days are counted, and it is possible to refer to February 29.
226.It Sy M  Em m.n.d
227The
228.Em d Ns 'th
229day (0 \*(Le
230.Em d
231\*(Le 6)
232of week
233.Em n
234of month
235.Em m
236of the year
237(1 \*(Le
238.Em n
239\*(Le 5),
240(1 \*(Le
241.Em m
242\*(Le 12),
243where week 5 means
244.Do
245the last
246.Em d
247day in month
248.Em m
249.Dc
250which may occur in either the fourth or the fifth week).  Week 1 is the
251first week in which the
252.Em d Ns 'th
253day occurs.  Day zero is Sunday.
254.Pp
255The
256.Em time
257has the same format as
258.Em offset
259except that no leading sign
260.Pq Ql \-
261or
262.Pq Ql +
263is allowed.  The default, if
264.Em time
265is not given, is
266.Sy 02:00:00 .
267.El
268.Pp
269If no
270.Em rule
271is present in the
272.Ev TZ
273specification, the rules specified
274by the
275.Xr tzfile 5 Ns -format
276file
277.Em posixrules
278in the system time conversion information directory are used, with the
279standard and summer time offsets from
280.Tn UTC
281replaced by those specified by
282the
283.Em offset
284values in
285.Ev TZ .
286.El
287.Pp
288For compatibility with System V Release 3.1, a semicolon
289.Pq Ql \&;
290may be used to separate the
291.Em rule
292from the rest of the specification.
293.Sh FILES
294.Bl -tag -width /usr/share/zoneinfo/posixrules -compact
295.It Pa /etc/localtime
296local time zone file
297.It Pa /usr/share/zoneinfo
298time zone directory
299.It Pa /usr/share/zoneinfo/posixrules
300rules for
301.Tn POSIX Ns -style
302.Tn TZ Ns 's
303.It Pa /usr/share/zoneinfo/GMT
304for
305.Tn UTC
306leap seconds
307.El
308.Pp
309If the file
310.Pa /usr/share/zoneinfo/GMT
311does not exist,
312.Tn UTC
313leap seconds are loaded from
314.Pa /usr/share/zoneinfo/posixrules .
315.Sh SEE ALSO
316.Xr date 1 ,
317.Xr gettimeofday 2 ,
318.Xr ctime 3 ,
319.Xr getenv 3 ,
320.Xr time 3 ,
321.Xr tzfile 5
322.Sh HISTORY
323The
324.Fn tzset
325and
326.Fn tzsetwall
327functions first appeared in
328.Bx 4.4 .
329