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