%z and %Z in strftime man page require clarification

%z and %Z in strftime man page require clarification

[Almaz Mingaleev]

Hi Michael,
Current strftime specification in C language standard is not accurate.
It tells that tm_isdst is enough to find out time zone's offset. But
that's not true, for example Europe/Lisbon has changed [0] its
standard offset from 00:00 to 01:00 and back to 00:00, so an exact
date is needed to answer that.

To get correct answer with the current glibc tm struct should either
come from localtime or there should be a mktime call prior to
strftime. You can find a repro example and discussion here [1]. Paul
Eggert has proposed a fix to C standard [2].

Should man pages reflect that i.e. mention that there should be
localtime/mktime calls for %z and %Z?

Thanks,
Almaz

P.S. I am resending the email. My previous attempt was bounced back as
it wasn't TEXT/PLAIN.

[0] https://github.com/eggert/tz/blob/a249a0c64b2f87a24c7f1aab43056fb597c95b96/europe#L2400
[1] https://mm.icann.org/pipermail/tz/2022-July/031668.html
[2] https://mm.icann.org/pipermail/tz/2022-July/031674.html

Re: %z and %Z in strftime man page require clarification

[Almaz Mingaleev]

Friendly ping.


On Thu, 28 Jul 2022 at 09:16, Almaz Mingaleev <mingaleev@google.com> wrote:
>
> Hi Michael,
> Current strftime specification in C language standard is not accurate.
> It tells that tm_isdst is enough to find out time zone's offset. But
> that's not true, for example Europe/Lisbon has changed [0] its
> standard offset from 00:00 to 01:00 and back to 00:00, so an exact
> date is needed to answer that.
>
> To get correct answer with the current glibc tm struct should either
> come from localtime or there should be a mktime call prior to
> strftime. You can find a repro example and discussion here [1]. Paul
> Eggert has proposed a fix to C standard [2].
>
> Should man pages reflect that i.e. mention that there should be
> localtime/mktime calls for %z and %Z?
>
> Thanks,
> Almaz
>
> P.S. I am resending the email. My previous attempt was bounced back as
> it wasn't TEXT/PLAIN.
>
> [0] https://github.com/eggert/tz/blob/a249a0c64b2f87a24c7f1aab43056fb597c95b96/europe#L2400
> [1] https://mm.icann.org/pipermail/tz/2022-July/031668.html
> [2] https://mm.icann.org/pipermail/tz/2022-July/031674.html

Re: %z and %Z in strftime man page require clarification

[enh]

(given how complex a topic this is -- based on the discussion on the
tz mailing list -- you might want to send a specific suggestion in the
form of a patch...)

On Mon, Feb 13, 2023 at 1:15 AM Almaz Mingaleev <mingaleev@google.com> wrote:
>
> Friendly ping.
>
>
> On Thu, 28 Jul 2022 at 09:16, Almaz Mingaleev <mingaleev@google.com> wrote:
> >
> > Hi Michael,
> > Current strftime specification in C language standard is not accurate.
> > It tells that tm_isdst is enough to find out time zone's offset. But
> > that's not true, for example Europe/Lisbon has changed [0] its
> > standard offset from 00:00 to 01:00 and back to 00:00, so an exact
> > date is needed to answer that.
> >
> > To get correct answer with the current glibc tm struct should either
> > come from localtime or there should be a mktime call prior to
> > strftime. You can find a repro example and discussion here [1]. Paul
> > Eggert has proposed a fix to C standard [2].
> >
> > Should man pages reflect that i.e. mention that there should be
> > localtime/mktime calls for %z and %Z?
> >
> > Thanks,
> > Almaz
> >
> > P.S. I am resending the email. My previous attempt was bounced back as
> > it wasn't TEXT/PLAIN.
> >
> > [0] https://github.com/eggert/tz/blob/a249a0c64b2f87a24c7f1aab43056fb597c95b96/europe#L2400
> > [1] https://mm.icann.org/pipermail/tz/2022-July/031668.html
> > [2] https://mm.icann.org/pipermail/tz/2022-July/031674.html

Re: %z and %Z in strftime man page require clarification

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1805 bytes --]

Hi Elliott, Almaz,

On 2/13/23 17:31, enh wrote:
> (given how complex a topic this is -- based on the discussion on the
> tz mailing list -- you might want to send a specific suggestion in the
> form of a patch...)

Thanks, I agree.  This is too complex, and it would be nice to
see a more specific suggestion in the form of a patch.
I CCed Paul, in case he can help.

Cheers,

Alex

> 
> On Mon, Feb 13, 2023 at 1:15 AM Almaz Mingaleev <mingaleev@google.com> wrote:
>>
>> Friendly ping.
>>
>>
>> On Thu, 28 Jul 2022 at 09:16, Almaz Mingaleev <mingaleev@google.com> wrote:
>>>
>>> Hi Michael,
>>> Current strftime specification in C language standard is not accurate.
>>> It tells that tm_isdst is enough to find out time zone's offset. But
>>> that's not true, for example Europe/Lisbon has changed [0] its
>>> standard offset from 00:00 to 01:00 and back to 00:00, so an exact
>>> date is needed to answer that.
>>>
>>> To get correct answer with the current glibc tm struct should either
>>> come from localtime or there should be a mktime call prior to
>>> strftime. You can find a repro example and discussion here [1]. Paul
>>> Eggert has proposed a fix to C standard [2].
>>>
>>> Should man pages reflect that i.e. mention that there should be
>>> localtime/mktime calls for %z and %Z?
>>>
>>> Thanks,
>>> Almaz
>>>
>>> P.S. I am resending the email. My previous attempt was bounced back as
>>> it wasn't TEXT/PLAIN.
>>>
>>> [0] https://github.com/eggert/tz/blob/a249a0c64b2f87a24c7f1aab43056fb597c95b96/europe#L2400
>>> [1] https://mm.icann.org/pipermail/tz/2022-July/031668.html
>>> [2] https://mm.icann.org/pipermail/tz/2022-July/031674.html

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: %z and %Z in strftime man page require clarification

[Almaz Mingaleev]

Hi Alex,

Patch is somewhat ready, I will send it once a teammate reviews it.
Should be ready by tomorrow.

I'd definitely appreciate if Paul checks it too :)


On Wed, 15 Feb 2023 at 17:21, Alejandro Colomar <alx.manpages@gmail.com> wrote:
>
> Hi Elliott, Almaz,
>
> On 2/13/23 17:31, enh wrote:
> > (given how complex a topic this is -- based on the discussion on the
> > tz mailing list -- you might want to send a specific suggestion in the
> > form of a patch...)
>
> Thanks, I agree.  This is too complex, and it would be nice to
> see a more specific suggestion in the form of a patch.
> I CCed Paul, in case he can help.
>
> Cheers,
>
> Alex
>
> >
> > On Mon, Feb 13, 2023 at 1:15 AM Almaz Mingaleev <mingaleev@google.com> wrote:
> >>
> >> Friendly ping.
> >>
> >>
> >> On Thu, 28 Jul 2022 at 09:16, Almaz Mingaleev <mingaleev@google.com> wrote:
> >>>
> >>> Hi Michael,
> >>> Current strftime specification in C language standard is not accurate.
> >>> It tells that tm_isdst is enough to find out time zone's offset. But
> >>> that's not true, for example Europe/Lisbon has changed [0] its
> >>> standard offset from 00:00 to 01:00 and back to 00:00, so an exact
> >>> date is needed to answer that.
> >>>
> >>> To get correct answer with the current glibc tm struct should either
> >>> come from localtime or there should be a mktime call prior to
> >>> strftime. You can find a repro example and discussion here [1]. Paul
> >>> Eggert has proposed a fix to C standard [2].
> >>>
> >>> Should man pages reflect that i.e. mention that there should be
> >>> localtime/mktime calls for %z and %Z?
> >>>
> >>> Thanks,
> >>> Almaz
> >>>
> >>> P.S. I am resending the email. My previous attempt was bounced back as
> >>> it wasn't TEXT/PLAIN.
> >>>
> >>> [0] https://github.com/eggert/tz/blob/a249a0c64b2f87a24c7f1aab43056fb597c95b96/europe#L2400
> >>> [1] https://mm.icann.org/pipermail/tz/2022-July/031668.html
> >>> [2] https://mm.icann.org/pipermail/tz/2022-July/031674.html
>
> --
> <http://www.alejandro-colomar.es/>
> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

Re: %z and %Z in strftime man page require clarification

[Almaz Mingaleev]

[-- Attachment #1: Type: text/plain, Size: 2394 bytes --]

I've started a new thread, but can't see it in the mailing list archives.
Please see the patch attached.


On Wed, 15 Feb 2023 at 17:34, Almaz Mingaleev <mingaleev@google.com> wrote:
>
> Hi Alex,
>
> Patch is somewhat ready, I will send it once a teammate reviews it.
> Should be ready by tomorrow.
>
> I'd definitely appreciate if Paul checks it too :)
>
>
> On Wed, 15 Feb 2023 at 17:21, Alejandro Colomar <alx.manpages@gmail.com> wrote:
> >
> > Hi Elliott, Almaz,
> >
> > On 2/13/23 17:31, enh wrote:
> > > (given how complex a topic this is -- based on the discussion on the
> > > tz mailing list -- you might want to send a specific suggestion in the
> > > form of a patch...)
> >
> > Thanks, I agree.  This is too complex, and it would be nice to
> > see a more specific suggestion in the form of a patch.
> > I CCed Paul, in case he can help.
> >
> > Cheers,
> >
> > Alex
> >
> > >
> > > On Mon, Feb 13, 2023 at 1:15 AM Almaz Mingaleev <mingaleev@google.com> wrote:
> > >>
> > >> Friendly ping.
> > >>
> > >>
> > >> On Thu, 28 Jul 2022 at 09:16, Almaz Mingaleev <mingaleev@google.com> wrote:
> > >>>
> > >>> Hi Michael,
> > >>> Current strftime specification in C language standard is not accurate.
> > >>> It tells that tm_isdst is enough to find out time zone's offset. But
> > >>> that's not true, for example Europe/Lisbon has changed [0] its
> > >>> standard offset from 00:00 to 01:00 and back to 00:00, so an exact
> > >>> date is needed to answer that.
> > >>>
> > >>> To get correct answer with the current glibc tm struct should either
> > >>> come from localtime or there should be a mktime call prior to
> > >>> strftime. You can find a repro example and discussion here [1]. Paul
> > >>> Eggert has proposed a fix to C standard [2].
> > >>>
> > >>> Should man pages reflect that i.e. mention that there should be
> > >>> localtime/mktime calls for %z and %Z?
> > >>>
> > >>> Thanks,
> > >>> Almaz
> > >>>
> > >>> P.S. I am resending the email. My previous attempt was bounced back as
> > >>> it wasn't TEXT/PLAIN.
> > >>>
> > >>> [0] https://github.com/eggert/tz/blob/a249a0c64b2f87a24c7f1aab43056fb597c95b96/europe#L2400
> > >>> [1] https://mm.icann.org/pipermail/tz/2022-July/031668.html
> > >>> [2] https://mm.icann.org/pipermail/tz/2022-July/031674.html
> >
> > --
> > <http://www.alejandro-colomar.es/>
> > GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: 0001-Add-notes-about-timezone-formatting-in-strftime.patch --]
[-- Type: application/octet-stream, Size: 3073 bytes --]

From e116c394e8a15736c2155f6335964aaa17802bc1 Mon Sep 17 00:00:00 2001
From: Almaz Mingaleev <mingaleev@google.com>
Date: Thu, 23 Feb 2023 12:30:16 +0000
Subject: [PATCH] Add notes about timezone formatting in strftime.

According to libc specification in order to find replacements for
%z and %Z the only tm struct field needed is tm_isdst. However
governments change offsets, both standard and daylight saving.

For example, Europe/Lisbon changed its standard offset from GMT+1
to GMT in 1996 [1]. So in order to find out %z replacement exact
time is needed

Pacific/Fiji does not observe DST since 2021 [2]. Requesting its
daylight saving offset (even with date and time specified in tm
struct argument) just makes no sense and strftime has no means
to indicate invalid combination.

The same things are applicable to %Z as abbreviation also change
over time.

To overcome these issues:
1. tm struct should point to an exact date and tm_isdst flag
should be provided if possible as dates can overlap when clocks
go backwards.

2. Either mktime should be called to bring tm struct into valid
state and fill fields like tm_zone and tm_gmtoff or tm struct
should comes from functions like localtime.

[1] https://github.com/eggert/tz/blob/6765f094aa004ca84057d4721b94136266dd978c/europe#L2119
[2] https://github.com/eggert/tz/blob/6765f094aa004ca84057d4721b94136266dd978c/australasia#L366

Signed-off-by: Almaz Mingaleev <mingaleev@google.com>
---
 man3/strftime.3 | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/man3/strftime.3 b/man3/strftime.3
index 57b2a38aa..0178fd4eb 100644
--- a/man3/strftime.3
+++ b/man3/strftime.3
@@ -645,6 +645,51 @@ and of these, it is only really useful with
 An optional decimal width specifier may follow the (possibly absent) flag.
 If the natural size of the field is smaller than this width,
 then the result string is padded (on the left) to the specified width.
+.SS Timezone formatting
+Timezones change frequently and any part of it can change: rules by which
+daylight saving time starts and ends, or whether it starts at all, its
+standard and daylight saving offsets. In order to find numeric offset
+.RB ( %z ),
+name or abbreviation
+.RB ( %Z )
+exact date/time
+.RI ( tm_sec ,
+.IR tm_min ,
+.IR tm_hou r,
+.IR tm_mday ,
+.IR tm_mon
+and
+.IR tm_year
+fields) and DST flag
+.RI ( tm_isdst
+field) as there is an overlap when clocks go backwards have to be specified.
+
+But according to the latest libc specification only
+.IR tm_isdst
+field is needed to calculate replacements for
+.BR %z
+and
+.BR %Z.
+That does not conform to the reality of timezones.
+glibc implementation does not follow libc specification and uses
+.IR tm_gmtoff
+for
+.BR %z
+and
+.IR tm_zone
+for
+.BR %Z
+replacements. To populate these fields with the right values either call
+.BR mktime ()
+before passing
+.IR tm
+struct to
+.BR strftime ()
+or make sure that
+.IR tm
+struct comes from
+.BR localtime ().
+
 .SH BUGS
 If the output string would exceed
 .I max
-- 
2.39.2.637.g21b0678d19-goog

Re: %z and %Z in strftime man page require clarification

[Alex Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 2914 bytes --]

Hi Almaz,

On 2/24/23 17:40, Almaz Mingaleev wrote:
> I've started a new thread, but can't see it in the mailing list archives.
> Please see the patch attached.

Thanks!

Could you please send the patch inline (if you use git-format-patch(1), 
that would be --no-attach (or --inline, but I prefer --no-attach)), so I 
can quote reply on it?

If you fear that your mailer will do harmful stuff, please send it both 
attached and inline.

Cheers,

Alex

> 
> 
> On Wed, 15 Feb 2023 at 17:34, Almaz Mingaleev <mingaleev@google.com> wrote:
>>
>> Hi Alex,
>>
>> Patch is somewhat ready, I will send it once a teammate reviews it.
>> Should be ready by tomorrow.
>>
>> I'd definitely appreciate if Paul checks it too :)
>>
>>
>> On Wed, 15 Feb 2023 at 17:21, Alejandro Colomar <alx.manpages@gmail.com> wrote:
>>>
>>> Hi Elliott, Almaz,
>>>
>>> On 2/13/23 17:31, enh wrote:
>>>> (given how complex a topic this is -- based on the discussion on the
>>>> tz mailing list -- you might want to send a specific suggestion in the
>>>> form of a patch...)
>>>
>>> Thanks, I agree.  This is too complex, and it would be nice to
>>> see a more specific suggestion in the form of a patch.
>>> I CCed Paul, in case he can help.
>>>
>>> Cheers,
>>>
>>> Alex
>>>
>>>>
>>>> On Mon, Feb 13, 2023 at 1:15 AM Almaz Mingaleev <mingaleev@google.com> wrote:
>>>>>
>>>>> Friendly ping.
>>>>>
>>>>>
>>>>> On Thu, 28 Jul 2022 at 09:16, Almaz Mingaleev <mingaleev@google.com> wrote:
>>>>>>
>>>>>> Hi Michael,
>>>>>> Current strftime specification in C language standard is not accurate.
>>>>>> It tells that tm_isdst is enough to find out time zone's offset. But
>>>>>> that's not true, for example Europe/Lisbon has changed [0] its
>>>>>> standard offset from 00:00 to 01:00 and back to 00:00, so an exact
>>>>>> date is needed to answer that.
>>>>>>
>>>>>> To get correct answer with the current glibc tm struct should either
>>>>>> come from localtime or there should be a mktime call prior to
>>>>>> strftime. You can find a repro example and discussion here [1]. Paul
>>>>>> Eggert has proposed a fix to C standard [2].
>>>>>>
>>>>>> Should man pages reflect that i.e. mention that there should be
>>>>>> localtime/mktime calls for %z and %Z?
>>>>>>
>>>>>> Thanks,
>>>>>> Almaz
>>>>>>
>>>>>> P.S. I am resending the email. My previous attempt was bounced back as
>>>>>> it wasn't TEXT/PLAIN.
>>>>>>
>>>>>> [0] https://github.com/eggert/tz/blob/a249a0c64b2f87a24c7f1aab43056fb597c95b96/europe#L2400
>>>>>> [1] https://mm.icann.org/pipermail/tz/2022-July/031668.html
>>>>>> [2] https://mm.icann.org/pipermail/tz/2022-July/031674.html
>>>
>>> --
>>> <http://www.alejandro-colomar.es/>
>>> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: %z and %Z in strftime man page require clarification

[Paul Eggert]

[-- Attachment #1: Type: text/plain, Size: 436 bytes --]

That patch looks complex and rather than go into its nooks and crannies, 
how about something much simpler, like the attached? This would be 
better for the typical reader of the strftime man page.

Although tm_zone and tm_gmtoff are not 100% portable to oddball 
platforms like MS-Windows, they'll be in the next POSIX and if that 
portability issue is to be documented at all any longwinded discussion 
should go in tm.3type not here.

[-- Attachment #2: 0001-strftime.3-document-how-z-and-Z-are-calculated.patch --]
[-- Type: text/x-patch, Size: 790 bytes --]

From 4b2ffe84d5abc5b11323657fdfb812c7269ce2d3 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Fri, 24 Feb 2023 17:02:37 -0800
Subject: [PATCH] strftime.3: document how %z and %Z are calculated

---
 man3/strftime.3 | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/man3/strftime.3 b/man3/strftime.3
index 57b2a38aa..90248d0b4 100644
--- a/man3/strftime.3
+++ b/man3/strftime.3
@@ -417,6 +417,8 @@ The
 or
 .I \-hhmm
 numeric timezone (that is, the hour and minute offset from UTC). (SU)
+(Calculated from
+.IR tm_gmtoff .)
 .TP
 .B %Z
 The timezone name or abbreviation.
@@ -427,6 +429,8 @@ The timezone name or abbreviation.
 The date and time in
 .BR date (1)
 format. (TZ)
+(Calculated from
+.IR tm_zone .)
 (Not supported in glibc2.)
 .TP
 .B %%
-- 
2.37.2

Re: %z and %Z in strftime man page require clarification

[Almaz Mingaleev]

Thanks Paul, looks good to me. Just one follow-up question: mktime's
man page does not mention tm_gmtoff / tm_zone fields. Should it also
be updated, for completeness?
I'd assume it is not a big deal as I couldn't find anyone who faced the
same issue with timezone formatting in strftime, but still.

On Sat, 25 Feb 2023 at 01:11, Paul Eggert <eggert@cs.ucla.edu> wrote:
>
> That patch looks complex and rather than go into its nooks and crannies,
> how about something much simpler, like the attached? This would be
> better for the typical reader of the strftime man page.
>
> Although tm_zone and tm_gmtoff are not 100% portable to oddball
> platforms like MS-Windows, they'll be in the next POSIX and if that
> portability issue is to be documented at all any longwinded discussion
> should go in tm.3type not here.

Re: %z and %Z in strftime man page require clarification

[Paul Eggert]

On 2/27/23 00:52, Almaz Mingaleev wrote:
> Thanks Paul, looks good to me. Just one follow-up question: mktime's
> man page does not mention tm_gmtoff / tm_zone fields. Should it also
> be updated, for completeness?

Quite possibly. Lots of updates are needed in this area; I'm afraid I 
haven't had time to look into it. (The general rule ought to be to keep 
it short and sweet, and of course that takes more time....)

Re: %z and %Z in strftime man page require clarification

[Almaz Mingaleev]

Alex and Michael,
Please let me know if the patch proposed by Paul can be applied
on its own.
If you also think that mktime should be updated, I can try to
prepare a patch for it.


On Mon, 27 Feb 2023 at 20:43, Paul Eggert <eggert@cs.ucla.edu> wrote:
>
> On 2/27/23 00:52, Almaz Mingaleev wrote:
> > Thanks Paul, looks good to me. Just one follow-up question: mktime's
> > man page does not mention tm_gmtoff / tm_zone fields. Should it also
> > be updated, for completeness?
>
> Quite possibly. Lots of updates are needed in this area; I'm afraid I
> haven't had time to look into it. (The general rule ought to be to keep
> it short and sweet, and of course that takes more time....)