1src/timezone/README 2 3This is a PostgreSQL adapted version of the IANA timezone library from 4 5 https://www.iana.org/time-zones 6 7The latest version of the timezone data and library source code is 8available right from that page. It's best to get the merged file 9tzdb-NNNNX.tar.lz, since the other archive formats omit tzdata.zi. 10Historical versions, as well as release announcements, can be found 11elsewhere on the site. 12 13Since time zone rules change frequently in some parts of the world, 14we should endeavor to update the data files before each PostgreSQL 15release. The code need not be updated as often, but we must track 16changes that might affect interpretation of the data files. 17 18 19Time Zone data 20============== 21 22We distribute the time zone source data as-is under src/timezone/data/. 23Currently, we distribute just the abbreviated single-file format 24"tzdata.zi", to reduce the size of our tarballs as well as churn 25in our git repo. Feeding that file to zic produces the same compiled 26output as feeding the bulkier individual data files would do. 27 28While data/tzdata.zi can just be duplicated when updating, manual effort 29is needed to update the time zone abbreviation lists under tznames/. 30These need to be changed whenever new abbreviations are invented or the 31UTC offset associated with an existing abbreviation changes. To detect 32if this has happened, after installing new files under data/ do 33 make abbrevs.txt 34which will produce a file showing all abbreviations that are in current 35use according to the data/ files. Compare this to known_abbrevs.txt, 36which is the list that existed last time the tznames/ files were updated. 37Update tznames/ as seems appropriate, then replace known_abbrevs.txt 38in the same commit. Usually, if a known abbreviation has changed meaning, 39the appropriate fix is to make it refer to a long-form zone name instead 40of a fixed GMT offset. 41 42The core regression test suite does some simple validation of the zone 43data and abbreviations data (notably by checking that the pg_timezone_names 44and pg_timezone_abbrevs views don't throw errors). It's worth running it 45as a cross-check on proposed updates. 46 47When there has been a new release of Windows (probably including Service 48Packs), the list of matching timezones need to be updated. Run the 49script in src/tools/win32tzlist.pl on a Windows machine running this new 50release and apply any new timezones that it detects. Never remove any 51mappings in case they are removed in Windows, since we still need to 52match properly on the old version. 53 54 55Time Zone code 56============== 57 58The code in this directory is currently synced with tzcode release 2020d. 59There are many cosmetic (and not so cosmetic) differences from the 60original tzcode library, but diffs in the upstream version should usually 61be propagated to our version. Here are some notes about that. 62 63For the most part we want to use the upstream code as-is, but there are 64several considerations preventing an exact match: 65 66* For readability/maintainability we reformat the code to match our own 67conventions; this includes pgindent'ing it and getting rid of upstream's 68overuse of "register" declarations. (It used to include conversion of 69old-style function declarations to C89 style, but thank goodness they 70fixed that.) 71 72* We need the code to follow Postgres' portability conventions; this 73includes relying on configure's results rather than hand-hacked 74#defines (see private.h in particular). 75 76* Similarly, avoid relying on <stdint.h> features that may not exist on old 77systems. In particular this means using Postgres' definitions of the int32 78and int64 typedefs, not int_fast32_t/int_fast64_t. Likewise we use 79PG_INT32_MIN/MAX not INT32_MIN/MAX. (Once we desupport all PG versions 80that don't require C99, it'd be practical to rely on <stdint.h> and remove 81this set of diffs; but that day is not yet.) 82 83* Since Postgres is typically built on a system that has its own copy 84of the <time.h> functions, we must avoid conflicting with those. This 85mandates renaming typedef time_t to pg_time_t, and similarly for most 86other exposed names. 87 88* zic.c's typedef "lineno" is renamed to "lineno_t", because having 89"lineno" in our typedefs list would cause unfortunate pgindent behavior 90in some other files where we have variables named that. 91 92* We have exposed the tzload() and tzparse() internal functions, and 93slightly modified the API of the former, in part because it now relies 94on our own pg_open_tzfile() rather than opening files for itself. 95 96* tzparse() is adjusted to never try to load the TZDEFRULES zone. 97 98* There's a fair amount of code we don't need and have removed, 99including all the nonstandard optional APIs. We have also added 100a few functions of our own at the bottom of localtime.c. 101 102* In zic.c, we have added support for a -P (print_abbrevs) switch, which 103is used to create the "abbrevs.txt" summary of currently-in-use zone 104abbreviations that was described above. 105 106 107The most convenient way to compare a new tzcode release to our code is 108to first run the tzcode source files through a sed filter like this: 109 110 sed -r \ 111 -e 's/^([ \t]*)\*\*([ \t])/\1 *\2/' \ 112 -e 's/^([ \t]*)\*\*$/\1 */' \ 113 -e 's|^\*/| */|' \ 114 -e 's/\bregister[ \t]//g' \ 115 -e 's/\bATTRIBUTE_PURE[ \t]//g' \ 116 -e 's/int_fast32_t/int32/g' \ 117 -e 's/int_fast64_t/int64/g' \ 118 -e 's/intmax_t/int64/g' \ 119 -e 's/INT32_MIN/PG_INT32_MIN/g' \ 120 -e 's/INT32_MAX/PG_INT32_MAX/g' \ 121 -e 's/INTMAX_MIN/PG_INT64_MIN/g' \ 122 -e 's/INTMAX_MAX/PG_INT64_MAX/g' \ 123 -e 's/struct[ \t]+tm\b/struct pg_tm/g' \ 124 -e 's/\btime_t\b/pg_time_t/g' \ 125 -e 's/lineno/lineno_t/g' \ 126 127and then run them through pgindent. (The first three sed patterns deal 128with conversion of their block comment style to something pgindent 129won't make a hash of; the remainder address other points noted above.) 130After that, the files can be diff'd directly against our corresponding 131files. Also, it's typically helpful to diff against the previous tzcode 132release (after processing that the same way), and then try to apply the 133diff to our files. This will take care of most of the changes 134mechanically. 135