diff options
Diffstat (limited to 'doc/src/sgml/html/datetime-posix-timezone-specs.html')
| -rw-r--r-- | doc/src/sgml/html/datetime-posix-timezone-specs.html | 135 |
1 files changed, 135 insertions, 0 deletions
diff --git a/doc/src/sgml/html/datetime-posix-timezone-specs.html b/doc/src/sgml/html/datetime-posix-timezone-specs.html new file mode 100644 index 0000000..1b0bcaf --- /dev/null +++ b/doc/src/sgml/html/datetime-posix-timezone-specs.html @@ -0,0 +1,135 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>B.5. POSIX Time Zone Specifications</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="datetime-config-files.html" title="B.4. Date/Time Configuration Files" /><link rel="next" href="datetime-units-history.html" title="B.6. History of Units" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">B.5. <acronym class="acronym">POSIX</acronym> Time Zone Specifications</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="datetime-config-files.html" title="B.4. Date/Time Configuration Files">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="datetime-appendix.html" title="Appendix B. Date/Time Support">Up</a></td><th width="60%" align="center">Appendix B. Date/Time Support</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="datetime-units-history.html" title="B.6. History of Units">Next</a></td></tr></table><hr /></div><div class="sect1" id="DATETIME-POSIX-TIMEZONE-SPECS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">B.5. <acronym class="acronym">POSIX</acronym> Time Zone Specifications</h2></div></div></div><a id="id-1.11.3.8.2" class="indexterm"></a><p> + <span class="productname">PostgreSQL</span> can accept time zone specifications + that are written according to the <acronym class="acronym">POSIX</acronym> standard's rules + for the <code class="varname">TZ</code> environment + variable. <acronym class="acronym">POSIX</acronym> time zone specifications are + inadequate to deal with the complexity of real-world time zone history, + but there are sometimes reasons to use them. + </p><p> + A POSIX time zone specification has the form +</p><pre class="synopsis"> +<em class="replaceable"><code>STD</code></em> <em class="replaceable"><code>offset</code></em> [<span class="optional"> <em class="replaceable"><code>DST</code></em> [<span class="optional"> <em class="replaceable"><code>dstoffset</code></em> </span>] [<span class="optional"> , <em class="replaceable"><code>rule</code></em> </span>] </span>] +</pre><p> + (For readability, we show spaces between the fields, but spaces should + not be used in practice.) The fields are: + </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + <em class="replaceable"><code>STD</code></em> is the zone abbreviation to be used + for standard time. + </p></li><li class="listitem"><p> + <em class="replaceable"><code>offset</code></em> is the zone's standard-time offset + from UTC. + </p></li><li class="listitem"><p> + <em class="replaceable"><code>DST</code></em> is the zone abbreviation to be used + for daylight-savings time. If this field and the following ones are + omitted, the zone uses a fixed UTC offset with no daylight-savings + rule. + </p></li><li class="listitem"><p> + <em class="replaceable"><code>dstoffset</code></em> is the daylight-savings offset + from UTC. This field is typically omitted, since it defaults to one + hour less than the standard-time <em class="replaceable"><code>offset</code></em>, + which is usually the right thing. + </p></li><li class="listitem"><p> + <em class="replaceable"><code>rule</code></em> defines the rule for when daylight + savings is in effect, as described below. + </p></li></ul></div><p> + </p><p> + In this syntax, a zone abbreviation can be a string of letters, such + as <code class="literal">EST</code>, or an arbitrary string surrounded by angle + brackets, such as <code class="literal"><UTC-05></code>. + Note that the zone abbreviations given here are only used for output, + and even then only in some timestamp output formats. The zone + abbreviations recognized in timestamp input are determined as explained + in <a class="xref" href="datetime-config-files.html" title="B.4. Date/Time Configuration Files">Section B.4</a>. + </p><p> + The offset fields specify the hours, and optionally minutes and seconds, + difference from UTC. They have the format + <em class="replaceable"><code>hh</code></em>[<span class="optional"><code class="literal">:</code><em class="replaceable"><code>mm</code></em>[<span class="optional"><code class="literal">:</code><em class="replaceable"><code>ss</code></em></span>]</span>] + optionally with a leading sign (<code class="literal">+</code> + or <code class="literal">-</code>). The positive sign is used for + zones <span class="emphasis"><em>west</em></span> of Greenwich. (Note that this is the + opposite of the ISO-8601 sign convention used elsewhere in + <span class="productname">PostgreSQL</span>.) <em class="replaceable"><code>hh</code></em> + can have one or two digits; <em class="replaceable"><code>mm</code></em> + and <em class="replaceable"><code>ss</code></em> (if used) must have two. + </p><p> + The daylight-savings transition <em class="replaceable"><code>rule</code></em> has the + format +</p><pre class="synopsis"> +<em class="replaceable"><code>dstdate</code></em> [<span class="optional"> <code class="literal">/</code> <em class="replaceable"><code>dsttime</code></em> </span>] <code class="literal">,</code> <em class="replaceable"><code>stddate</code></em> [<span class="optional"> <code class="literal">/</code> <em class="replaceable"><code>stdtime</code></em> </span>] +</pre><p> + (As before, spaces should not be included in practice.) + The <em class="replaceable"><code>dstdate</code></em> + and <em class="replaceable"><code>dsttime</code></em> fields define when daylight-savings + time starts, while <em class="replaceable"><code>stddate</code></em> + and <em class="replaceable"><code>stdtime</code></em> define when standard time + starts. (In some cases, notably in zones south of the equator, the + former might be later in the year than the latter.) The date fields + have one of these formats: + </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>n</code></em></span></dt><dd><p> + A plain integer denotes a day of the year, counting from zero to + 364, or to 365 in leap years. + </p></dd><dt><span class="term"><code class="literal">J</code><em class="replaceable"><code>n</code></em></span></dt><dd><p> + In this form, <em class="replaceable"><code>n</code></em> counts from 1 to 365, + and February 29 is not counted even if it is present. (Thus, a + transition occurring on February 29 could not be specified this + way. However, days after February have the same numbers whether + it's a leap year or not, so that this form is usually more useful + than the plain-integer form for transitions on fixed dates.) + </p></dd><dt><span class="term"><code class="literal">M</code><em class="replaceable"><code>m</code></em><code class="literal">.</code><em class="replaceable"><code>n</code></em><code class="literal">.</code><em class="replaceable"><code>d</code></em></span></dt><dd><p> + This form specifies a transition that always happens during the same + month and on the same day of the week. <em class="replaceable"><code>m</code></em> + identifies the month, from 1 to 12. <em class="replaceable"><code>n</code></em> + specifies the <em class="replaceable"><code>n</code></em>'th occurrence of the + weekday identified by <em class="replaceable"><code>d</code></em>. + <em class="replaceable"><code>n</code></em> is a number between 1 and 4, or 5 + meaning the last occurrence of that weekday in the month (which + could be the fourth or the fifth). <em class="replaceable"><code>d</code></em> is + a number between 0 and 6, with 0 indicating Sunday. + For example, <code class="literal">M3.2.0</code> means <span class="quote">“<span class="quote">the second + Sunday in March</span>”</span>. + </p></dd></dl></div><p> + </p><div class="note"><h3 class="title">Note</h3><p> + The <code class="literal">M</code> format is sufficient to describe many common + daylight-savings transition laws. But note that none of these variants + can deal with daylight-savings law changes, so in practice the + historical data stored for named time zones (in the IANA time zone + database) is necessary to interpret past time stamps correctly. + </p></div><p> + The time fields in a transition rule have the same format as the offset + fields described previously, except that they cannot contain signs. + They define the current local time at which the change to the other + time occurs. If omitted, they default to <code class="literal">02:00:00</code>. + </p><p> + If a daylight-savings abbreviation is given but the + transition <em class="replaceable"><code>rule</code></em> field is omitted, + the fallback behavior is to use the + rule <code class="literal">M3.2.0,M11.1.0</code>, which corresponds to USA + practice as of 2020 (that is, spring forward on the second Sunday of + March, fall back on the first Sunday of November, both transitions + occurring at 2AM prevailing time). Note that this rule does not + give correct USA transition dates for years before 2007. + </p><p> + As an example, <code class="literal">CET-1CEST,M3.5.0,M10.5.0/3</code> describes + current (as of 2020) timekeeping practice in Paris. This specification + says that standard time has the abbreviation <code class="literal">CET</code> and + is one hour ahead (east) of UTC; daylight savings time has the + abbreviation <code class="literal">CEST</code> and is implicitly two hours ahead + of UTC; daylight savings time begins on the last Sunday in March at 2AM + CET and ends on the last Sunday in October at 3AM CEST. + </p><p> + The four timezone names <code class="literal">EST5EDT</code>, + <code class="literal">CST6CDT</code>, <code class="literal">MST7MDT</code>, + and <code class="literal">PST8PDT</code> look like they are POSIX zone + specifications. However, they actually are treated as named time zones + because (for historical reasons) there are files by those names in the + IANA time zone database. The practical implication of this is that + these zone names will produce valid historical USA daylight-savings + transitions, even when a plain POSIX specification would not. + </p><p> + One should be wary that it is easy to misspell a POSIX-style time zone + specification, since there is no check on the reasonableness of the + zone abbreviation(s). For example, <code class="literal">SET TIMEZONE TO + FOOBAR0</code> will work, leaving the system effectively using a + rather peculiar abbreviation for UTC. + </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="datetime-config-files.html" title="B.4. Date/Time Configuration Files">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="datetime-appendix.html" title="Appendix B. Date/Time Support">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="datetime-units-history.html" title="B.6. History of Units">Next</a></td></tr><tr><td width="40%" align="left" valign="top">B.4. Date/Time Configuration Files </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> B.6. History of Units</td></tr></table></div></body></html>
\ No newline at end of file |