--- name: "newtzset" section: "3" platform: "linux" package: "tzdata" version: "2026e-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/newtzset" --- # newtzset(3) initialize time conversion information ## NAME tzset - initialize time conversion information ## SYNOPSIS ``` #include ``` **timezone\_t tzalloc(char const \****TZ***);** **void tzfree(timezone\_t** *tz***);** **void tzset(void);** /\* Optional and obsolescent: \*/\ **extern char \*tzname\[\];**\ **extern long timezone;**\ **extern int daylight;** **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)](/tzfile/5.md)-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)](/newctime/3.md) 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. In a privileged program the pathname must be relative. Relative pathnames must not contain “..” components. For the purpose of these checks, a file name beginning with “/” is considered to be relative if it is the **localtime** file's name, or if it starts with the system timezone directory's name followed by one more more slashes. The file must be a regular file in the format specified in [**tzfile**(5)](/tzfile/5.md). 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. 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: - **J***n* 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. - **M***m***.***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 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. - **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 rule 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*, the rule typically defaults to the current US daylight-saving rule, although such a default is not guaranteed and is incorrect for many locations outside the US. Therefore, if a *TZ* string directly specifies a timezone with daylight saving time, it should specify the daylight saving rule 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. As a side effect, the **tzset** function sets some external variables if the platform defines them. It sets **tzname**\[0\] and **tzname**\[1\] to pointers to strings that are time zone abbreviations to be used with standard and daylight saving time, respectively. It also sets **timezone** to be the number of seconds that standard time is west of the Prime Meridian, and **daylight** to be zero if daylight saving time is never in effect, non-zero otherwise. ## 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*. The **tzfree** function does not modify *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)](/access/2.md), [**close**(2)](/close/2.md), [**malloc**(3)](/malloc/3.md), [**open**(2)](/open/2.md), and [**read**(2)](/read/2.md). ## FILES /etc/localtime local timezone file\ /usr/share/zoneinfo timezone directory\ /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)](/getenv/3.md), [**newctime**(3)](/newctime/3.md), **newstrftime**(3), [**time**(2)](/time/2.md), [**tzfile**(5)](/tzfile/5.md). ## NOTES Portable code should not rely on the contents of the external variables **tzname**, **timezone** and **daylight** as their contents are unspecified (and do not make sense in general) when a geographical TZ is used. In multithreaded applications behavior is undefined if one thread accesses one of these variables while another thread invokes **tzset**. A future version of POSIX is planned to remove these variables; callers can instead use the *tm\_gmtoff* and *tm\_zone* members of **struct tm**, or use **strftime** with "%z" or "%Z".