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. If TZ is not a valid timezone description, or if the object 20 cannot be allocated, tzalloc returns a null pointer and sets errno. 21 22 The tzfree function frees a timezone object tz, which should have been 23 successfully allocated by tzalloc. This invalidates any tm_zone 24 pointers that tz was used to set. 25 26 The tzset function acts like tzalloc(getenv("TZ")), except it saves any 27 resulting timezone object into internal storage that is accessed by 28 localtime, localtime_r, and mktime. The anonymous shared timezone 29 object is freed by the next call to tzset. If the implied call to 30 tzalloc fails, tzset falls back on Universal Time (UT). 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, UT is used, with the abbreviation "UTC" and without leap second 36 correction; please see newctime(3) for more about UT, UTC, and leap 37 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 the alternative (dst, such 62 as daylight saving time) time zone. Only std is 63 required; if dst is missing, then daylight saving 64 time does not apply in this locale. Upper- and 65 lowercase letters are explicitly allowed. Any 66 characters except a leading colon (:), digits, 67 comma (,), ASCII minus (-), ASCII plus (+), and 68 NUL bytes are allowed. Alternatively, a 69 designation can be surrounded by angle brackets < 70 and >; in this case, the designation can contain 71 any characters other than > 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, daylight saving time is 83 assumed to be one hour ahead of standard time. 84 One or more digits may be used; the value is 85 always interpreted as a decimal number. The hour 86 must 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 94 daylight saving 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 daylight saving time occurs and 100 the 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 timezone; 142 they use some of the extensions to POSIX. 143 144 EST5 stands for US Eastern Standard Time (EST), 5 hours behind UT, 145 without daylight saving. 146 147 <+12>-12<+13>,M11.1.0,M1.2.1/147 148 stands for Fiji time, 12 hours ahead of UT, springing forward on 149 November's first Sunday at 02:00, and falling back on January's 150 second Monday at 147:00 (i.e., 03:00 on the first Sunday on or 151 after January 14). The abbreviations for standard and daylight 152 saving time are "+12" and "+13". 153 154 IST-2IDT,M3.4.4/26,M10.5.0 155 stands for Israel Standard Time (IST) and Israel Daylight Time 156 (IDT), 2 hours ahead of UT, springing forward on March's fourth 157 Thursday at 26:00 (i.e., 02:00 on the first Friday on or after 158 March 23), and falling back on October's last Sunday at 02:00. 159 160 <-04>4<-03>,J1/0,J365/25 161 stands for permanent daylight saving time, 3 hours behind UT 162 with abbreviation "-03". There is a dummy fall-back transition 163 on December 31 at 25:00 daylight saving time (i.e., 24:00 164 standard time, equivalent to January 1 at 00:00 standard time), 165 and a simultaneous spring-forward transition on January 1 at 166 00:00 standard time, so daylight saving time is in effect all 167 year and the initial <-04> is a placeholder. 168 169 <-03>3<-02>,M3.5.0/-2,M10.5.0/-1 170 stands for time in western Greenland, 3 hours behind UT, where 171 clocks follow the EU rules of springing forward on March's last 172 Sunday at 01:00 UT (-02:00 local time, i.e., 22:00 the previous 173 day) and falling back on October's last Sunday at 01:00 UT 174 (-01:00 local time, i.e., 23:00 the previous day). The 175 abbreviations for standard and daylight saving time are "-03" 176 and "-02". 177 178 If no rule is present in TZ, the rules specified by the 179 tzfile(5)-format file posixrules in the system time conversion 180 information directory are used, with the standard and daylight saving 181 time offsets from UT replaced by those specified by the offset values 182 in TZ. 183 184 For compatibility with System V Release 3.1, a semicolon (;) may be 185 used to separate the rule from the rest of the specification. 186 187FILES 188 /usr/share/zoneinfo timezone information directory 189 /usr/share/zoneinfo/localtime local timezone file 190 /usr/share/zoneinfo/posixrules used with POSIX-style TZ's 191 /usr/share/zoneinfo/GMT for UTC leap seconds 192 193 If /usr/share/zoneinfo/GMT is absent, UTC leap seconds are loaded from 194 /usr/share/zoneinfo/posixrules. 195 196SEE ALSO 197 getenv(3), newctime(3), newstrftime(3), time(2), tzfile(5) 198 199 NEWTZSET(3) 200