diff options
| author | Philip Paeps <philip@FreeBSD.org> | 2022-08-16 08:09:47 +0000 |
|---|---|---|
| committer | Philip Paeps <philip@FreeBSD.org> | 2022-08-16 08:09:47 +0000 |
| commit | a24d752d3e77a28c877a5319face8d00aa1b558c (patch) | |
| tree | 5ae147d3bedd850833ec5c783ea54fa4b00e6aba /newtzset.3.txt | |
| parent | 9b5369d383baf54651be0922591eeb6263ce029d (diff) | |
Import tzcode 2022cvendor/tzcode/tzcode2022c
Diffstat (limited to 'newtzset.3.txt')
| -rw-r--r-- | newtzset.3.txt | 290 |
1 files changed, 168 insertions, 122 deletions
diff --git a/newtzset.3.txt b/newtzset.3.txt index 9d7d02233ee0..171e8291f8ce 100644 --- a/newtzset.3.txt +++ b/newtzset.3.txt @@ -1,153 +1,199 @@ -NAME +NEWTZSET(3) Library Functions Manual NEWTZSET(3) - tzset - initialize time conversion information +NAME + tzset - initialize time conversion information SYNOPSIS - void tzset() + #include <time.h> + + timezone_t tzalloc(char const *TZ); + + void tzfree(timezone_t tz); - cc ... -ltz + void tzset(void); + + cc ... -ltz DESCRIPTION - Tzset uses the value of the environment variable TZ to set - time conversion information used by localtime. If TZ does - not appear in the environment, 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, is used by localtime. If - TZ appears in the environment but its value is a null - string, Coordinated Universal Time (UTC) is used (without - leap second correction). If TZ appears in the environment - and its value is not a null string: + The tzalloc function allocates and returns a timezone object described + by TZ. If TZ is not a valid timezone description, or if the object + cannot be allocated, tzalloc returns a null pointer and sets errno. + + 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 + tzalloc fails, tzset falls back on Universal Time (UT). + + If TZ is null, 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, is used. If TZ is the empty + string, UT is used, 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 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. + 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 is used as a pathname, if it begins with a slash, it - is used as an absolute pathname; otherwise, it is used as a - pathname relative to a system time conversion information - directory. The file must be in the format specified in - tzfile(5). + When TZ is used as a pathname, if it begins with a slash, it is used as + an absolute pathname; otherwise, it is used as a pathname 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 - (spaces inserted for clarity): + When TZ is used directly as a specification of the time conversion + information, it must have the following syntax (spaces inserted for + clarity): - stdoffset[dst[offset][,rule]] + stdoffset[dst[offset][,rule]] - Where: + Where: - std and dst Three or more bytes that are the - designation for the standard (std) or - summer (dst) time zone. Only std is - required; if dst is missing, then summer - time does not apply in this locale. - Upper- and lowercase letters are - explicitly allowed. Any characters - except a leading colon (:), digits, - comma (,), minus (-), plus (+), and - ASCII NUL are allowed. + 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: + 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]] + 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, summer 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 ``+''). + 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 summer time. The rule has the - form: + rule Indicates when to change to and back from + daylight saving time. The rule has the form: - date/time,date/time + date/time,date/time - where the first date describes when the - change from standard to summer 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. + 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, 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: + 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. + 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. + 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. + 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 no leading sign (``-'' or - ``+'') is allowed. The default, if time - is not given, is 02:00:00. + The time has the same format as offset except + that POSIX does not allow a leading sign ("-" or + "+"). As an extension to POSIX, 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. - If no rule is present in TZ, the rules specified by the - tzfile(5)-format file posixrules in the system time - conversion information directory are used, with the standard - and summer time offsets from UTC replaced by those specified - by the offset values in TZ. - For compatibility with System V Release 3.1, a semicolon (;) - may be used to separate the rule from the rest of the - specification. + Here are some examples of TZ values that directly specify the timezone; + they use some of the extensions to POSIX. - If the TZ environment variable does not specify a - tzfile(5)-format and cannot be interpreted as a direct - specification, UTC is used. + 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 no rule is present in TZ, the rules specified by the + tzfile(5)-format file posixrules in the system time conversion + information directory are used, with the standard and daylight saving + time offsets from UT replaced by those specified by the offset values + in TZ. + + For compatibility with System V Release 3.1, a semicolon (;) may be + used to separate the rule from the rest of the specification. FILES - /usr/local/etc/zoneinfo time zone information - directory - /usr/local/etc/zoneinfo/localtime local time zone file - /usr/local/etc/zoneinfo/posixrules used with POSIX-style - TZ's - /usr/local/etc/zoneinfo/GMT for UTC leap seconds + /usr/share/zoneinfo timezone information directory + /usr/share/zoneinfo/localtime local timezone file + /usr/share/zoneinfo/posixrules used with POSIX-style TZ's + /usr/share/zoneinfo/GMT for UTC leap seconds - If /usr/local/etc/zoneinfo/GMT is absent, UTC leap seconds - are loaded from /usr/local/etc/zoneinfo/posixrules. + If /usr/share/zoneinfo/GMT is absent, UTC leap seconds are loaded from + /usr/share/zoneinfo/posixrules. SEE ALSO - getenv(3), newctime(3), newstrftime(3), time(2), tzfile(5) + getenv(3), newctime(3), newstrftime(3), time(2), tzfile(5) + + NEWTZSET(3) |