xref: /dragonfly/lib/libc/gen/tzset.3 (revision 89a89091) 
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.\" $FreeBSD: src/lib/libc/gen/tzset.3,v 1.6.2.5 2001/12/14 18:33:51 ru Exp $
36.\"
37.Dd October 19, 2008
38.Dt TZSET 3
39.Os
40.Sh NAME
41.Nm tzset ,
42.Nm tzsetwall
43.Nd initialize time conversion information
44.Sh LIBRARY
45.Lb libc
46.Sh SYNOPSIS
47.In time.h
48.Ft void
49.Fn tzset void
50.Ft void
51.Fn tzsetwall void
52.Sh DESCRIPTION
53The
54.Fn tzset
55function
56initializes time conversion information used by the library routine
57.Xr localtime 3 .
58The environment variable
59.Ev TZ
60specifies how this is done.
61.Pp
62If
63.Ev TZ
64does not appear in the environment, the best available approximation to
65local wall clock time, as specified by the
66.Xr tzfile 5 Ns -format
67file
68.Pa /etc/localtime
69is used.
70.Pp
71If
72.Ev TZ
73appears in the environment but its value is a null string, Coordinated
74Universal Time
75.Pq Tn UTC
76is used (without leap second correction).
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.
204.Pp
205The format of
206.Em date
207is one of the following:
208.Bl -tag -width "M.m.n.d"
209.It Sy J Em n
210The Julian day
211.Em n
212(1 \*(Le
213.Em n
214\*(Le 365).
215Leap days are not counted; that is, in all years \(em including leap
216years \(em February 28 is day 59 and March 1 is day 60.  It is
217impossible to explicitly refer to the occasional February 29.
218.It Em n
219The zero-based Julian day
220(0 \*(Le
221.Em n
222\*(Le 365 ) .
223Leap days are counted, and it is possible to refer to February 29.
224.It Sy M  Em m.n.d
225The
226.Em d Ns 'th
227day (0 \*(Le
228.Em d
229\*(Le 6)
230of week
231.Em n
232of month
233.Em m
234of the year
235(1 \*(Le
236.Em n
237\*(Le 5),
238(1 \*(Le
239.Em m
240\*(Le 12),
241where week 5 means
242.Do
243the last
244.Em d
245day in month
246.Em m
247.Dc
248which may occur in either the fourth or the fifth week).  Week 1 is the
249first week in which the
250.Em d Ns 'th
251day occurs.  Day zero is Sunday.
252.Pp
253The
254.Em time
255has the same format as
256.Em offset
257except that no leading sign
258.Pq Ql \-
259or
260.Pq Ql +
261is allowed.  The default, if
262.Em time
263is not given, is
264.Sy 02:00:00 .
265.El
266.Pp
267If no
268.Em rule
269is present in the
270.Ev TZ
271specification, the rules specified
272by the
273.Xr tzfile 5 Ns -format
274file
275.Em posixrules
276in the system time conversion information directory are used, with the
277standard and summer time offsets from
278.Tn UTC
279replaced by those specified by
280the
281.Em offset
282values in
283.Ev TZ .
284.El
285.Pp
286For compatibility with System V Release 3.1, a semicolon
287.Pq Ql \&;
288may be used to separate the
289.Em rule
290from the rest of the specification.
291.Sh FILES
292.Bl -tag -width /usr/share/zoneinfo/posixrules -compact
293.It Pa /etc/localtime
294local time zone file
295.It Pa /usr/share/zoneinfo
296time zone directory
297.It Pa /usr/share/zoneinfo/posixrules
298rules for
299.Tn POSIX Ns -style
300.Tn TZ Ns 's
301.It Pa /usr/share/zoneinfo/GMT
302for
303.Tn UTC
304leap seconds
305.El
306.Pp
307If the file
308.Pa /usr/share/zoneinfo/GMT
309does not exist,
310.Tn UTC
311leap seconds are loaded from
312.Pa /usr/share/zoneinfo/posixrules .
313.Sh SEE ALSO
314.Xr date 1 ,
315.Xr gettimeofday 2 ,
316.Xr ctime 3 ,
317.Xr getenv 3 ,
318.Xr strftime 3 ,
319.Xr time 3 ,
320.Xr tzfile 5
321.Sh HISTORY
322The
323.Fn tzset
324and
325.Fn tzsetwall
326functions first appeared in
327.Bx 4.4 .
328