coreutils: Specifying time zone rules

1 
1 29.10 Specifying time zone rules
1 ================================
1 
1 Normally, dates are interpreted using the rules of the current time
1 zone, which in turn are specified by the ‘TZ’ environment variable, or
1 by a system default if ‘TZ’ is not set.  To specify a different set of
1 default time zone rules that apply just to one date, start the date with
1 a string of the form ‘TZ="RULE"’.  The two quote characters (‘"’) must
1 be present in the date, and any quotes or backslashes within RULE must
1 be escaped by a backslash.
1 
1    For example, with the GNU ‘date’ command you can answer the question
1 “What time is it in New York when a Paris clock shows 6:30am on October
1 31, 2004?” by using a date beginning with ‘TZ="Europe/Paris"’ as shown
1 in the following shell transcript:
1 
1      $ export TZ="America/New_York"
1      $ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
1      Sun Oct 31 01:30:00 EDT 2004
1 
1    In this example, the ‘--date’ operand begins with its own ‘TZ’
1 setting, so the rest of that operand is processed according to
1 ‘Europe/Paris’ rules, treating the string ‘2004-10-31 06:30’ as if it
1 were in Paris.  However, since the output of the ‘date’ command is
1 processed according to the overall time zone rules, it uses New York
1 time.  (Paris was normally six hours ahead of New York in 2004, but this
1 example refers to a brief Halloween period when the gap was five hours.)
1 
1    A ‘TZ’ value is a rule that typically names a location in the ‘tz’
1 database (http://www.twinsun.com/tz/tz-link.htm).  A recent catalog of
1 location names appears in the TWiki Date and Time Gateway
1 (http://twiki.org/cgi-bin/xtra/tzdate).  A few non-GNU hosts require a
1 colon before a location name in a ‘TZ’ setting, e.g.,
1 ‘TZ=":America/New_York"’.
1 
1    The ‘tz’ database includes a wide variety of locations ranging from
1 ‘Arctic/Longyearbyen’ to ‘Antarctica/South_Pole’, but if you are at sea
1 and have your own private time zone, or if you are using a non-GNU host
1 that does not support the ‘tz’ database, you may need to use a POSIX
1 rule instead.  Simple POSIX rules like ‘UTC0’ specify a time zone
1 without daylight saving time; other rules can specify simple daylight
11 saving regimes.  ⇒Specifying the Time Zone with ‘TZ’ (libc)TZ
 Variable.
1