xref: /third_party/tzdata/newtzset.3.txt

newtzset(3)                Library Functions Manual                newtzset(3)

NAME
       tzset - initialize time conversion information

SYNOPSIS
       #include <time.h>

       timezone_t tzalloc(char const *TZ);

       void tzfree(timezone_t tz);

       void tzset(void);

       cc ... -ltz

DESCRIPTION
       The tzalloc function allocates and returns a timezone object described
       by TZ.

       If TZ is a null pointer, tzalloc uses the best available approximation
       to local (wall clock) time, as specified by the tzfile(5)-format file
       localtime in the system time conversion information directory.

       If TZ is the empty string, tzalloc uses Universal Time (UT), with the
       abbreviation "UTC" and without leap second correction; please see
       newctime(3) for more about UT, UTC, and leap seconds.

       If TZ is nonnull and nonempty:

              if the value begins with a colon, it is used as a pathname of a
              file from which to read the time conversion information;

              if the value does not begin with a colon, it is first used as
              the pathname of a file from which to read the time conversion
              information, and, if that file cannot be read, is used directly
              as a specification of the time conversion information.

       When TZ contents are used as a pathname, a pathname beginning with "/"
       is used as-is; otherwise the pathname is relative to a system time
       conversion information directory.  The file must be in the format
       specified in tzfile(5).

       When TZ is used directly as a specification of the time conversion
       information, it must have the following syntax:

              stdoffset[dst[offset][,rule]]

       Where:

              std and dst
                     Three  or  more  bytes  that  are the designation for the
                     standard (std) or the alternative (dst, such as  daylight
                     saving  time) time zone.  Only std is required; if dst is
                     missing, then daylight saving time does not apply in this
                     locale.  Upper-  and  lowercase  letters  are  explicitly
                     allowed.   Any  characters  except  a  leading colon (:),
                     digits, comma (,), ASCII minus (-), ASCII plus  (+),  and
                     NUL  bytes are allowed.  Alternatively, a designation can
                     be surrounded by angle brackets < and >;  in  this  case,
                     the  designation  can contain any characters other than >
                     and NUL.

              offset Indicates the value one must add to  the  local  time  to
                     arrive at Coordinated Universal Time.  The offset has the
                     form:

                            hh[:mm[:ss]]

                     The minutes (mm) and seconds (ss) are optional.  The hour
                     (hh)  is  required and may be a single digit.  The offset
                     following std is required.  If  no  offset  follows  dst,
                     daylight  saving  time is assumed to be one hour ahead of
                     standard time.  One or more digits may be used; the value
                     is always interpreted as a decimal number.  The hour must
                     be between zero and 24, and the minutes (and  seconds)  -
                     if  present - between zero and 59.  If preceded by a "-",
                     the time zone  shall  be  east  of  the  Prime  Meridian;
                     otherwise  it shall be west (which may be indicated by an
                     optional preceding "+".

              rule   Indicates when to change to and back from daylight saving
                     time.  The rule has the form:

                            date/time,date/time

                     where the first  date  describes  when  the  change  from
                     standard  to  daylight  saving time occurs and the second
                     date describes when the change back happens.   Each  time
                     field  describes  when, in current local time, the change
                     to  the  other  time  is  made.   As  an   extension   to
                     POSIX.1-2017,  daylight saving is assumed to be in effect
                     all year if  it  begins  January  1  at  00:00  and  ends
                     December 31 at 24:00 plus the difference between daylight
                     saving  and  standard  time, leaving no room for standard
                     time in the calendar.

                     The format of date is one of the following:

                     Jn     The Julian day n (1 <= n <= 365).  Leap  days  are
                            not  counted;  that  is,  in all years - including
                            leap years - February 28 is day 59 and March 1  is
                            day  60.   It is impossible to explicitly refer to
                            the occasional February 29.

                     n      The zero-based Julian day  (0 <= n <= 365).   Leap
                            days  are  counted, and it is possible to refer to
                            February 29.

                     Mm.n.d The d'th day (0 <= d <= 6) of week n of month m of
                            the year (1 <= n <= 5, 1 <= m <= 12, where week  5
                            means  "the last d day in month m" which may occur
                            in either the fourth or the fifth week).   Week  1
                            is  the  first  week in which the d'th day occurs.
                            Day zero is Sunday.

                     The time has  the  same  format  as  offset  except  that
                     POSIX.1-2017  does not allow a leading sign ("-" or "+").
                     As an extension to POSIX.1-2017, the hours part  of  time
                     can  range from -167 through 167; this allows for unusual
                     rules such as "the Saturday before the  first  Sunday  of
                     March".  The default, if time is not given, is 02:00:00.

       Here are some examples of TZ values that directly specify the timezone;
       they use some of the extensions to POSIX.1-2017.

       EST5   stands  for  US  Eastern Standard Time (EST), 5 hours behind UT,
              without daylight saving.

       <+12>-12<+13>,M11.1.0,M1.2.1/147
              stands for Fiji time, 12 hours ahead of UT, springing forward on
              November's first Sunday at 02:00, and falling back on  January's
              second  Monday  at 147:00 (i.e., 03:00 on the first Sunday on or
              after January 14).  The abbreviations for standard and  daylight
              saving time are "+12" and "+13".

       IST-2IDT,M3.4.4/26,M10.5.0
              stands  for  Israel Standard Time (IST) and Israel Daylight Time
              (IDT), 2 hours ahead of UT, springing forward on March's  fourth
              Thursday  at  26:00 (i.e., 02:00 on the first Friday on or after
              March 23), and falling back on October's last Sunday at 02:00.

       <-04>4<-03>,J1/0,J365/25
              stands for permanent daylight saving time,  3  hours  behind  UT
              with  abbreviation "-03".  There is a dummy fall-back transition
              on December 31  at  25:00  daylight  saving  time  (i.e.,  24:00
              standard  time, equivalent to January 1 at 00:00 standard time),
              and a simultaneous spring-forward transition  on  January  1  at
              00:00  standard  time,  so daylight saving time is in effect all
              year and the initial <-04> is a placeholder.

       <-03>3<-02>,M3.5.0/-2,M10.5.0/-1
              stands for time in western Greenland, 3 hours behind  UT,  where
              clocks  follow the EU rules of springing forward on March's last
              Sunday at 01:00 UT (-02:00 local time, i.e., 22:00 the  previous
              day)  and  falling  back  on  October's  last Sunday at 01:00 UT
              (-01:00  local  time,  i.e.,  23:00  the  previous  day).    The
              abbreviations  for  standard  and daylight saving time are "-03"
              and "-02".

       If TZ specifies daylight saving time but does not specify a  rule,  and
       the  optional tzfile(5)-format file posixrules is present in the system
       time conversion information directory,  the  rules  in  posixrules  are
       used,  with  the  posixrules  standard and daylight saving time offsets
       from UT replaced by  those  specified  by  the  offset  values  in  TZ.
       However,  the  posixrules file is obsolete: if it is present it is only
       for backward compatibility, and it does not work reliably.   Therefore,
       if a TZ string directly specifies a timezone with daylight saving time,
       it should specify the daylight saving rules explicitly.

       For  compatibility  with  System  V Release 3.1, a semicolon (;) may be
       used to separate the rule from the rest of the specification;  this  is
       an extension to POSIX.

       The  tzfree function frees a timezone object tz, which should have been
       successfully  allocated  by  tzalloc.   This  invalidates  any  tm_zone
       pointers that tz was used to set.

       The tzset function acts like tzalloc(getenv("TZ")), except it saves any
       resulting  timezone  object  into  internal storage that is accessed by
       localtime, localtime_r, and  mktime.   The  anonymous  shared  timezone
       object  is  freed  by  the  next call to tzset.  If the implied call to
       getenv fails, tzset acts like tzalloc(nullptr); if the implied call  to
       tzalloc fails, tzset falls back on UT.

RETURN VALUE
       If  successful,  the  tzalloc function returns a nonnull pointer to the
       newly allocated object.  Otherwise, it returns a null pointer and  sets
       errno.

ERRORS
       EOVERFLOW
              TZ  directly specifies time conversion information, and contains
              an integer out of machine range or a time zone abbreviation that
              is too long for this platform.

       The tzalloc function may also fail and set errno for any of the  errors
       specified for the routines access(2), close(2), malloc(3), open(2), and
       read(2).

FILES
       /etc/localtime                  local timezone file
       /usr/share/zoneinfo             timezone directory
       /usr/share/zoneinfo/posixrules  default DST rules (obsolete)
       /usr/share/zoneinfo/GMT         for UTC leap seconds

       If  /usr/share/zoneinfo/GMT is absent, UTC leap seconds are loaded from
       /usr/share/zoneinfo/GMT0 if present.

SEE ALSO
       getenv(3), newctime(3), newstrftime(3), time(2), tzfile(5)

Time Zone Database                                                 newtzset(3)