Annotation of src/lib/libc/time/tzset.3, Revision 1.33
1.33 ! christos 1: .\" $NetBSD: tzset.3,v 1.32 2015/04/05 08:36:38 pgoyette Exp $
! 2: .Dd October 29, 2015
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
40: is not a valid time zone description, or if the object cannot be allocated,
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.33 ! christos 92: Finally, the
! 93: .Fn tzgetgmtoff
! 94: function acts like
! 95: .Fn tzgetname
! 96: only it returns the offset in seconds from GMT for the timezone.
! 97: If there is no match, then
! 98: .Dv \-1
! 99: is returned and
! 100: .Va errno
! 101: is set to
! 102: .Dv ESRCH .
1.30 christos 103: The
1.15 wiz 104: .Fn tzset
1.30 christos 105: function acts like
106: .Dv tzalloc(getenv("TZ")) ,
107: except it saves any resulting time zone object into internal
108: storage that is accessed by
109: .Fn localtime ,
110: .Fn localtime_r ,
111: and
112: .Fn mktime .
113: The anonymous shared time zone object is freed by the next call to
114: .Fn tzset .
115: If the implied call to
116: .Fn tzalloc
117: fails,
118: .Fn tzset
119: falls back on UTC.
1.1 jtc 120: If
1.15 wiz 121: .Ev TZ
1.30 christos 122: is
123: .Dv NULL ,
1.15 wiz 124: the best available approximation to local wall clock time, as
125: specified by the
126: .Xr tzfile 5
127: format file
128: .Pa /etc/localtime
129: is used by
130: .Xr localtime 3 .
1.1 jtc 131: If
1.15 wiz 132: .Ev TZ
1.30 christos 133: appears in the environment but its value is the empty string,
1.26 christos 134: Universal Time (UT) is used, with the abbreviation
135: .Dq UTC
136: and without leap second correction; please see
137: .Xr ctime 3 .
1.21 wiz 138: If
1.15 wiz 139: .Ev TZ
1.30 christos 140: is nonnull and nonempty:
1.15 wiz 141: .Bl -dash
142: .It
1.1 jtc 143: if the value begins with a colon, it is used as a pathname of a file
144: from which to read the time conversion information;
1.15 wiz 145: .It
1.1 jtc 146: if the value does not begin with a colon, it is first used as the
147: pathname of a file from which to read the time conversion information,
1.15 wiz 148: and, if that file cannot be read, is used directly as a specification
149: of the time conversion information.
150: .El
151: .Pp
1.1 jtc 152: When
1.15 wiz 153: .Ev TZ
154: is used as a pathname, if it begins with a slash, it is used as an
155: absolute pathname; otherwise, it is used as a pathname relative to
156: .Pa /usr/share/zoneinfo .
1.1 jtc 157: The file must be in the format specified in
1.15 wiz 158: .Xr tzfile 5 .
159: .Pp
1.1 jtc 160: When
1.15 wiz 161: .Ev TZ
1.1 jtc 162: is used directly as a specification of the time conversion information,
163: it must have the following syntax (spaces inserted for clarity):
1.15 wiz 164: .Sm off
165: .Bd -literal -offset indent
166: .Cm std Cm offset Oo
167: .Cm dst Oo
168: .Cm offset Oc Oo
169: .No , Cm rule Oc Oc
170: .Ed
171: .Sm on
172: .Pp
173: where:
174: .Bl -tag -width "std and dst" -compact
175: .It Cm std No and Cm dst
1.1 jtc 176: Three or more bytes that are the designation for the standard
1.15 wiz 177: .Cm ( std )
1.1 jtc 178: or summer
1.15 wiz 179: .Cm ( dst )
1.21 wiz 180: time zone.
181: Only
1.15 wiz 182: .Cm std
1.1 jtc 183: is required; if
1.15 wiz 184: .Cm dst
1.1 jtc 185: is missing, then summer time does not apply in this locale.
1.21 wiz 186: Upper- and lowercase letters are explicitly allowed.
187: Any characters except a leading colon (:), digits, comma (,), minus (-),
1.29 christos 188: plus (+), and NUL bytes are allowed.
1.15 wiz 189: .It Cm offset
1.1 jtc 190: Indicates the value one must add to the local time to arrive at
1.21 wiz 191: Coordinated Universal Time.
192: The
1.15 wiz 193: .Cm offset
1.1 jtc 194: has the form:
1.15 wiz 195: .Sm off
196: .Bd -literal -offset indent
197: .Cm hh Oo
198: .Cm :mm Oo
199: .Cm :ss Oc Oc
200: .Ed
201: .Sm on
202: .Pp
1.1 jtc 203: The minutes
1.15 wiz 204: .Cm ( mm )
1.1 jtc 205: and seconds
1.15 wiz 206: .Cm ( ss )
1.21 wiz 207: are optional.
208: The hour
1.15 wiz 209: .Cm ( hh )
1.21 wiz 210: is required and may be a single digit.
211: The
1.15 wiz 212: .Cm offset
1.1 jtc 213: following
1.15 wiz 214: .Cm std
1.21 wiz 215: is required.
216: If no
1.15 wiz 217: .Cm offset
1.1 jtc 218: follows
1.15 wiz 219: .Cm dst ,
1.21 wiz 220: summer time is assumed to be one hour ahead of standard time.
221: One or more digits may be used; the value is always interpreted as a
222: decimal number.
223: The hour must be between zero and 24, and the minutes (and
1.29 christos 224: seconds) \*(en if present \*(en between zero and 59.
1.21 wiz 225: If preceded by a
1.15 wiz 226: .Dq -
1.1 jtc 227: the time zone shall be east of the Prime Meridian; otherwise it shall be
228: west (which may be indicated by an optional preceding
1.15 wiz 229: .Dq + ) .
230: .It Cm rule
1.21 wiz 231: Indicates when to change to and back from summer time.
232: The
1.15 wiz 233: .Cm rule
1.1 jtc 234: has the form:
1.15 wiz 235: .Sm off
1.17 wiz 236: .Bd -literal -offset indent
1.15 wiz 237: .Xo
238: .Cm date No /
239: .Cm time No ,
240: .Cm date No /
241: .Cm time
242: .Xc
243: .Ed
244: .Sm on
245: .Pp
1.1 jtc 246: where the first
1.15 wiz 247: .Cm date
1.1 jtc 248: describes when the change from standard to summer time occurs and the
249: second
1.15 wiz 250: .Cm date
1.21 wiz 251: describes when the change back happens.
252: Each
1.15 wiz 253: .Cm time
1.1 jtc 254: field describes when, in current local time, the change to the other
255: time is made.
1.26 christos 256: As an extension to POSIX, daylight saving is assumed to be in effect
257: all year if it begins January 1 at 00:00 and ends December 31 at
258: 24:00 plus the difference between daylight saving and standard time,
259: leaving no room for standard time in the calendar.
1.1 jtc 260: The format of
1.15 wiz 261: .Fa date
1.1 jtc 262: is one of the following:
1.15 wiz 263: .Bl -tag -width "The Julian day" -compact
264: .It Cm J Ns Ar n
1.1 jtc 265: The Julian day
1.15 wiz 266: .Ar n
1.20 ross 267: (1 \*[Le]
1.15 wiz 268: .Ar n
1.20 ross 269: \*[Le] 365).
1.29 christos 270: Leap days are not counted; that is, in all years \*(en including leap
271: years \*(en February 28 is day 59 and March 1 is day 60.
1.21 wiz 272: It is impossible to explicitly refer to the occasional February 29.
1.15 wiz 273: .It Ar n
1.19 ross 274: The zero-based Julian day (0\ \*[Le]
1.15 wiz 275: .Ar n
1.21 wiz 276: \*[Le]\ 365).
277: Leap days are counted, and it is possible to refer to
1.15 wiz 278: February 29.
279: .Sm off
1.23 joerg 280: .It Cm M Ns Ar m No . Ar n No . Ar d
1.15 wiz 281: .Sm on
1.1 jtc 282: The
1.15 wiz 283: .Ar d Ns 'th
1.1 jtc 284: day
1.19 ross 285: (0 \*[Le]
1.15 wiz 286: .Ar d
1.19 ross 287: \*[Le]\ 6) of week
1.15 wiz 288: .Ar n
1.1 jtc 289: of month
1.15 wiz 290: .Ar m
1.1 jtc 291: of the year
1.19 ross 292: (1 \*[Le]
1.15 wiz 293: .Ar n
1.19 ross 294: \*[Le]\ 5, 1 \*[Le]
1.15 wiz 295: .Ar m
1.19 ross 296: \*[Le]\ 12, where week 5 means
1.15 wiz 297: .Dq the\ last Ar d No day\ in\ month Ar m
1.21 wiz 298: which may occur in either the fourth or the fifth week).
299: Week 1 is the first week in which the
1.15 wiz 300: .Ar d Ns 'th
1.21 wiz 301: day occurs.
302: Day zero is Sunday.
1.15 wiz 303: .El
1.1 jtc 304: The
1.15 wiz 305: .Cm time
1.1 jtc 306: has the same format as
1.15 wiz 307: .Cm offset
1.26 christos 308: except that POSIX does not allow a leading sign
1.15 wiz 309: .Dq -
1.1 jtc 310: or
1.15 wiz 311: .Dq +
1.21 wiz 312: is allowed.
1.26 christos 313: As an extension to POSIX, the hours part of
314: .Cm time
1.29 christos 315: can range from \-167 through 167; this allows for unusual rules such as
1.26 christos 316: .Dq the Saturday before the first Sunday of March .
1.21 wiz 317: The default, if
1.15 wiz 318: .Cm time
1.1 jtc 319: is not given, is
1.15 wiz 320: .Cm 02:00:00 .
321: .El
1.26 christos 322: .Pp
323: Here are some examples of
324: .Va TZ
325: values that directly specify the time zone rules; they use some of the
326: extensions to POSIX.
327: .Bl -tag
328: .It EST5
1.27 christos 329: stands for US Eastern Standard
330: Time (EST), 5 hours behind UTC, without daylight saving.
1.31 christos 331: .It FJT\-12FJST,M11.1.0,M1.3.4/75
1.26 christos 332: stands for Fiji Time (FJT) and Fiji Summer Time (FJST), 12 hours ahead
1.31 christos 333: of UTC, springing forward on November's first Sunday at 02:00, and
1.26 christos 334: falling back on January's third Thursday at 75:00 (i.e., 03:00 on the
335: first Sunday on or after January 18).
1.29 christos 336: .It IST\-2IDT,M3.4.4/26,M10.5.0
1.26 christos 337: stands for Israel Standard Time (IST) and Israel Daylight Time (IDT),
338: 2 hours ahead of UTC, springing forward on March's fourth
1.28 christos 339: Thursday at 26:00 (i.e., 02:00 on the first Friday on or after March
1.26 christos 340: 23), and falling back on October's last Sunday at 02:00.
341: .It WART4WARST,J1/0,J365/25
342: stands for Western Argentina Summer Time (WARST), 3 hours behind UTC.
343: There is a dummy fall-back transition on December 31 at 25:00 daylight
344: saving time (i.e., 24:00 standard time, equivalent to January 1 at
345: 00:00 standard time), and a simultaneous spring-forward transition on
346: January 1 at 00:00 standard time, so daylight saving time is in effect
347: all year and the initial
348: .Em WART
349: is a placeholder.
1.29 christos 350: .It WGT3WGST,M3.5.0/\-2,M10.5.0/\-1
1.27 christos 351: stands for Western Greenland Time (WGT) and Western Greenland Summer
1.26 christos 352: Time (WGST), 3 hours behind UTC, where clocks follow the EU rules of
1.29 christos 353: springing forward on March's last Sunday at 01:00 UTC (\-02:00 local
1.26 christos 354: time) and falling back on October's last Sunday at 01:00 UTC
1.29 christos 355: (\-01:00 local time).
1.26 christos 356: .El
357: .Pp
1.1 jtc 358: If no
1.15 wiz 359: .Cm rule
1.1 jtc 360: is present in
1.15 wiz 361: .Ev TZ ,
362: the rules specified by the
363: .Xr tzfile 5
364: format file
365: .Pa posixrules
366: in
367: .Pa /usr/share/zoneinfo
368: are used, with the standard and summer time offsets from UTC replaced
369: by those specified by the
370: .Cm offset
1.1 jtc 371: values in
1.15 wiz 372: .Ev TZ .
373: .Pp
374: For compatibility with System V Release 3.1, a semicolon (;) may be
375: used to separate the
376: .Cm rule
1.1 jtc 377: from the rest of the specification.
1.15 wiz 378: .Sh FILES
379: .Bl -tag -width /usr/share/zoneinfo/posixrules -compact
380: .It Pa /etc/localtime
381: local time zone file
382: .It Pa /usr/share/zoneinfo
383: time zone information directory
384: .It Pa /usr/share/zoneinfo/posixrules
385: used with POSIX-style TZ's
386: .It Pa /usr/share/zoneinfo/GMT
387: for UTC leap seconds
388: .El
389: .Pp
1.1 jtc 390: If
1.15 wiz 391: .Pa /usr/share/zoneinfo/GMT
392: is absent, UTC leap seconds are loaded from
393: .Pa /usr/share/zoneinfo/posixrules .
394: .Sh SEE ALSO
1.16 wiz 395: .Xr ctime 3 ,
1.15 wiz 396: .Xr getenv 3 ,
397: .Xr strftime 3 ,
398: .Xr time 3 ,
399: .Xr tzfile 5
400: .Sh STANDARDS
1.10 kleink 401: The
1.25 wiz 402: .Fn tzset
1.10 kleink 403: function conforms to
1.15 wiz 404: .St -p1003.1-88 .
1.24 mlelstv 405: .\" @(#)newtzset.3 8.2
406: .\" This file is in the public domain, so clarified as of
407: .\" 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