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
  69               offset         Indicates the value one must add to the local
  70                              time to arrive at Coordinated Universal Time.
  71                              The offset has the form:
  72
  73                                     hh[:mm[:ss]]
  74
  75                              The minutes (mm) and seconds (ss) are optional.
  76                              The hour (hh) is required and may be a single
  77                              digit.  The offset following std is required.  If
  78                              no offset follows dst, summer time is assumed to
  79                              be one hour ahead of standard time.  One or more
  80                              digits may be used; the value is always
  81                              interpreted as a decimal number.  The hour must
  82                              be between zero and 24, and the minutes (and
  83                              seconds) - if present - between zero and 59.  If
  84                              preceded by a "-", the time zone shall be east of
  85                              the Prime Meridian; otherwise it shall be west
  86                              (which may be indicated by an optional preceding
  87                              "+".
  88
  89               rule           Indicates when to change to and back from summer
  90                              time.  The rule has the form:
  91
  92                                     date/time,date/time
  93
  94                              where the first date describes when the change
  95                              from standard to summer time occurs and the
  96                              second date describes when the change back
  97                              happens.  Each time field describes when, in
  98                              current local time, the change to the other time
  99                              is made.  As an extension to POSIX, daylight
 100                              saving is assumed to be in effect all year if it
 101                              begins January 1 at 00:00 and ends December 31 at
 102                              24:00 plus the difference between daylight saving
 103                              and standard time, leaving no room for standard
 104                              time in the calendar.
 105
 106                              The format of date is one of the following:
 107
 108                              Jn        The Julian day n (1 <= n <= 365).  Leap
 109                                        days are not counted; that is, in all
 110                                        years - including leap years - February
 111                                        28 is day 59 and March 1 is day 60.  It
 112                                        is impossible to explicitly refer to
 113                                        the occasional February 29.
 114
 115                              n         The zero-based Julian day
 116                                        (0 <= n <= 365).  Leap days are
 117                                        counted, and it is possible to refer to
 118                                        February 29.
 119
 120                              Mm.n.d    The d'th day (0 <= d <= 6) of week n of
 121                                        month m of the year (1 <= n <= 5,
 122                                        1 <= m <= 12, where week 5 means "the
 123                                        last d day in month m" which may occur
 124                                        in either the fourth or the fifth
 125                                        week).  Week 1 is the first week in
 126                                        which the d'th day occurs.  Day zero is
 127                                        Sunday.
 128
 129                              The time has the same format as offset except
 130                              that POSIX does not allow a leading sign ("-" or
 131                              "+").  As an extension to POSIX, the hours part
 132                              of time can range from -167 through 167; this
 133                              allows for unusual rules such as "the Saturday
 134                              before the first Sunday of March".  The default,
 135                              if time is not given, is 02:00:00.
 136
 137        Here are some examples of TZ values that directly specify the time zone
 138        rules; they use some of the extensions to POSIX.
 139
 140        EST5   stands for US Eastern Standard Time (EST), 5 hours behind UTC,
 141               without daylight saving.
 142
 143        FJT-12FJST,M11.1.0,M1.3.4/75
 144               stands for Fiji Time (FJT) and Fiji Summer Time (FJST), 12 hours
 145               ahead of UTC, springing forward on November's first Sunday at
 146               02:00, and falling back on January's third Thursday at 75:00
 147               (i.e., 03:00 on the first Sunday on or after January 18).
 148
 149        IST-2IDT,M3.4.4/26,M10.5.0
 150               stands for Israel Standard Time (IST) and Israel Daylight Time
 151               (IDT), 2 hours ahead of UTC, springing forward on March's fourth
 152               Thursday at 26:00 (i.e., 02:00 on the first Friday on or after
 153               March 23), and falling back on October's last Sunday at 02:00.
 154
 155        WART4WARST,J1/0,J365/25
 156               stands for Western Argentina Summer Time (WARST), 3 hours behind
 157               UTC.  There is a dummy fall-back transition on December 31 at
 158               25:00 daylight saving time (i.e., 24:00 standard time,
 159               equivalent to January 1 at 00:00 standard time), and a
 160               simultaneous spring-forward transition on January 1 at 00:00
 161               standard time, so daylight saving time is in effect all year and
 162               the initial WART is a placeholder.
 163
 164        WGT3WGST,M3.5.0/-2,M10.5.0/-1
 165               stands for Western Greenland Time (WGT) and Western Greenland
 166               Summer Time (WGST), 3 hours behind UTC, where clocks follow the
 167               EU rules of springing forward on March's last Sunday at 01:00
 168               UTC (-02:00 local time) and falling back on October's last
 169               Sunday at 01:00 UTC (-01:00 local time).
 170
 171        If no rule is present in TZ, the rules specified by the
 172        tzfile(5)-format file posixrules in the system time conversion
 173        information directory are used, with the standard and summer time
 174        offsets from UTC replaced by those specified by the offset values in
 175        TZ.
 176
 177        For compatibility with System V Release 3.1, a semicolon (;) may be
 178        used to separate the rule from the rest of the specification.
 179
 180 FILES
 181        /usr/local/etc/zoneinfo             time zone information directory
 182        /usr/local/etc/zoneinfo/localtime   local time zone file
 183        /usr/local/etc/zoneinfo/posixrules  used with POSIX-style TZ's
 184        /usr/local/etc/zoneinfo/GMT         for UTC leap seconds
 185
 186        If /usr/local/etc/zoneinfo/GMT is absent, UTC leap seconds are loaded
 187        from /usr/local/etc/zoneinfo/posixrules.
 188
 189 SEE ALSO
 190        getenv(3), newctime(3), newstrftime(3), time(2), tzfile(5)
 191
 192                                                                    NEWTZSET(3)