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