Debian Codegraph @

upstream/debian-trixie/man3/tzset.3

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