xref: /freebsd/lib/libc/stdtime/tzset.3 (revision 7a0a6b276cfd7e072346842fe4746d08ee30e617)
1*7a0a6b27SWarner Losh.\" Copyright (c) 1989, 1991, 1993
2*7a0a6b27SWarner Losh.\"	The Regents of the University of California.  All rights reserved.
3*7a0a6b27SWarner Losh.\"
4*7a0a6b27SWarner Losh.\" This code is derived from software contributed to Berkeley by
5*7a0a6b27SWarner Losh.\" Arthur Olson.
6*7a0a6b27SWarner Losh.\"
7*7a0a6b27SWarner Losh.\" Redistribution and use in source and binary forms, with or without
8*7a0a6b27SWarner Losh.\" modification, are permitted provided that the following conditions
9*7a0a6b27SWarner Losh.\" are met:
10*7a0a6b27SWarner Losh.\" 1. Redistributions of source code must retain the above copyright
11*7a0a6b27SWarner Losh.\"    notice, this list of conditions and the following disclaimer.
12*7a0a6b27SWarner Losh.\" 2. Redistributions in binary form must reproduce the above copyright
13*7a0a6b27SWarner Losh.\"    notice, this list of conditions and the following disclaimer in the
14*7a0a6b27SWarner Losh.\"    documentation and/or other materials provided with the distribution.
15*7a0a6b27SWarner Losh.\" 3. Neither the name of the University nor the names of its contributors
16*7a0a6b27SWarner Losh.\"    may be used to endorse or promote products derived from this software
17*7a0a6b27SWarner Losh.\"    without specific prior written permission.
18*7a0a6b27SWarner Losh.\"
19*7a0a6b27SWarner Losh.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20*7a0a6b27SWarner Losh.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21*7a0a6b27SWarner Losh.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22*7a0a6b27SWarner Losh.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23*7a0a6b27SWarner Losh.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24*7a0a6b27SWarner Losh.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25*7a0a6b27SWarner Losh.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26*7a0a6b27SWarner Losh.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27*7a0a6b27SWarner Losh.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28*7a0a6b27SWarner Losh.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29*7a0a6b27SWarner Losh.\" SUCH DAMAGE.
30*7a0a6b27SWarner Losh.\"
31*7a0a6b27SWarner Losh.Dd December 25, 2023
32*7a0a6b27SWarner Losh.Dt TZSET 3
33*7a0a6b27SWarner Losh.Os
34*7a0a6b27SWarner Losh.Sh NAME
35*7a0a6b27SWarner Losh.Nm daylight ,
36*7a0a6b27SWarner Losh.Nm timezone ,
37*7a0a6b27SWarner Losh.Nm tzname ,
38*7a0a6b27SWarner Losh.Nm tzset
39*7a0a6b27SWarner Losh.Nd initialize time conversion information
40*7a0a6b27SWarner Losh.Sh LIBRARY
41*7a0a6b27SWarner Losh.Lb libc
42*7a0a6b27SWarner Losh.Sh SYNOPSIS
43*7a0a6b27SWarner Losh.In time.h
44*7a0a6b27SWarner Losh.Vt extern int daylight ;
45*7a0a6b27SWarner Losh.Vt extern long timezone ;
46*7a0a6b27SWarner Losh.Vt extern char *tzname[2] ;
47*7a0a6b27SWarner Losh.Ft void
48*7a0a6b27SWarner Losh.Fn tzset void
49*7a0a6b27SWarner Losh.Sh DESCRIPTION
50*7a0a6b27SWarner LoshThe
51*7a0a6b27SWarner Losh.Fn tzset
52*7a0a6b27SWarner Loshfunction
53*7a0a6b27SWarner Loshinitializes time conversion information used by the library routine
54*7a0a6b27SWarner Losh.Xr localtime 3 .
55*7a0a6b27SWarner LoshThe environment variable
56*7a0a6b27SWarner Losh.Ev TZ
57*7a0a6b27SWarner Loshspecifies how this is done.
58*7a0a6b27SWarner Losh.Pp
59*7a0a6b27SWarner LoshIf
60*7a0a6b27SWarner Losh.Ev TZ
61*7a0a6b27SWarner Loshdoes not appear in the environment, the best available approximation to
62*7a0a6b27SWarner Loshlocal wall clock time, as specified by the
63*7a0a6b27SWarner Losh.Xr tzfile 5 Ns -format
64*7a0a6b27SWarner Loshfile
65*7a0a6b27SWarner Losh.Pa /etc/localtime
66*7a0a6b27SWarner Loshis used.
67*7a0a6b27SWarner Losh.Pp
68*7a0a6b27SWarner LoshIf
69*7a0a6b27SWarner Losh.Ev TZ
70*7a0a6b27SWarner Loshappears in the environment but its value is a null string, Coordinated
71*7a0a6b27SWarner LoshUniversal Time
72*7a0a6b27SWarner Losh.Pq Tn UTC
73*7a0a6b27SWarner Loshis used (without leap second correction).
74*7a0a6b27SWarner Losh.Pp
75*7a0a6b27SWarner LoshIf
76*7a0a6b27SWarner Losh.Ev TZ
77*7a0a6b27SWarner Loshappears in the environment and its value begins with a colon
78*7a0a6b27SWarner Losh.Pq Ql \&: ,
79*7a0a6b27SWarner Loshthe rest of its value is used as a pathname of a
80*7a0a6b27SWarner Losh.Xr tzfile 5 Ns -format
81*7a0a6b27SWarner Loshfile from which to read the time conversion information.
82*7a0a6b27SWarner LoshIf the first character of the pathname is a slash
83*7a0a6b27SWarner Losh.Pq Ql /
84*7a0a6b27SWarner Loshit is used as
85*7a0a6b27SWarner Loshan absolute pathname; otherwise, it is used as a pathname relative to
86*7a0a6b27SWarner Loshthe system time conversion information directory.
87*7a0a6b27SWarner Losh.Pp
88*7a0a6b27SWarner LoshIf its value does not begin with a colon, it is first used as the pathname
89*7a0a6b27SWarner Loshof a file (as described above) from which to read the time conversion
90*7a0a6b27SWarner Loshinformation.
91*7a0a6b27SWarner LoshIf that file cannot be read, the value is then interpreted as a direct
92*7a0a6b27SWarner Loshspecification (the format is described below) of the time conversion
93*7a0a6b27SWarner Loshinformation.
94*7a0a6b27SWarner Losh.Pp
95*7a0a6b27SWarner LoshIf the
96*7a0a6b27SWarner Losh.Ev TZ
97*7a0a6b27SWarner Loshenvironment variable does not specify a
98*7a0a6b27SWarner Losh.Xr tzfile 5 Ns -format
99*7a0a6b27SWarner Loshfile and cannot be interpreted as a direct specification,
100*7a0a6b27SWarner Losh.Tn UTC
101*7a0a6b27SWarner Loshis used.
102*7a0a6b27SWarner Losh.Pp
103*7a0a6b27SWarner LoshAfter the first call to
104*7a0a6b27SWarner Losh.Nm tzset ,
105*7a0a6b27SWarner Loshthe
106*7a0a6b27SWarner Losh.Vt timezone
107*7a0a6b27SWarner Loshvariable is set to the difference, in seconds, between Coordinated Universal
108*7a0a6b27SWarner LoshTime (UTC) and the local time.
109*7a0a6b27SWarner LoshThe
110*7a0a6b27SWarner Losh.Vt daylight
111*7a0a6b27SWarner Loshvariable is set to 0 if the local timezone is observing standard time.
112*7a0a6b27SWarner LoshIt is set to 1 if the local timezone ever observes an alternate time, such as summer time.
113*7a0a6b27SWarner LoshThe first element of the
114*7a0a6b27SWarner Losh.Vt tzname
115*7a0a6b27SWarner Losharray is the timezone name of standard time, while the second element is the
116*7a0a6b27SWarner Loshname of the altnerative time zone.
117*7a0a6b27SWarner Losh.Sh SPECIFICATION FORMAT
118*7a0a6b27SWarner LoshWhen
119*7a0a6b27SWarner Losh.Ev TZ
120*7a0a6b27SWarner Loshis used directly as a specification of the time conversion information,
121*7a0a6b27SWarner Loshit must have the following syntax (spaces inserted for clarity):
122*7a0a6b27SWarner Losh.Bd -ragged -offset indent
123*7a0a6b27SWarner Losh.Em std offset
124*7a0a6b27SWarner Losh.Bo
125*7a0a6b27SWarner Losh.Em dst
126*7a0a6b27SWarner Losh.Bq Em offset
127*7a0a6b27SWarner Losh.Bq , Em rule
128*7a0a6b27SWarner Losh.Bc
129*7a0a6b27SWarner Losh.Ed
130*7a0a6b27SWarner Losh.Pp
131*7a0a6b27SWarner LoshWhere:
132*7a0a6b27SWarner Losh.Bl -tag -width std_and_dst -offset indent
133*7a0a6b27SWarner Losh.It Em std No and Em dst
134*7a0a6b27SWarner LoshThree or more bytes that are the designation for the standard
135*7a0a6b27SWarner Losh.Pq Em std
136*7a0a6b27SWarner Loshor summer
137*7a0a6b27SWarner Losh.Pq Em dst
138*7a0a6b27SWarner Loshtime zone.
139*7a0a6b27SWarner LoshOnly
140*7a0a6b27SWarner Losh.Em std
141*7a0a6b27SWarner Loshis required; if
142*7a0a6b27SWarner Losh.Em dst
143*7a0a6b27SWarner Loshis missing, then summer time does not apply in this locale.
144*7a0a6b27SWarner LoshUpper and lowercase letters are explicitly allowed.
145*7a0a6b27SWarner LoshAny characters
146*7a0a6b27SWarner Loshexcept a leading colon
147*7a0a6b27SWarner Losh.Pq Ql \&: ,
148*7a0a6b27SWarner Loshdigits, comma
149*7a0a6b27SWarner Losh.Pq Ql \&, ,
150*7a0a6b27SWarner Loshminus
151*7a0a6b27SWarner Losh.Pq Ql \- ,
152*7a0a6b27SWarner Loshplus
153*7a0a6b27SWarner Losh.Pq Ql + ,
154*7a0a6b27SWarner Loshand
155*7a0a6b27SWarner Losh.Tn ASCII
156*7a0a6b27SWarner Losh.Dv NUL
157*7a0a6b27SWarner Loshare allowed.
158*7a0a6b27SWarner Losh.It Em offset
159*7a0a6b27SWarner LoshIndicates the value one must add to the local time to arrive at
160*7a0a6b27SWarner LoshCoordinated Universal Time.
161*7a0a6b27SWarner LoshThe
162*7a0a6b27SWarner Losh.Em offset
163*7a0a6b27SWarner Loshhas the form:
164*7a0a6b27SWarner Losh.Bd -ragged -offset indent
165*7a0a6b27SWarner Losh.Sm off
166*7a0a6b27SWarner Losh.Em hh Bo
167*7a0a6b27SWarner Losh.Em : mm
168*7a0a6b27SWarner Losh.Bq Em : ss
169*7a0a6b27SWarner Losh.Bc
170*7a0a6b27SWarner Losh.Sm on
171*7a0a6b27SWarner Losh.Ed
172*7a0a6b27SWarner Losh.Pp
173*7a0a6b27SWarner LoshThe minutes
174*7a0a6b27SWarner Losh.Pq Em mm
175*7a0a6b27SWarner Loshand seconds
176*7a0a6b27SWarner Losh.Pq Em ss
177*7a0a6b27SWarner Loshare optional.
178*7a0a6b27SWarner LoshThe hour
179*7a0a6b27SWarner Losh.Pq Em hh
180*7a0a6b27SWarner Loshis required and may be a single digit.
181*7a0a6b27SWarner LoshThe
182*7a0a6b27SWarner Losh.Em offset
183*7a0a6b27SWarner Loshfollowing
184*7a0a6b27SWarner Losh.Em std
185*7a0a6b27SWarner Loshis required.
186*7a0a6b27SWarner LoshIf no
187*7a0a6b27SWarner Losh.Em offset
188*7a0a6b27SWarner Loshfollows
189*7a0a6b27SWarner Losh.Em dst ,
190*7a0a6b27SWarner Loshsummer time is assumed to be one hour ahead of standard time.
191*7a0a6b27SWarner LoshOne or
192*7a0a6b27SWarner Loshmore digits may be used; the value is always interpreted as a decimal
193*7a0a6b27SWarner Loshnumber.
194*7a0a6b27SWarner LoshThe hour must be between zero and 24, and the minutes (and
195*7a0a6b27SWarner Loshseconds) \(em if present \(em between zero and 59.
196*7a0a6b27SWarner LoshIf preceded by a
197*7a0a6b27SWarner Losh.Pq Ql \-
198*7a0a6b27SWarner Loshthe time zone shall be east of the Prime Meridian; otherwise it shall be
199*7a0a6b27SWarner Loshwest (which may be indicated by an optional preceding
200*7a0a6b27SWarner Losh.Pq Ql + ) .
201*7a0a6b27SWarner Losh.It Em rule
202*7a0a6b27SWarner LoshIndicates when to change to and back from summer time.
203*7a0a6b27SWarner LoshThe
204*7a0a6b27SWarner Losh.Em rule
205*7a0a6b27SWarner Loshhas the form:
206*7a0a6b27SWarner Losh.Bd -ragged -offset indent
207*7a0a6b27SWarner Losh.Em date/time,date/time
208*7a0a6b27SWarner Losh.Ed
209*7a0a6b27SWarner Losh.Pp
210*7a0a6b27SWarner Loshwhere the first
211*7a0a6b27SWarner Losh.Em date
212*7a0a6b27SWarner Loshdescribes when the change from standard to summer time occurs and the
213*7a0a6b27SWarner Loshsecond
214*7a0a6b27SWarner Losh.Em date
215*7a0a6b27SWarner Loshdescribes when the change back happens.
216*7a0a6b27SWarner LoshEach
217*7a0a6b27SWarner Losh.Em time
218*7a0a6b27SWarner Loshfield describes when, in current local time, the change to the other
219*7a0a6b27SWarner Loshtime is made.
220*7a0a6b27SWarner Losh.Pp
221*7a0a6b27SWarner LoshThe format of
222*7a0a6b27SWarner Losh.Em date
223*7a0a6b27SWarner Loshis one of the following:
224*7a0a6b27SWarner Losh.Bl -tag -width "M.m.n.d"
225*7a0a6b27SWarner Losh.It Sy J Em n
226*7a0a6b27SWarner LoshThe Julian day
227*7a0a6b27SWarner Losh.Em n
228*7a0a6b27SWarner Losh(1 \*(Le
229*7a0a6b27SWarner Losh.Em n
230*7a0a6b27SWarner Losh\*(Le 365).
231*7a0a6b27SWarner LoshLeap days are not counted; that is, in all years \(em including leap
232*7a0a6b27SWarner Loshyears \(em February 28 is day 59 and March 1 is day 60.
233*7a0a6b27SWarner LoshIt is
234*7a0a6b27SWarner Loshimpossible to explicitly refer to the occasional February 29.
235*7a0a6b27SWarner Losh.It Em n
236*7a0a6b27SWarner LoshThe zero-based Julian day
237*7a0a6b27SWarner Losh(0 \*(Le
238*7a0a6b27SWarner Losh.Em n
239*7a0a6b27SWarner Losh\*(Le 365 ) .
240*7a0a6b27SWarner LoshLeap days are counted, and it is possible to refer to February 29.
241*7a0a6b27SWarner Losh.It Sy M Em m.n.d
242*7a0a6b27SWarner LoshThe
243*7a0a6b27SWarner Losh.Em d Ns 'th
244*7a0a6b27SWarner Loshday (0 \*(Le
245*7a0a6b27SWarner Losh.Em d
246*7a0a6b27SWarner Losh\*(Le 6)
247*7a0a6b27SWarner Loshof week
248*7a0a6b27SWarner Losh.Em n
249*7a0a6b27SWarner Loshof month
250*7a0a6b27SWarner Losh.Em m
251*7a0a6b27SWarner Loshof the year
252*7a0a6b27SWarner Losh(1 \*(Le
253*7a0a6b27SWarner Losh.Em n
254*7a0a6b27SWarner Losh\*(Le 5),
255*7a0a6b27SWarner Losh(1 \*(Le
256*7a0a6b27SWarner Losh.Em m
257*7a0a6b27SWarner Losh\*(Le 12),
258*7a0a6b27SWarner Loshwhere week 5 means
259*7a0a6b27SWarner Losh.Do
260*7a0a6b27SWarner Loshthe last
261*7a0a6b27SWarner Losh.Em d
262*7a0a6b27SWarner Loshday in month
263*7a0a6b27SWarner Losh.Em m
264*7a0a6b27SWarner Losh.Dc
265*7a0a6b27SWarner Loshwhich may occur in either the fourth or the fifth week).
266*7a0a6b27SWarner LoshWeek 1 is the
267*7a0a6b27SWarner Loshfirst week in which the
268*7a0a6b27SWarner Losh.Em d Ns 'th
269*7a0a6b27SWarner Loshday occurs.
270*7a0a6b27SWarner LoshDay zero is Sunday.
271*7a0a6b27SWarner Losh.Pp
272*7a0a6b27SWarner LoshThe
273*7a0a6b27SWarner Losh.Em time
274*7a0a6b27SWarner Loshhas the same format as
275*7a0a6b27SWarner Losh.Em offset
276*7a0a6b27SWarner Loshexcept that no leading sign
277*7a0a6b27SWarner Losh.Pq Ql \-
278*7a0a6b27SWarner Loshor
279*7a0a6b27SWarner Losh.Pq Ql +
280*7a0a6b27SWarner Loshis allowed.
281*7a0a6b27SWarner LoshThe default, if
282*7a0a6b27SWarner Losh.Em time
283*7a0a6b27SWarner Loshis not given, is
284*7a0a6b27SWarner Losh.Sy 02:00:00 .
285*7a0a6b27SWarner Losh.El
286*7a0a6b27SWarner Losh.Pp
287*7a0a6b27SWarner LoshIf no
288*7a0a6b27SWarner Losh.Em rule
289*7a0a6b27SWarner Loshis present in the
290*7a0a6b27SWarner Losh.Ev TZ
291*7a0a6b27SWarner Loshspecification, the rules specified
292*7a0a6b27SWarner Loshby the
293*7a0a6b27SWarner Losh.Xr tzfile 5 Ns -format
294*7a0a6b27SWarner Loshfile
295*7a0a6b27SWarner Losh.Em posixrules
296*7a0a6b27SWarner Loshin the system time conversion information directory are used, with the
297*7a0a6b27SWarner Loshstandard and summer time offsets from
298*7a0a6b27SWarner Losh.Tn UTC
299*7a0a6b27SWarner Loshreplaced by those specified by
300*7a0a6b27SWarner Loshthe
301*7a0a6b27SWarner Losh.Em offset
302*7a0a6b27SWarner Loshvalues in
303*7a0a6b27SWarner Losh.Ev TZ .
304*7a0a6b27SWarner Losh.El
305*7a0a6b27SWarner Losh.Pp
306*7a0a6b27SWarner LoshFor compatibility with System V Release 3.1, a semicolon
307*7a0a6b27SWarner Losh.Pq Ql \&;
308*7a0a6b27SWarner Loshmay be used to separate the
309*7a0a6b27SWarner Losh.Em rule
310*7a0a6b27SWarner Loshfrom the rest of the specification.
311*7a0a6b27SWarner Losh.Sh FILES
312*7a0a6b27SWarner Losh.Bl -tag -width /usr/share/zoneinfo/posixrules -compact
313*7a0a6b27SWarner Losh.It Pa /etc/localtime
314*7a0a6b27SWarner Loshlocal time zone file
315*7a0a6b27SWarner Losh.It Pa /usr/share/zoneinfo
316*7a0a6b27SWarner Loshtime zone directory
317*7a0a6b27SWarner Losh.It Pa /usr/share/zoneinfo/posixrules
318*7a0a6b27SWarner Loshrules for
319*7a0a6b27SWarner Losh.Tn POSIX Ns -style
320*7a0a6b27SWarner Losh.Tn TZ Ns 's
321*7a0a6b27SWarner Losh.It Pa /usr/share/zoneinfo/Etc/GMT
322*7a0a6b27SWarner Loshfor
323*7a0a6b27SWarner Losh.Tn UTC
324*7a0a6b27SWarner Loshleap seconds
325*7a0a6b27SWarner Losh.El
326*7a0a6b27SWarner Losh.Pp
327*7a0a6b27SWarner LoshIf the file
328*7a0a6b27SWarner Losh.Pa /usr/share/zoneinfo/UTC
329*7a0a6b27SWarner Loshdoes not exist,
330*7a0a6b27SWarner Losh.Tn UTC
331*7a0a6b27SWarner Loshleap seconds are loaded from
332*7a0a6b27SWarner Losh.Pa /usr/share/zoneinfo/posixrules .
333*7a0a6b27SWarner Losh.Sh SEE ALSO
334*7a0a6b27SWarner Losh.Xr date 1 ,
335*7a0a6b27SWarner Losh.Xr gettimeofday 2 ,
336*7a0a6b27SWarner Losh.Xr ctime 3 ,
337*7a0a6b27SWarner Losh.Xr getenv 3 ,
338*7a0a6b27SWarner Losh.Xr time 3 ,
339*7a0a6b27SWarner Losh.Xr tzfile 5
340*7a0a6b27SWarner Losh.Sh HISTORY
341*7a0a6b27SWarner LoshThe
342*7a0a6b27SWarner Losh.Fn tzset
343*7a0a6b27SWarner Loshfunction first appeared in
344*7a0a6b27SWarner Losh.Bx 4.4 .
345