[BACK]Return to tzset.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / time

Annotation of src/lib/libc/time/tzset.3, Revision 1.37.2.2

1.37.2.2! pgoyette    1: .\"    $NetBSD: tzset.3,v 1.39 2018/10/19 23:05:35 christos Exp $
        !             2: .Dd October 19, 2018
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.37.2.2! pgoyette   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.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
1.34      wiz        98: .Dv \-1
                     99: is returned and
1.33      christos  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")) ,
1.37.2.2! pgoyette  107: except it saves any resulting timezone object into internal
1.30      christos  108: storage that is accessed by
                    109: .Fn localtime ,
                    110: .Fn localtime_r ,
                    111: and
                    112: .Fn mktime .
1.37.2.2! pgoyette  113: The anonymous shared timezone object is freed by the next call to
1.30      christos  114: .Fn tzset .
                    115: If the implied call to
                    116: .Fn tzalloc
                    117: fails,
                    118: .Fn tzset
1.37      christos  119: falls back on Universal Time (UT).
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.37      christos  134: UT is used, with the abbreviation
1.26      christos  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.37.2.1  pgoyette  178: or the alternative
                    179: .Cm ( dst
                    180: such as daylight saving time)
1.37.2.2! pgoyette  181: timezone.
1.21      wiz       182: Only
1.15      wiz       183: .Cm std
1.1       jtc       184: is required; if
1.15      wiz       185: .Cm dst
1.37.2.1  pgoyette  186: is missing, then daylight saving time does not apply in this locale.
1.21      wiz       187: Upper- and lowercase letters are explicitly allowed.
                    188: Any characters except a leading colon (:), digits, comma (,), minus (-),
1.29      christos  189: plus (+), and NUL bytes are allowed.
1.35      christos  190: Alternatively, a designation can be surrounded by angle brackets
1.36      wiz       191: .Dv <
1.35      christos  192: and
1.36      wiz       193: .Dv > ;
1.35      christos  194: in this case, the designation can contain any characters other than
1.36      wiz       195: .Dv >
1.35      christos  196: and
                    197: .Dv NUL .
1.15      wiz       198: .It Cm offset
1.1       jtc       199: Indicates the value one must add to the local time to arrive at
1.21      wiz       200: Coordinated Universal Time.
                    201: The
1.15      wiz       202: .Cm offset
1.1       jtc       203: has the form:
1.15      wiz       204: .Sm off
                    205: .Bd -literal -offset indent
                    206: .Cm hh Oo
                    207: .Cm :mm Oo
                    208: .Cm :ss Oc Oc
                    209: .Ed
                    210: .Sm on
                    211: .Pp
1.1       jtc       212: The minutes
1.15      wiz       213: .Cm ( mm )
1.1       jtc       214: and seconds
1.15      wiz       215: .Cm ( ss )
1.21      wiz       216: are optional.
                    217: The hour
1.15      wiz       218: .Cm ( hh )
1.21      wiz       219: is required and may be a single digit.
                    220: The
1.15      wiz       221: .Cm offset
1.1       jtc       222: following
1.15      wiz       223: .Cm std
1.21      wiz       224: is required.
                    225: If no
1.15      wiz       226: .Cm offset
1.1       jtc       227: follows
1.15      wiz       228: .Cm dst ,
1.37.2.1  pgoyette  229: daylight saving time is assumed to be one hour ahead of standard time.
1.21      wiz       230: One or more digits may be used; the value is always interpreted as a
                    231: decimal number.
                    232: The hour must be between zero and 24, and the minutes (and
1.29      christos  233: seconds) \*(en if present \*(en between zero and 59.
1.21      wiz       234: If preceded by a
1.15      wiz       235: .Dq -
1.37.2.2! pgoyette  236: the timezone shall be east of the Prime Meridian; otherwise it shall be
1.1       jtc       237: west (which may be indicated by an optional preceding
1.15      wiz       238: .Dq + ) .
                    239: .It Cm rule
1.37.2.1  pgoyette  240: Indicates when to change to and back from daylight saving time.
1.21      wiz       241: The
1.15      wiz       242: .Cm rule
1.1       jtc       243: has the form:
1.15      wiz       244: .Sm off
1.17      wiz       245: .Bd -literal -offset indent
1.15      wiz       246: .Xo
                    247: .Cm date No /
                    248: .Cm time No ,
                    249: .Cm date No /
                    250: .Cm time
                    251: .Xc
                    252: .Ed
                    253: .Sm on
                    254: .Pp
1.1       jtc       255: where the first
1.15      wiz       256: .Cm date
1.37.2.1  pgoyette  257: describes when the change from standard to daylight saving time occurs and the
1.1       jtc       258: second
1.15      wiz       259: .Cm date
1.21      wiz       260: describes when the change back happens.
                    261: Each
1.15      wiz       262: .Cm time
1.1       jtc       263: field describes when, in current local time, the change to the other
                    264: time is made.
1.26      christos  265: As an extension to POSIX, daylight saving is assumed to be in effect
                    266: all year if it begins January 1 at 00:00 and ends December 31 at
                    267: 24:00 plus the difference between daylight saving and standard time,
                    268: leaving no room for standard time in the calendar.
1.1       jtc       269: The format of
1.15      wiz       270: .Fa date
1.1       jtc       271: is one of the following:
1.15      wiz       272: .Bl -tag -width "The Julian day" -compact
                    273: .It Cm J Ns Ar n
1.1       jtc       274: The Julian day
1.15      wiz       275: .Ar n
1.20      ross      276: (1 \*[Le]
1.15      wiz       277: .Ar n
1.20      ross      278: \*[Le] 365).
1.29      christos  279: Leap days are not counted; that is, in all years \*(en including leap
                    280: years \*(en February 28 is day 59 and March 1 is day 60.
1.21      wiz       281: It is impossible to explicitly refer to the occasional February 29.
1.15      wiz       282: .It Ar n
1.19      ross      283: The zero-based Julian day (0\ \*[Le]
1.15      wiz       284: .Ar n
1.21      wiz       285: \*[Le]\ 365).
                    286: Leap days are counted, and it is possible to refer to
1.15      wiz       287: February 29.
                    288: .Sm off
1.23      joerg     289: .It Cm M Ns Ar m No . Ar n No . Ar d
1.15      wiz       290: .Sm on
1.1       jtc       291: The
1.15      wiz       292: .Ar d Ns 'th
1.1       jtc       293: day
1.19      ross      294: (0 \*[Le]
1.15      wiz       295: .Ar d
1.19      ross      296: \*[Le]\ 6) of week
1.15      wiz       297: .Ar n
1.1       jtc       298: of month
1.15      wiz       299: .Ar m
1.1       jtc       300: of the year
1.19      ross      301: (1 \*[Le]
1.15      wiz       302: .Ar n
1.19      ross      303: \*[Le]\ 5, 1 \*[Le]
1.15      wiz       304: .Ar m
1.19      ross      305: \*[Le]\ 12, where week 5 means
1.15      wiz       306: .Dq the\ last Ar d No day\ in\ month Ar m
1.21      wiz       307: which may occur in either the fourth or the fifth week).
                    308: Week 1 is the first week in which the
1.15      wiz       309: .Ar d Ns 'th
1.21      wiz       310: day occurs.
                    311: Day zero is Sunday.
1.15      wiz       312: .El
1.1       jtc       313: The
1.15      wiz       314: .Cm time
1.1       jtc       315: has the same format as
1.15      wiz       316: .Cm offset
1.26      christos  317: except that POSIX does not allow a leading sign
1.15      wiz       318: .Dq -
1.1       jtc       319: or
1.15      wiz       320: .Dq +
1.21      wiz       321: is allowed.
1.26      christos  322: As an extension to POSIX, the hours part of
                    323: .Cm time
1.29      christos  324: can range from \-167 through 167; this allows for unusual rules such as
1.26      christos  325: .Dq the Saturday before the first Sunday of March .
1.21      wiz       326: The default, if
1.15      wiz       327: .Cm time
1.1       jtc       328: is not given, is
1.15      wiz       329: .Cm 02:00:00 .
                    330: .El
1.26      christos  331: .Pp
                    332: Here are some examples of
                    333: .Va TZ
1.37.2.2! pgoyette  334: values that directly specify the timezone rules; they use some of the
1.26      christos  335: extensions to POSIX.
                    336: .Bl -tag
                    337: .It EST5
1.27      christos  338: stands for US Eastern Standard
1.37      christos  339: Time (EST), 5 hours behind UT, without daylight saving.
1.31      christos  340: .It FJT\-12FJST,M11.1.0,M1.3.4/75
1.37.2.1  pgoyette  341: .It <+12>\-12<+13>,M11.1.0,M1.2.1/147
                    342: stands for Fiji time, 12 hours ahead
1.37      christos  343: of UT, springing forward on November's first Sunday at 02:00, and
1.37.2.1  pgoyette  344: falling back on January's second Monday at 147:00 (i.e., 03:00 on the
                    345: first Sunday on or after January 14).
                    346: The abbreviations for standard and daylight saving time are
                    347: .Qq +12
                    348: and
                    349: .Qq +13 .
1.29      christos  350: .It IST\-2IDT,M3.4.4/26,M10.5.0
1.26      christos  351: stands for Israel Standard Time (IST) and Israel Daylight Time (IDT),
1.37      christos  352: 2 hours ahead of UT, springing forward on March's fourth
1.28      christos  353: Thursday at 26:00 (i.e., 02:00 on the first Friday on or after March
1.26      christos  354: 23), and falling back on October's last Sunday at 02:00.
1.37.2.1  pgoyette  355: .It <\-04>4<\-03>,J1/0,J365/25
                    356: stands for permanent daylight saving time, 3 hours behind UT with
                    357: abbreviation
                    358: .Qq \-03 .
1.26      christos  359: There is a dummy fall-back transition on December 31 at 25:00 daylight
                    360: saving time (i.e., 24:00 standard time, equivalent to January 1 at
                    361: 00:00 standard time), and a simultaneous spring-forward transition on
                    362: January 1 at 00:00 standard time, so daylight saving time is in effect
                    363: all year and the initial
1.37.2.1  pgoyette  364: .Em <\-04>
1.26      christos  365: is a placeholder.
1.37.2.1  pgoyette  366: .It <\-03>3<\-02>,M3.5.0/\-2,M10.5.0/\-1
                    367: stands for time in western Greenland, 3 hours behind UT, where clocks
                    368: follow the EU rules of
1.37      christos  369: springing forward on March's last Sunday at 01:00 UT (\-02:00 local
1.37.2.1  pgoyette  370: time, i.e., 22:00 the previous day) and falling back on October's last
                    371: Sunday at 01:00 UT (\-01:00 local time, i.e., 23:00 the previous day).
                    372: The abbreviations for standard and daylight saving time are
                    373: .Qq \-03
                    374: and
                    375: .Qq \-02 .
1.26      christos  376: .El
                    377: .Pp
1.1       jtc       378: If no
1.15      wiz       379: .Cm rule
1.1       jtc       380: is present in
1.15      wiz       381: .Ev TZ ,
                    382: the rules specified by the
                    383: .Xr tzfile 5
                    384: format file
                    385: .Pa posixrules
                    386: in
                    387: .Pa /usr/share/zoneinfo
1.37.2.1  pgoyette  388: are used, with the standard and daylight saving time offsets from UT replaced
1.15      wiz       389: by those specified by the
                    390: .Cm offset
1.1       jtc       391: values in
1.15      wiz       392: .Ev TZ .
                    393: .Pp
                    394: For compatibility with System V Release 3.1, a semicolon (;) may be
                    395: used to separate the
                    396: .Cm rule
1.1       jtc       397: from the rest of the specification.
1.15      wiz       398: .Sh FILES
                    399: .Bl -tag -width /usr/share/zoneinfo/posixrules -compact
                    400: .It Pa /etc/localtime
1.37.2.2! pgoyette  401: local timezone file
1.15      wiz       402: .It Pa /usr/share/zoneinfo
1.37.2.2! pgoyette  403: local timezone information directory
        !           404: .\" .It Pa /usr/share/zoneinfo/localtime
        !           405: .\" local timezone file
1.15      wiz       406: .It Pa /usr/share/zoneinfo/posixrules
                    407: used with POSIX-style TZ's
                    408: .It Pa /usr/share/zoneinfo/GMT
                    409: for UTC leap seconds
                    410: .El
                    411: .Pp
1.1       jtc       412: If
1.15      wiz       413: .Pa /usr/share/zoneinfo/GMT
                    414: is absent, UTC leap seconds are loaded from
                    415: .Pa /usr/share/zoneinfo/posixrules .
                    416: .Sh SEE ALSO
1.16      wiz       417: .Xr ctime 3 ,
1.15      wiz       418: .Xr getenv 3 ,
                    419: .Xr strftime 3 ,
                    420: .Xr time 3 ,
                    421: .Xr tzfile 5
                    422: .Sh STANDARDS
1.10      kleink    423: The
1.25      wiz       424: .Fn tzset
1.10      kleink    425: function conforms to
1.15      wiz       426: .St -p1003.1-88 .
1.24      mlelstv   427: .\" @(#)newtzset.3     8.2
                    428: .\" This file is in the public domain, so clarified as of
                    429: .\" 2009-05-17 by Arthur David Olson.

CVSweb <webmaster@jp.NetBSD.org>