| blob | 6fdbcc22fa7327339fe0a8afb070a2af19bf367c |
1 .\" $NetBSD: tzset.3,v 1.32 2015/04/05 08:36:38 pgoyette Exp $
2 .Dd October 23, 2014
3 .Dt TZSET 3
4 .Os
5 .Sh NAME
6 .Nm tzset ,
7 .Nm tzalloc ,
8 .Nm tzgetname ,
9 .Nm tzfree
10 .Nd initialize time conversion information
11 .Sh LIBRARY
12 .Lb libc
13 .Sh SYNOPSIS
14 .In time.h
15 .Ft timezone_t
16 .Fn tzalloc "const char *zone"
17 .Ft void
18 .Fn tzfree "timezone_t restrict tz"
19 .Ft const char *
20 .Fn tzgetname "timezone_t restrict tz" "int isdst"
21 .Ft void
22 .Fn tzset "void"
23 .Sh DESCRIPTION
24 The
25 .Fn tzalloc
26 function takes as an argument a timezone name and returns a
27 .Ft timezone_t
28 object suitable to be used in the
29 .Fn ctime_rz ,
30 .Fn localtime_rz ,
31 and
32 .Fn mktime_z
33 functions.
34 .Pp
35 If
36 .Ar tz
37 is not a valid time zone description, or if the object cannot be allocated,
38 .Fn tzalloc
39 returns a
40 .Dv NULL
41 pointer and sets
42 .Va errno .
43 .Pp
44 A
45 .Dv NULL
46 pointer may be passed to
47 .Fn tzalloc
48 instead of a timezone name, to refer to the current system timezone.
49 An empty timezone string indicates Coordinated Universal Time
50 .Pq Tn UTC .
51 .Pp
52 Note that instead of setting the environment variable
53 .Va TZ ,
54 and globally changing the behavior of the calling program, one can use
55 multiple timezones at the same time by using separate
56 .Ft timezone_t
57 objects allocated by
58 .Fn tzalloc
59 and calling the
60 .Dq z
61 variants of the functions.
62 The
63 .Fn tzfree
64 function deallocates
65 .Fa tz ,
66 which was previously allocated by
67 .Fn tzalloc .
68 This invalidates any
69 .Ft tm_zone
70 pointers that
71 .Fa tz
72 was used to set.
73 Finally,
74 .Fn tzgetname
75 returns the name for the given
76 .Fa tz .
77 If
78 .Fa isdst
79 is
80 .Va 0 ,
81 the call is equivalent to
82 .Va tzname[0] .
83 If
84 .Fa isdst
85 is set to
86 .Va 1
87 the call is equivalent to
88 .Va tzname[1] .
89 The
90 .Fn tzset
91 function acts like
92 .Dv tzalloc(getenv("TZ")) ,
93 except it saves any resulting time zone object into internal
94 storage that is accessed by
95 .Fn localtime ,
96 .Fn localtime_r ,
97 and
98 .Fn mktime .
99 The anonymous shared time zone object is freed by the next call to
100 .Fn tzset .
101 If the implied call to
102 .Fn tzalloc
103 fails,
104 .Fn tzset
105 falls back on UTC.
106 If
107 .Ev TZ
108 is
109 .Dv NULL ,
110 the best available approximation to local wall clock time, as
111 specified by the
112 .Xr tzfile 5
113 format file
114 .Pa /etc/localtime
115 is used by
116 .Xr localtime 3 .
117 If
118 .Ev TZ
119 appears in the environment but its value is the empty string,
120 Universal Time (UT) is used, with the abbreviation
121 .Dq UTC
122 and without leap second correction; please see
123 .Xr ctime 3 .
124 If
125 .Ev TZ
126 is nonnull and nonempty:
127 .Bl -dash
128 .It
129 if the value begins with a colon, it is used as a pathname of a file
130 from which to read the time conversion information;
131 .It
132 if the value does not begin with a colon, it is first used as the
133 pathname of a file from which to read the time conversion information,
134 and, if that file cannot be read, is used directly as a specification
135 of the time conversion information.
136 .El
137 .Pp
138 When
139 .Ev TZ
140 is used as a pathname, if it begins with a slash, it is used as an
141 absolute pathname; otherwise, it is used as a pathname relative to
142 .Pa /usr/share/zoneinfo .
143 The file must be in the format specified in
144 .Xr tzfile 5 .
145 .Pp
146 When
147 .Ev TZ
148 is used directly as a specification of the time conversion information,
149 it must have the following syntax (spaces inserted for clarity):
150 .Sm off
151 .Bd -literal -offset indent
152 .Cm std Cm offset Oo
153 .Cm dst Oo
154 .Cm offset Oc Oo
155 .No , Cm rule Oc Oc
156 .Ed
157 .Sm on
158 .Pp
159 where:
160 .Bl -tag -width "std and dst" -compact
161 .It Cm std No and Cm dst
162 Three or more bytes that are the designation for the standard
163 .Cm ( std )
164 or summer
165 .Cm ( dst )
166 time zone.
167 Only
168 .Cm std
169 is required; if
170 .Cm dst
171 is missing, then summer time does not apply in this locale.
172 Upper- and lowercase letters are explicitly allowed.
173 Any characters except a leading colon (:), digits, comma (,), minus (-),
174 plus (+), and NUL bytes are allowed.
175 .It Cm offset
176 Indicates the value one must add to the local time to arrive at
177 Coordinated Universal Time.
178 The
179 .Cm offset
180 has the form:
181 .Sm off
182 .Bd -literal -offset indent
183 .Cm hh Oo
184 .Cm :mm Oo
185 .Cm :ss Oc Oc
186 .Ed
187 .Sm on
188 .Pp
189 The minutes
190 .Cm ( mm )
191 and seconds
192 .Cm ( ss )
193 are optional.
194 The hour
195 .Cm ( hh )
196 is required and may be a single digit.
197 The
198 .Cm offset
199 following
200 .Cm std
201 is required.
202 If no
203 .Cm offset
204 follows
205 .Cm dst ,
206 summer time is assumed to be one hour ahead of standard time.
207 One or more digits may be used; the value is always interpreted as a
208 decimal number.
209 The hour must be between zero and 24, and the minutes (and
210 seconds) \*(en if present \*(en between zero and 59.
211 If preceded by a
212 .Dq -
213 the time zone shall be east of the Prime Meridian; otherwise it shall be
214 west (which may be indicated by an optional preceding
215 .Dq + ) .
216 .It Cm rule
217 Indicates when to change to and back from summer time.
218 The
219 .Cm rule
220 has the form:
221 .Sm off
222 .Bd -literal -offset indent
223 .Xo
224 .Cm date No /
225 .Cm time No ,
226 .Cm date No /
227 .Cm time
228 .Xc
229 .Ed
230 .Sm on
231 .Pp
232 where the first
233 .Cm date
234 describes when the change from standard to summer time occurs and the
235 second
236 .Cm date
237 describes when the change back happens.
238 Each
239 .Cm time
240 field describes when, in current local time, the change to the other
241 time is made.
242 As an extension to POSIX, daylight saving is assumed to be in effect
243 all year if it begins January 1 at 00:00 and ends December 31 at
244 24:00 plus the difference between daylight saving and standard time,
245 leaving no room for standard time in the calendar.
246 The format of
247 .Fa date
248 is one of the following:
249 .Bl -tag -width "The Julian day" -compact
250 .It Cm J Ns Ar n
251 The Julian day
252 .Ar n
253 (1 \*[Le]
254 .Ar n
255 \*[Le] 365).
256 Leap days are not counted; that is, in all years \*(en including leap
257 years \*(en February 28 is day 59 and March 1 is day 60.
258 It is impossible to explicitly refer to the occasional February 29.
259 .It Ar n
260 The zero-based Julian day (0\ \*[Le]
261 .Ar n
262 \*[Le]\ 365).
263 Leap days are counted, and it is possible to refer to
264 February 29.
265 .Sm off
266 .It Cm M Ns Ar m No . Ar n No . Ar d
267 .Sm on
268 The
269 .Ar d Ns 'th
270 day
271 (0 \*[Le]
272 .Ar d
273 \*[Le]\ 6) of week
274 .Ar n
275 of month
276 .Ar m
277 of the year
278 (1 \*[Le]
279 .Ar n
280 \*[Le]\ 5, 1 \*[Le]
281 .Ar m
282 \*[Le]\ 12, where week 5 means
283 .Dq the\ last Ar d No day\ in\ month Ar m
284 which may occur in either the fourth or the fifth week).
285 Week 1 is the first week in which the
286 .Ar d Ns 'th
287 day occurs.
288 Day zero is Sunday.
289 .El
290 The
291 .Cm time
292 has the same format as
293 .Cm offset
294 except that POSIX does not allow a leading sign
295 .Dq -
296 or
297 .Dq +
298 is allowed.
299 As an extension to POSIX, the hours part of
300 .Cm time
301 can range from \-167 through 167; this allows for unusual rules such as
302 .Dq the Saturday before the first Sunday of March .
303 The default, if
304 .Cm time
305 is not given, is
306 .Cm 02:00:00 .
307 .El
308 .Pp
309 Here are some examples of
310 .Va TZ
311 values that directly specify the time zone rules; they use some of the
312 extensions to POSIX.
313 .Bl -tag
314 .It EST5
315 stands for US Eastern Standard
316 Time (EST), 5 hours behind UTC, without daylight saving.
317 .It FJT\-12FJST,M11.1.0,M1.3.4/75
318 stands for Fiji Time (FJT) and Fiji Summer Time (FJST), 12 hours ahead
319 of UTC, springing forward on November's first Sunday at 02:00, and
320 falling back on January's third Thursday at 75:00 (i.e., 03:00 on the
321 first Sunday on or after January 18).
322 .It IST\-2IDT,M3.4.4/26,M10.5.0
323 stands for Israel Standard Time (IST) and Israel Daylight Time (IDT),
324 2 hours ahead of UTC, springing forward on March's fourth
325 Thursday at 26:00 (i.e., 02:00 on the first Friday on or after March
326 23), and falling back on October's last Sunday at 02:00.
327 .It WART4WARST,J1/0,J365/25
328 stands for Western Argentina Summer Time (WARST), 3 hours behind UTC.
329 There is a dummy fall-back transition on December 31 at 25:00 daylight
330 saving time (i.e., 24:00 standard time, equivalent to January 1 at
331 00:00 standard time), and a simultaneous spring-forward transition on
332 January 1 at 00:00 standard time, so daylight saving time is in effect
333 all year and the initial
334 .Em WART
335 is a placeholder.
336 .It WGT3WGST,M3.5.0/\-2,M10.5.0/\-1
337 stands for Western Greenland Time (WGT) and Western Greenland Summer
338 Time (WGST), 3 hours behind UTC, where clocks follow the EU rules of
339 springing forward on March's last Sunday at 01:00 UTC (\-02:00 local
340 time) and falling back on October's last Sunday at 01:00 UTC
341 (\-01:00 local time).
342 .El
343 .Pp
344 If no
345 .Cm rule
346 is present in
347 .Ev TZ ,
348 the rules specified by the
349 .Xr tzfile 5
350 format file
351 .Pa posixrules
352 in
353 .Pa /usr/share/zoneinfo
354 are used, with the standard and summer time offsets from UTC replaced
355 by those specified by the
356 .Cm offset
357 values in
358 .Ev TZ .
359 .Pp
360 For compatibility with System V Release 3.1, a semicolon (;) may be
361 used to separate the
362 .Cm rule
363 from the rest of the specification.
364 .Sh FILES
365 .Bl -tag -width /usr/share/zoneinfo/posixrules -compact
366 .It Pa /etc/localtime
367 local time zone file
368 .It Pa /usr/share/zoneinfo
369 time zone information directory
370 .It Pa /usr/share/zoneinfo/posixrules
371 used with POSIX-style TZ's
372 .It Pa /usr/share/zoneinfo/GMT
373 for UTC leap seconds
374 .El
375 .Pp
376 If
377 .Pa /usr/share/zoneinfo/GMT
378 is absent, UTC leap seconds are loaded from
379 .Pa /usr/share/zoneinfo/posixrules .
380 .Sh SEE ALSO
381 .Xr ctime 3 ,
382 .Xr getenv 3 ,
383 .Xr strftime 3 ,
384 .Xr time 3 ,
385 .Xr tzfile 5
386 .Sh STANDARDS
387 The
388 .Fn tzset
389 function conforms to
390 .St -p1003.1-88 .
391 .\" @(#)newtzset.3 8.2
392 .\" This file is in the public domain, so clarified as of
393 .\" 2009-05-17 by Arthur David Olson.