On 7/12/22 15:57, Karl Berry wrote:
$ TZ=UTC-4 date -d 'TZ="UTC" 2022-07-24 15:00'
This doesn't mean what you want, because TZ=UTC-4 means "My time zone is
abbreviated 'UTC', and it's four hours east of Greenwich" which is not a
useful setting.
You're not the first person to run afoul of POSIX TZ strings, which are
poorly designed. I installed the attached patch to Gnulib to give
another example, which I hope clarifies things a bit. I'll cc this email
to bug-gnulib since the problem is in Gnulib not Coreutils proper.
If the offset syntax is documented anywhere, I couldn't find it. Sorry.
It's documented in the glibc manual, and this part of the Coreutils
manual (actually, taken from Gnulib) has a cross-reference to that.
BTW, in neither case did --debug clarify anything for me. In fact, it
confused me more, because the output seemingly did not include anything
about the offset at all, just reporting "UTC".
It'd be nice if --debug could diagnose invalid TZ settings. However,
this would likely require glibc support along the lines of what's in
tzcode and NetBSD (the tzalloc function).From f65d00ebacc891e57cca729041d028d07d1883bb Mon Sep 17 00:00:00 2001
From: Paul Eggert
Date: Tue, 12 Jul 2022 17:11:26 -0700
Subject: [PATCH] parse-datetime: improve doc for TZ="<-07>7" etc.
* doc/parse-datetime.texi (Specifying time zone rules):
Give examples of POSIX TZ strings that specify UTC offsets (Bug#56524).
---
ChangeLog | 6 ++
doc/parse-datetime.texi | 24 +---
2 files changed, 27 insertions(+), 3 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index cd01e0208e..f245082aa6 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2022-07-12 Paul Eggert
+
+ parse-datetime: improve doc for TZ="<-07>7" etc.
+ * doc/parse-datetime.texi (Specifying time zone rules):
+ Give examples of POSIX TZ strings that specify UTC offsets (Bug#56524).
+
2022-07-10 Bruno Haible
sigsegv: Optimize stackvma implementation for AIX 7.
diff --git a/doc/parse-datetime.texi b/doc/parse-datetime.texi
index 44305d136c..7939273691 100644
--- a/doc/parse-datetime.texi
+++ b/doc/parse-datetime.texi
@@ -554,9 +554,27 @@ The @samp{tz} database includes a wide variety of locations ranging
from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but
if you are at sea and have your own private time zone, or if you are
using a non-GNU host that does not support the @samp{tz}
-database, you may need to use a POSIX rule instead. Simple
-POSIX rules like @samp{UTC0} specify a time zone without
-daylight saving time; other rules can specify simple daylight saving
+database, you may need to use a POSIX rule instead.
+The previously-mentioned POSIX rule @samp{UTC0} says that the time zone
+abbreviation is @samp{UTC}, the zone is zero hours away from
+Greenwich, and there is no daylight saving time.
+Simple POSIX rules like this can also specify nonzero Greenwich offsets.
+For example, the following shell transcript answers the question
+``What time is it five and a half hours east of Greenwich when a clock
+seven hours west of Greenwich shows 9:50pm on July 12, 2022?''
+
+@example
+$ TZ="<+0530>-5:30" date --date='TZ="<-07>7" 2022-07-12 21:50'
+Wed Jul 13 10:20:00 +0530 2022
+@end example
+
+@noindent
+This example uses the somewhat-confusing POSIX convention for TZ strings.
+@samp{TZ="<-07>7"} says that the time zone abbreviation is @samp{-07}
+and the time zone is 7 hours west of Greenwich, and
+@samp{TZ="<+0530>-5:30"} says that the time zone abbreviation is @samp{+0530}
+and the time zone is 5 hours 30 minutes east of Greenwich.
+More-complex POSIX TZ strings can specify simple daylight saving
regimes. @xref{TZ Variable,, Specifying the Time Zone with @code{TZ},
libc, The GNU C Library}.
--
2.34.1
