contrib/tzcode/newtzset.3.txt

   1 NEWTZSET(3)                Library Functions Manual                NEWTZSET(3)
   2
   3 NAME
   4        tzset - initialize time conversion information
   5
   6 SYNOPSIS
   7        #include <time.h>
   8
   9        timezone_t tzalloc(char const *TZ);
  10
  11        void tzfree(timezone_t tz);
  12
  13        void tzset(void);
  14
  15        cc ... -ltz
  16
  17 DESCRIPTION
  18        Tzalloc allocates and returns a time zone object described by TZ.  If
  19        TZ is not a valid time zone description, or if the object cannot be
  20        allocated, tzalloc returns a null pointer and sets errno.
  21
  22        Tzfree frees a time zone object tz, which should have been successfully
  23        allocated by tzalloc.  This invalidates any tm_zone pointers that tz
  24        was used to set.
  25
  26        Tzset acts like tzalloc(getenv("TZ")), except it saves any resulting
  27        time zone object into internal storage that is accessed by localtime,
  28        localtime_r, and mktime.  The anonymous shared time zone object is
  29        freed by the next call to tzset.  If the implied call to tzalloc fails,
  30        tzset falls back on UTC.
  31
  32        If TZ is null, the best available approximation to local wall clock
  33        time, as specified by the tzfile(5)-format file localtime in the system
  34        time conversion information directory, is used.  If TZ is the empty
  35        string, Universal Time (UT) is used, with the abbreviation "UTC" and
  36        without leap second correction; please see newctime(3) for more about
  37        UT, UTC, and leap seconds.  If TZ is nonnull and nonempty:
  38
  39               if the value begins with a colon, it is used as a pathname of a
  40               file from which to read the time conversion information;
  41
  42               if the value does not begin with a colon, it is first used as
  43               the pathname of a file from which to read the time conversion
  44               information, and, if that file cannot be read, is used directly
  45               as a specification of the time conversion information.
  46
  47        When TZ is used as a pathname, if it begins with a slash, it is used as
  48        an absolute pathname; otherwise, it is used as a pathname relative to a
  49        system time conversion information directory.  The file must be in the
  50        format specified in tzfile(5).
  51
  52        When TZ is used directly as a specification of the time conversion
  53        information, it must have the following syntax (spaces inserted for
  54        clarity):
  55
  56               stdoffset[dst[offset][,rule]]
  57
  58        Where:
  59
  60               std and dst    Three or more bytes that are the designation for
  61                              the standard (std) or summer (dst) time zone.
  62                              Only std is required; if dst is missing, then
  63                              summer time does not apply in this locale.
  64                              Upper- and lowercase letters are explicitly
  65                              allowed.  Any characters except a leading colon
  66                              (:), digits, comma (,), ASCII minus (-), ASCII
  67                              plus (+), and NUL bytes are allowed.
  68                              Alternatively, a designation can be surrounded by
  69                              angle brackets < and >; in this case, the
  70                              designation can contain any characters other than
  71                              > and NUL.
  72
  73               offset         Indicates the value one must add to the local
  74                              time to arrive at Coordinated Universal Time.
  75                              The offset has the form:
  76
  77                                     hh[:mm[:ss]]
  78
  79                              The minutes (mm) and seconds (ss) are optional.
  80                              The hour (hh) is required and may be a single
  81                              digit.  The offset following std is required.  If
  82                              no offset follows dst, summer time is assumed to
  83                              be one hour ahead of standard time.  One or more
  84                              digits may be used; the value is always
  85                              interpreted as a decimal number.  The hour must
  86                              be between zero and 24, and the minutes (and
  87                              seconds) - if present - between zero and 59.  If
  88                              preceded by a "-", the time zone shall be east of
  89                              the Prime Meridian; otherwise it shall be west
  90                              (which may be indicated by an optional preceding
  91                              "+".
  92
  93               rule           Indicates when to change to and back from summer
  94                              time.  The rule has the form:
  95
  96                                     date/time,date/time
  97
  98                              where the first date describes when the change
  99                              from standard to summer time occurs and the
 100                              second date describes when the change back
 101                              happens.  Each time field describes when, in
 102                              current local time, the change to the other time
 103                              is made.  As an extension to POSIX, daylight
 104                              saving is assumed to be in effect all year if it
 105                              begins January 1 at 00:00 and ends December 31 at
 106                              24:00 plus the difference between daylight saving
 107                              and standard time, leaving no room for standard
 108                              time in the calendar.
 109
 110                              The format of date is one of the following:
 111
 112                              Jn        The Julian day n (1 <= n <= 365).  Leap
 113                                        days are not counted; that is, in all
 114                                        years - including leap years - February
 115                                        28 is day 59 and March 1 is day 60.  It
 116                                        is impossible to explicitly refer to
 117                                        the occasional February 29.
 118
 119                              n         The zero-based Julian day
 120                                        (0 <= n <= 365).  Leap days are
 121                                        counted, and it is possible to refer to
 122                                        February 29.
 123
 124                              Mm.n.d    The d'th day (0 <= d <= 6) of week n of
 125                                        month m of the year (1 <= n <= 5,
 126                                        1 <= m <= 12, where week 5 means "the
 127                                        last d day in month m" which may occur
 128                                        in either the fourth or the fifth
 129                                        week).  Week 1 is the first week in
 130                                        which the d'th day occurs.  Day zero is
 131                                        Sunday.
 132
 133                              The time has the same format as offset except
 134                              that POSIX does not allow a leading sign ("-" or
 135                              "+").  As an extension to POSIX, the hours part
 136                              of time can range from -167 through 167; this
 137                              allows for unusual rules such as "the Saturday
 138                              before the first Sunday of March".  The default,
 139                              if time is not given, is 02:00:00.
 140
 141        Here are some examples of TZ values that directly specify the time zone
 142        rules; they use some of the extensions to POSIX.
 143
 144        EST5   stands for US Eastern Standard Time (EST), 5 hours behind UTC,
 145               without daylight saving.
 146
 147        FJT-12FJST,M11.1.0,M1.3.4/75
 148               stands for Fiji Time (FJT) and Fiji Summer Time (FJST), 12 hours
 149               ahead of UTC, springing forward on November's first Sunday at
 150               02:00, and falling back on January's third Thursday at 75:00
 151               (i.e., 03:00 on the first Sunday on or after January 18).
 152
 153        IST-2IDT,M3.4.4/26,M10.5.0
 154               stands for Israel Standard Time (IST) and Israel Daylight Time
 155               (IDT), 2 hours ahead of UTC, springing forward on March's fourth
 156               Thursday at 26:00 (i.e., 02:00 on the first Friday on or after
 157               March 23), and falling back on October's last Sunday at 02:00.
 158
 159        WART4WARST,J1/0,J365/25
 160               stands for Western Argentina Summer Time (WARST), 3 hours behind
 161               UTC.  There is a dummy fall-back transition on December 31 at
 162               25:00 daylight saving time (i.e., 24:00 standard time,
 163               equivalent to January 1 at 00:00 standard time), and a
 164               simultaneous spring-forward transition on January 1 at 00:00
 165               standard time, so daylight saving time is in effect all year and
 166               the initial WART is a placeholder.
 167
 168        WGT3WGST,M3.5.0/-2,M10.5.0/-1
 169               stands for Western Greenland Time (WGT) and Western Greenland
 170               Summer Time (WGST), 3 hours behind UTC, where clocks follow the
 171               EU rules of springing forward on March's last Sunday at 01:00
 172               UTC (-02:00 local time) and falling back on October's last
 173               Sunday at 01:00 UTC (-01:00 local time).
 174
 175        If no rule is present in TZ, the rules specified by the
 176        tzfile(5)-format file posixrules in the system time conversion
 177        information directory are used, with the standard and summer time
 178        offsets from UTC replaced by those specified by the offset values in
 179        TZ.
 180
 181        For compatibility with System V Release 3.1, a semicolon (;) may be
 182        used to separate the rule from the rest of the specification.
 183
 184 FILES
 185        /usr/local/etc/zoneinfo             time zone information directory
 186        /usr/local/etc/zoneinfo/localtime   local time zone file
 187        /usr/local/etc/zoneinfo/posixrules  used with POSIX-style TZ's
 188        /usr/local/etc/zoneinfo/GMT         for UTC leap seconds
 189
 190        If /usr/local/etc/zoneinfo/GMT is absent, UTC leap seconds are loaded
 191        from /usr/local/etc/zoneinfo/posixrules.
 192
 193 SEE ALSO
 194        getenv(3), newctime(3), newstrftime(3), time(2), tzfile(5)
 195
 196                                                                    NEWTZSET(3)