From 13980693084c36e0275828d8d46d9d9e8975be0d Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Wed, 27 Jun 2018 11:24:09 -0700 Subject: [PROPOSED 1/3] =?UTF-8?q?Use=20=E2=80=9Ctimezone=E2=80=9C=20for?= =?UTF-8?q?=20timestamp=20histories?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The POSIX standard uses the spelling “timezone”, and often uses it to mean a TZ setting that determines the past and predicted future of UT offsets, time zone abbreviations, and tm_isdst flags. In contrast, in popular usage by far the most common spelling is “time zone”, and it typically means a maximal geographic region of clocks that currently have the same standard time. As these two quite-different meanings are often confused, attempt to disambiguate things a bit by consistently using “timezone” for the former meaning and “time zone” for the latter. This affects documentation and a few diagnostic messages. --- Makefile | 22 +++++++------- NEWS | 22 ++++++++------ backward | 2 +- date.1 | 4 +-- etcetera | 2 +- factory | 4 +-- localtime.c | 25 ++++++++-------- newctime.3 | 8 ++--- newstrftime.3 | 5 ++-- newtzset.3 | 16 +++++----- strftime.c | 3 +- theory.html | 93 ++++++++++++++++++++++++++++++++++------------------------ tz-how-to.html | 2 +- tz-link.html | 24 +++++++-------- tzfile.5 | 18 ++++++------ tzselect.8 | 12 ++++---- tzselect.ksh | 18 +++++------- zdump.8 | 16 +++++----- zdump.c | 2 +- zic.8 | 38 +++++++++++++----------- zone.tab | 12 ++++---- zone1970.tab | 28 +++++++++--------- 22 files changed, 200 insertions(+), 176 deletions(-) diff --git a/Makefile b/Makefile index 29058e5..9e3b8f9 100644 --- a/Makefile +++ b/Makefile @@ -19,9 +19,9 @@ BUGEMAIL= tz@iana.org # DATAFORM= rearguard DATAFORM= main -# Change the line below for your time zone (after finding the zone you want in -# the time zone files, or adding it to a time zone file). -# Alternatively, if you discover you've got the wrong time zone, you can just +# Change the line below for your timezone (after finding the one you want in +# one of the $(TDATA) source files, or adding it to a source file). +# Alternatively, if you discover you've got the wrong timezone, you can just # zic -l rightzone # to correct things. # Use the command @@ -31,14 +31,14 @@ DATAFORM= main LOCALTIME= GMT # If you want something other than Eastern United States time as a template -# for handling POSIX-style time zone environment variables, -# change the line below (after finding the zone you want in the -# time zone files, or adding it to a time zone file). +# for handling POSIX-style timezone environment variables, +# change the line below (after finding the timezone you want in the +# one of the $(TDATA) source files, or adding it to a source file). # When a POSIX-style environment variable is handled, the rules in the # template file are used to determine "spring forward" and "fall back" days and # times; the environment variable itself specifies UT offsets of standard and # daylight saving time. -# Alternatively, if you discover you've got the wrong time zone, you can just +# Alternatively, if you discover you've got the wrong timezone, you can just # zic -p rightzone # to correct things. # Use the command @@ -75,7 +75,7 @@ DESTDIR = # TOPDIR should be empty or an absolute name unless you're just testing. TOPDIR = -# The default local time zone is taken from the file TZDEFAULT. +# The default local timezone is taken from the file TZDEFAULT. TZDEFAULT = $(TOPDIR)/etc/localtime # The subdirectory containing installed program and data files, and @@ -84,7 +84,7 @@ TZDEFAULT = $(TOPDIR)/etc/localtime USRDIR = usr USRSHAREDIR = $(USRDIR)/share -# "Compiled" time zone information is placed in the "TZDIR" directory +# "Compiled" timezone information is placed in the "TZDIR" directory # (and subdirectories). # TZDIR_BASENAME should not contain "/" and should not be ".", ".." or empty. TZDIR_BASENAME= zoneinfo @@ -298,7 +298,7 @@ GCC_DEBUG_FLAGS = -DGCC_LINT -g3 -O3 -fno-common \ # "tzsetwall", "offtime", "timelocal", "timegm", "timeoff", # "posix2time", and "time2posix" to be added to the time conversion library. # "tzsetwall" is like "tzset" except that it arranges for local wall clock -# time (rather than the time specified in the TZ environment variable) +# time (rather than the timezone specified in the TZ environment variable) # to be used. # "offtime" is like "gmtime" except that it accepts a second (long) argument # that gives an offset to add to the time_t when converting it. @@ -321,7 +321,7 @@ GCC_DEBUG_FLAGS = -DGCC_LINT -g3 -O3 -fno-common \ # "posix2time_z" and "time2posix_z" are added as well. # The functions ending in "_z" (or "_rz") are like their unsuffixed # (or suffixed-by-"_r") counterparts, except with an extra first -# argument of opaque type timezone_t that specifies the time zone. +# argument of opaque type timezone_t that specifies the timezone. # "tzalloc" allocates a timezone_t value, and "tzfree" frees it. # # If you want to allocate state structures in localtime, add diff --git a/NEWS b/NEWS index 5296542..4ebb5f7 100644 --- a/NEWS +++ b/NEWS @@ -64,6 +64,10 @@ Unreleased, experimental changes tzfile.5 now documents what time types apply before the first and after the last transition, if any. + Documentation now uses the spelling "timezone" for a TZ setting + that determines timestamp history, and "time zone" for a + geographic region currently sharing the same standard time. + The name "TZif" is now used for the tz binary data format. tz-link.htm now mentions the A0 TimeZone Migration utilities. @@ -607,7 +611,7 @@ Release 2017b - 2017-03-17 07:30:38 -0700 The reference localtime implementation now falls back on the current US daylight-saving transition rules rather than the 1987-2006 rules. This fallback occurs only when (1) the TZ - environment variable's value has a name like "AST4ADT" that asks + environment variable has a value like "AST4ADT" that asks for daylight saving time but does not specify the rules, (2) there is no file by that name, and (3) the TZDEFRULES file cannot be loaded. (Thanks to Tom Lane.) @@ -1762,7 +1766,7 @@ Release 2014g - 2014-08-28 12:31:23 -0700 Unless NETBSD_INSPIRED is defined to 0, the tz library now supplies functions for creating and using objects that represent - time zones. The new functions are tzalloc, tzfree, localtime_rz, + timezones. The new functions are tzalloc, tzfree, localtime_rz, mktime_z, and (if STD_INSPIRED is also defined) posix2time_z and time2posix_z. They are intended for performance: for example, localtime_rz (unlike localtime_r) is trivially thread-safe without @@ -1776,7 +1780,7 @@ Release 2014g - 2014-08-28 12:31:23 -0700 TZDOBJS=zdump.o CHECK_TIME_T_ALTERNATIVES='. zdump now uses localtime_rz if available, as it's significantly faster, - and it can help zdump better diagnose invalid time zone names. + and it can help zdump better diagnose invalid timezone names. Define HAVE_LOCALTIME_RZ to 0 to suppress this. HAVE_LOCALTIME_RZ defaults to 1 if NETBSD_INSPIRED && USE_LTZ. When localtime_rz is not available, zdump now uses localtime_r and tzset if available, @@ -1792,7 +1796,7 @@ Release 2014g - 2014-08-28 12:31:23 -0700 invalid or outlandish input. The tz library no longer mishandles leap seconds on platforms with - unsigned time_t in time zones that lack ordinary transitions after 1970. + unsigned time_t in timezones that lack ordinary transitions after 1970. The tz code now attempts to infer TM_GMTOFF and TM_ZONE if not already defined, to make it easier to configure on common platforms. @@ -3570,7 +3574,7 @@ Release 2005j - 2005-06-13 14:34:13 -0400 These reflect changes to limit the length of time zone abbreviations and the characters used in those abbreviations. - There are also changes to handle POSIX-style "quoted" time zone + There are also changes to handle POSIX-style "quoted" timezone environment variables. The changes were circulated on the time zone mailing list; the only @@ -3896,7 +3900,7 @@ Release 1999f - 1999-09-23 09:48:14 -0400 Release 1999e - 1999-08-17 15:20:54 -0400 changes circulated by Paul Eggert, although the change to handling - of DST-specifying time zone names has been commented out for now + of DST-specifying timezone names has been commented out for now (search for "XXX" in "localtime.c" for details). These files also do not make any changes to the start of DST in Brazil. @@ -4021,7 +4025,7 @@ Release code1997i-data1997k - 1997-12-29 09:53:41 -0500 Release code1997h-data1997j - 1997-12-18 17:47:35 -0500 - minor changes to put "TZif" at the start of each time zone information file + minor changes to put "TZif" at the start of each timezone information file a rule has also been added to the Makefile so you can make zones @@ -4531,8 +4535,8 @@ consisting of a single tarball tzdb-R.tar.lz with extra data. Release timestamps are taken from the release's commit (for newer, Git-based releases), from the newest file in the tarball (for older releases, where this info is available) or from the email announcing -the release (if all else fails; these are marked with a time zone of --0000 and an "is missing!" comment). +the release (if all else fails; these are marked with a time zone +abbreviation of -0000 and an "is missing!" comment). Earlier versions of the code and data were not announced on the tz list and are not summarized here. diff --git a/backward b/backward index 2141f0d..a455044 100644 --- a/backward +++ b/backward @@ -1,7 +1,7 @@ # This file is in the public domain, so clarified as of # 2009-05-17 by Arthur David Olson. -# This file provides links between current names for time zones +# This file provides links between current names for timezones # and their old names. Many names changed in late 1993. # Link TARGET LINK-NAME diff --git a/date.1 b/date.1 index 28dc1d7..6e79cc1 100644 --- a/date.1 +++ b/date.1 @@ -146,11 +146,11 @@ should be an integer, either decimal, octal (leading 0), or hexadecimal (leading 0x), preceded by an optional sign. .SH FILES .ta \w'/usr/share/zoneinfo/posixrules\0\0'u -/etc/localtime local time zone file +/etc/localtime local timezone file .br /usr/lib/locale/\f2L\fP/LC_TIME description of time locale \f2L\fP .br -/usr/share/zoneinfo time zone information directory +/usr/share/zoneinfo timezone information directory .br /usr/share/zoneinfo/posixrules used with POSIX-style TZ's .br diff --git a/etcetera b/etcetera index f5fa4c9..1a59630 100644 --- a/etcetera +++ b/etcetera @@ -3,7 +3,7 @@ # These entries are mostly present for historical reasons, so that # people in areas not otherwise covered by the tz files could "zic -l" -# to a time zone that was right for their area. These days, the +# to a timezone that was right for their area. These days, the # tz files cover almost all the inhabited world, and the only practical # need now for the entries that are not on UTC are for ships at sea # that cannot use POSIX TZ settings. diff --git a/factory b/factory index 75fa4a1..5f0573d 100644 --- a/factory +++ b/factory @@ -1,8 +1,8 @@ # This file is in the public domain, so clarified as of # 2009-05-17 by Arthur David Olson. -# For distributors who don't want to put time zone specification in -# their installation procedures. Users that run 'date' will get the +# For distributors who don't want to specify a timezone in their +# installation procedures. Users who run 'date' will get the # time zone abbreviation "-00", indicating that the actual time zone # is unknown. diff --git a/localtime.c b/localtime.c index f205363..b217865 100644 --- a/localtime.c +++ b/localtime.c @@ -300,7 +300,7 @@ settzname(void) return; } /* - ** And to get the latest zone names into tzname. . . + ** And to get the latest time zone abbreviations into tzname. . . */ for (i = 0; i < sp->typecnt; ++i) { register const struct ttinfo * const ttisp = &sp->ttis[i]; @@ -774,9 +774,9 @@ static const int year_lengths[2] = { }; /* -** Given a pointer into a time zone string, scan until a character that is not -** a valid character in a zone name is found. Return a pointer to that -** character. +** Given a pointer into a timezone string, scan until a character that is not +** a valid character in a time zone abbreviation is found. +** Return a pointer to that character. */ static const char * @@ -791,8 +791,9 @@ getzname(register const char *strp) } /* -** Given a pointer into an extended time zone string, scan until the ending -** delimiter of the zone name is located. Return a pointer to the delimiter. +** Given a pointer into an extended timezone string, scan until the ending +** delimiter of the time zone abbreviation is located. +** Return a pointer to the delimiter. ** ** As with getzname above, the legal character set is actually quite ** restricted, with other characters producing undefined results. @@ -810,7 +811,7 @@ getqzname(register const char *strp, const int delim) } /* -** Given a pointer into a time zone string, extract a number from that string. +** Given a pointer into a timezone string, extract a number from that string. ** Check that the number is within a specified range; if it is not, return ** NULL. ** Otherwise, return a pointer to the first character not part of the number. @@ -838,7 +839,7 @@ getnum(register const char *strp, int *const nump, const int min, const int max) } /* -** Given a pointer into a time zone string, extract a number of seconds, +** Given a pointer into a timezone string, extract a number of seconds, ** in hh[:mm[:ss]] form, from the string. ** If any error occurs, return NULL. ** Otherwise, return a pointer to the first character not part of the number @@ -879,7 +880,7 @@ getsecs(register const char *strp, int_fast32_t *const secsp) } /* -** Given a pointer into a time zone string, extract an offset, in +** Given a pointer into a timezone string, extract an offset, in ** [+-]hh[:mm[:ss]] form, from the string. ** If any error occurs, return NULL. ** Otherwise, return a pointer to the first character not part of the time. @@ -904,7 +905,7 @@ getoffset(register const char *strp, int_fast32_t *const offsetp) } /* -** Given a pointer into a time zone string, extract a rule in the form +** Given a pointer into a timezone string, extract a rule in the form ** date[/time]. See POSIX section 8 for the format of "date" and "time". ** If a valid rule is not found, return NULL. ** Otherwise, return a pointer to the first character not part of the rule. @@ -1106,7 +1107,7 @@ tzparse(const char *name, struct state *sp, bool lastditch) } else { dstname = name; name = getzname(name); - dstlen = name - dstname; /* length of DST zone name */ + dstlen = name - dstname; /* length of DST abbr. */ } if (!dstlen) return false; @@ -1450,7 +1451,7 @@ tzfree(timezone_t sp) ** ** If successful and SETNAME is nonzero, ** set the applicable parts of tzname, timezone and altzone; -** however, it's OK to omit this step if the time zone is POSIX-compatible, +** however, it's OK to omit this step if the timezone is POSIX-compatible, ** since in that case tzset should have already done this step correctly. ** SETNAME's type is intfast32_t for compatibility with gmtsub, ** but it is actually a boolean and its value should be 0 or 1. diff --git a/newctime.3 b/newctime.3 index d4645ad..565e89a 100644 --- a/newctime.3 +++ b/newctime.3 @@ -187,7 +187,7 @@ and are like their unsuffixed counterparts, except that they accept an extra initial .B zone -argument specifying the time zone to be used for conversion. +argument specifying the timezone to be used for conversion. If .B zone is null, UT is used; otherwise, @@ -252,9 +252,9 @@ There is no guarantee that these fields and this variable will continue to exist in this form in future releases of this code. .SH FILES .ta \w'/usr/share/zoneinfo/posixrules\0\0'u -/usr/share/zoneinfo time zone information directory +/usr/share/zoneinfo timezone information directory .br -/usr/share/zoneinfo/localtime local time zone file +/usr/share/zoneinfo/localtime local timezone file .br /usr/share/zoneinfo/posixrules used with POSIX-style TZ's .br @@ -292,7 +292,7 @@ can be freed or overwritten by later calls to the functions .IR tzfree , and .IR tzset , -if these functions affect the time zone information that specifies the +if these functions affect the timezone information that specifies the abbreviation in question. The remaining functions and data are thread-safe. .PP diff --git a/newstrftime.3 b/newstrftime.3 index f1a1a6d..1fd80df 100644 --- a/newstrftime.3 +++ b/newstrftime.3 @@ -210,7 +210,7 @@ is replaced by the year with century as a decimal number. is replaced by the year without century as a decimal number (00\*(en99). .TP %Z -is replaced by the time zone name, +is replaced by the time zone abbreviation, or by the empty string if this is not determinable. .TP %z @@ -218,7 +218,8 @@ is replaced by the offset from the Prime Meridian in the format +HHMM or \*-HHMM as appropriate, with positive values representing locations east of Greenwich, or by the empty string if this is not determinable. -The numeric time zone \*-0000 is used when the time is Universal Time +The numeric time zone abbreviation \*-0000 is used when the time is +Universal Time but local time is indeterminate; by convention this is used for locations while uninhabited, and corresponds to a zero offset when the time zone abbreviation begins with diff --git a/newtzset.3 b/newtzset.3 index 0eab732..29e8a21 100644 --- a/newtzset.3 +++ b/newtzset.3 @@ -26,17 +26,17 @@ tzset \- initialize time conversion information \\$3\*(lq\\$1\*(rq\\$2 .. .I Tzalloc -allocates and returns a time zone object described by +allocates and returns a timezone object described by .BR TZ . If .B TZ -is not a valid time zone description, or if the object cannot be allocated, +is not a valid timezone description, or if the object cannot be allocated, .I tzalloc returns a null pointer and sets .BR errno . .PP .I Tzfree -frees a time zone object +frees a timezone object .BR tz , which should have been successfully allocated by .IR tzalloc . @@ -49,13 +49,13 @@ was used to set. .I Tzset acts like .BR tzalloc(getenv("TZ")) , -except it saves any resulting time zone object into internal +except it saves any resulting timezone object into internal storage that is accessed by .IR localtime , .IR localtime_r , and .IR mktime . -The anonymous shared time zone object is freed by the next call to +The anonymous shared timezone object is freed by the next call to .IR tzset . If the implied call to .B tzalloc @@ -252,7 +252,7 @@ is not given, is .LP Here are some examples of .B TZ -values that directly specify the time zone rules; they use some of the +values that directly specify the timezone; they use some of the extensions to POSIX. .TP .B EST5 @@ -321,9 +321,9 @@ may be used to separate the from the rest of the specification. .SH FILES .ta \w'/usr/share/zoneinfo/posixrules\0\0'u -/usr/share/zoneinfo time zone information directory +/usr/share/zoneinfo timezone information directory .br -/usr/share/zoneinfo/localtime local time zone file +/usr/share/zoneinfo/localtime local timezone file .br /usr/share/zoneinfo/posixrules used with POSIX-style TZ's .br diff --git a/strftime.c b/strftime.c index e855890..ac26f4b 100644 --- a/strftime.c +++ b/strftime.c @@ -487,7 +487,8 @@ label: /* ** C99 and later say that %Z must be ** replaced by the empty string if the - ** time zone is not determinable. + ** time zone abbreviation is not + ** determinable. */ continue; case 'z': diff --git a/theory.html b/theory.html index 7ff6fc4..3939946 100644 --- a/theory.html +++ b/theory.html @@ -15,7 +15,7 @@