Debian Codegraph @

upstream/debian-unstable/man3/tzset.3

raw
1 '\" t
2 .\" Copyright 1993, David Metcalfe <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH tzset 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 tzset, tzname, timezone, daylight \- initialize time conversion information
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <time.h>
16 .P
17 .B void tzset(void);
18 .P
19 .BI "extern char *" tzname [2];
20 .BI "extern long " timezone ;
21 .BI "extern int " daylight ;
22 .fi
23 .P
24 .RS -4
25 Feature Test Macro Requirements for glibc (see
26 .BR feature_test_macros (7)):
27 .RE
28 .P
29 .BR tzset ():
30 .nf
31 _POSIX_C_SOURCE
32 .fi
33 .P
34 .IR tzname :
35 .nf
36 _POSIX_C_SOURCE
37 .fi
38 .P
39 .IR timezone ,
40 .IR daylight :
41 .nf
42 _XOPEN_SOURCE
43 || /* glibc >= 2.19: */ _DEFAULT_SOURCE
44 || /* glibc <= 2.19: */ _SVID_SOURCE
45 .fi
46 .SH DESCRIPTION
47 The
48 .BR tzset ()
49 function initializes the
50 .I tzname
51 variable from the
52 .B TZ
53 environment variable.
54 This function is automatically called by the
55 other time conversion functions that depend on the timezone.
56 In a System-V-like environment, it will also set the variables
57 .I timezone
58 (seconds West of UTC)
59 and
60 .I daylight
61 (to 0 if this timezone does not
62 have any daylight saving time rules, or to nonzero if there is a time,
63 past, present, or future when daylight saving time applies).
64 .P
65 The
66 .BR tzset ()
67 function initializes these variables to unspecified values if this
68 timezone is a geographical timezone like "America/New_York" (see below).
69 .P
70 If the
71 .B TZ
72 variable does not appear in the environment, the system timezone is used.
73 The system timezone is configured by copying, or linking, a file in the
74 .BR tzfile (5)
75 format to
76 .IR /etc/localtime .
77 A timezone database of these files may be located in the system
78 timezone directory (see the
79 .B FILES
80 section below).
81 .P
82 If the
83 .B TZ
84 variable does appear in the environment, but its value is empty,
85 or its value cannot be interpreted using any of the formats specified
86 below, then Coordinated Universal Time (UTC) is used.
87 .P
88 A nonempty value of
89 .B TZ
90 can be one of two formats,
91 either of which can be preceded by a colon which is ignored.
92 The first format is a string of characters that directly represent the
93 timezone to be used:
94 .P
95 .in +4n
96 .EX
97 .IR "std offset" [ dst [ offset ][, start [ /time ], end [ /time ]]]
98 .EE
99 .in
100 .P
101 There are no spaces in the specification.
102 The
103 .I std
104 string specifies an abbreviation for the timezone
105 and must be
106 three or more alphabetic characters.
107 When enclosed between the less-than (<) and greater-than (>) signs, the
108 character set is expanded to include the plus (+) sign, the minus (\-)
109 sign, and digits.
110 The
111 .I offset
112 string
113 immediately follows
114 .I std
115 and specifies the time value to be added to the local time
116 to get Coordinated Universal Time (UTC).
117 The
118 .I offset
119 is positive
120 if the local timezone is west of the Prime Meridian
121 and negative
122 if it is east.
123 The hour must be between 0 and 24, and the minutes and seconds 00 and 59:
124 .P
125 .in +4n
126 .EX
127 .RI [ + | \- ] hh [ :mm [ :ss ]]
128 .EE
129 .in
130 .P
131 The
132 .I dst
133 string and
134 .I offset
135 specify the name and offset for the
136 corresponding daylight saving timezone.
137 If the offset is omitted,
138 it defaults to one hour ahead of standard time.
139 .P
140 The
141 .I start
142 field specifies when daylight saving time goes into effect
143 and the
144 .I end
145 field specifies when the change is made back to
146 standard time.
147 These fields may have the following formats:
148 .TP
149 .RI J n
150 This specifies the Julian day with
151 .I n
152 between 1 and 365.
153 Leap days are not counted.
154 In this format, February 29 can't be represented;
155 February 28 is day 59, and March 1 is always day 60.
156 .TP
157 .I n
158 This specifies the zero-based Julian day with
159 .I n
160 between 0 and 365.
161 February 29 is counted in leap years.
162 .TP
163 .RI M m . w . d
164 This specifies day
165 .I d
166 .RI (0\~<=\~ d \~<=\~6)
167 of week
168 .I w
169 .RI (1\~<=\~ w \~<=\~5)
170 of month
171 .I m
172 .RI (1\~<=\~ m \~<=\~12).
173 Week 1 is
174 the first week in which day
175 .I d
176 occurs and week 5 is the last week
177 in which day
178 .I d
179 occurs.
180 Day 0 is a Sunday.
181 .P
182 The
183 .I time
184 fields specify when,
185 in the local time currently in effect,
186 the change to the other time occurs.
187 They use the same format as
188 .I offset
189 except that the hour can be in the range
190 .RB [ \-167 ,\~
191 .BR 167 ]
192 to represent times before and after the named day.
193 If omitted, the default is 02:00:00.
194 .P
195 Here is an example for New Zealand,
196 where the standard time (NZST) is 12 hours ahead of UTC,
197 and daylight saving time (NZDT), 13 hours ahead of UTC,
198 runs from September's last Sunday, at the default time 02:00:00,
199 to April's first Sunday at 03:00:00.
200 .P
201 .in +4n
202 .EX
203 TZ="NZST\-12:00:00NZDT\-13:00:00,M9.5.0,M4.1.0/3"
204 .EE
205 .in
206 .P
207 The second
208 \[em]or "geographical"\[em]
209 format specifies that the timezone information should be read
210 from a file:
211 .P
212 .in +4n
213 .EX
214 filespec
215 .EE
216 .in
217 .P
218 The
219 .I filespec
220 specifies a
221 .BR tzfile (5)-format
222 file to read the timezone information from.
223 If
224 .I filespec
225 does not begin with a
226 .RB \[aq] / \[aq],
227 the file specification is
228 relative to the system timezone directory.
229 If the specified file cannot be read or interpreted,
230 Coordinated Universal Time (UTC) is used;
231 however, applications should not depend on random
232 .I filespec
233 values standing for UTC, as
234 .B TZ
235 formats may be extended in the future.
236 .P
237 Here's an example, once more for New Zealand:
238 .P
239 .in +4n
240 .EX
241 TZ="Pacific/Auckland"
242 .EE
243 .in
244 .SH ENVIRONMENT
245 .TP
246 .B TZ
247 If this variable is set its value takes precedence over the system
248 configured timezone.
249 .TP
250 .B TZDIR
251 If this variable is set its value takes precedence over the system
252 configured timezone database directory path.
253 .SH FILES
254 .TP
255 .I /etc/localtime
256 The system timezone file.
257 .TP
258 .I /usr/share/zoneinfo/
259 The system timezone database directory.
260 .TP
261 .I /usr/share/zoneinfo/posixrules
262 When a TZ string includes a dst timezone without anything following it,
263 then this file is used for the start/end rules.
264 It is in the
265 .BR tzfile (5)
266 format.
267 By default, the zoneinfo Makefile hard links it to the
268 .IR America/New_York " tzfile."
269 .P
270 Above are the current standard file locations, but they are
271 configurable when glibc is compiled.
272 .SH ATTRIBUTES
273 For an explanation of the terms used in this section, see
274 .BR attributes (7).
275 .TS
276 allbox;
277 lbx lb lb
278 l l l.
279 Interface Attribute Value
280 T{
281 .na
282 .nh
283 .BR tzset ()
284 T} Thread safety MT-Safe env locale
285 .TE
286 .SH STANDARDS
287 POSIX.1-2024.
288 .SH HISTORY
289 .TP
290 .BR tzset ()
291 .TQ
292 .I tzname
293 POSIX.1-1988, SVr4, 4.3BSD.
294 .TP
295 .I timezone
296 .TQ
297 .I daylight
298 POSIX.1-2001 (XSI), SVr4, 4.3BSD.
299 .P
300 4.3BSD had a function
301 .BI "char *timezone(" zone ", " dst )
302 that returned the
303 name of the timezone corresponding to its first argument (minutes
304 West of UTC).
305 If the second argument was 0, the standard name was used,
306 otherwise the daylight saving time version.
307 .SH CAVEATS
308 Because the values of
309 .IR tzname ,
310 .IR timezone ,
311 and
312 .I daylight
313 are often unspecified,
314 and accessing them can lead to
315 undefined behavior in multithreaded applications,
316 code should instead obtain time zone offset and abbreviations from the
317 .I tm_gmtoff
318 and
319 .I tm_zone
320 members of the broken-down time structure
321 .BR tm (3type).
322 .SH BUGS
323 Since this function does not report errors,
324 there's no way to know if the value of TZ represents a valid time zone.
325 .SH SEE ALSO
326 .BR date (1),
327 .BR gettimeofday (2),
328 .BR time (2),
329 .BR ctime (3),
330 .BR getenv (3),
331 .BR tzfile (5)