sh-utils.info misdocuments the date command

[jeremy]

Package: shellutils
Version: 2.0.11-11

File: sh-utils.info
Node: Examples of date

Bug: date invocations involving "seconds since epoch" documented wrongly

Contents of this bug report:

(1) Outline
(2) Version information
(3) Description of problem
(4) Explanation and history lesson
(5) Suggested correction of manual
(6) Appendix (this bug has existed for some time)

* (1) Outline

There are some errors in the Texinfo manual for the "date" command.
The description of how to convert back and forth between "seconds
since the epoch" and human-style dates is partially incorrect.

In one case, the manual explicitly states what the output is, but the
system actually gives different output.

The info page in question is
   File: sh-utils.info
   Node: Examples of date


* (2) Version information

I'm using the GNU shell utilities version 2.0.11

Operating system: Debian GNU/Linux 3.0 (woody)
$ uname -a
Linux debian 2.2.19 #1 Thu Nov 1 19:52:06 EST 2001 i686 unknown

Package version information

$ dpkg -l shellutils libc6
Desired=Unknown/Install/Remove/Purge/Hold
| Status=Not/Installed/Config-files/Unpacked/Failed-config/Half-installed
|/ Err?=(none)/Hold/Reinst-required/X=both-problems (Status,Err: uppercase=bad)
||/ Name            Version         Description
+++-===============-===============-==============================================
ii  shellutils      2.0.11-11       The GNU shell programming utilities.
ii  libc6           2.2.5-6         GNU C Library: Shared libraries and 
Timezone d

My timezone was set (using tzconfig) to Europe/London

$ ls -al /etc/localtime
lrwxrwxrwx    1 root     root           33 Aug 26 02:04 /etc/localtime -> 
/usr/share/zoneinfo/Europe/London


* (3) Description of problem

Towards the end of the manual page, there is a discussion of how to
convert back and forth between "seconds since the epoch" and
human-readable dates.  The first example works correctly, 
whatever the local time zone:

  $ date --date='1970-01-01 00:00:01 UTC +5 hours' +%s
  18001

The manual goes on to say:

     Suppose you had _not_ specified time zone information in the
     example above.  Then, date would have used your computer's idea of
     the time zone when interpreting the string.  Here's what you would
     get if you were in Greenwich, England:

          # local time zone used
          date --date='1970-01-01 00:00:01' +%s
          1                                                                    

This is wrong!  On my system, I get:

  $ date --date='1970-01-01 00:00:01' +%s
  -3599    


* (4) Explanation and history lesson

Surprisingly, the manual is wrong and my system is correct.  For many
years, Britain has used GMT in winter and BST in summer.  However, the
start of the unix date epoch happens to lie in the period when Britain
experimented with so-called "British Standard Time".  The idea didn't
catch on (it was unpopular in the north, where the mornings were too
dark in winter).  Here is the definition from Collins English
Dictionary (3rd edn, updated 1994).

  British Standard Time  n.  the standard time used in Britain all the
  year round from 1968 to 1971, set one hour ahead of Greenwich Mean
  Time and equalling Central European Time

The dictionary is not accurate when it says "all the year round".  The
clocks went forward to British Summer Time (BST) in the spring of
1968, and stayed there for three years until the autumn of 1971.
(Presumably the name British Standard Time was chosen because it has
the same abbreviation as British Summer Time, but avoids the silliness
of using Summer Time in the winter).

I don't know how to read the timezone file (it's in a binary format)
but we can ask the system how long it thinks British Standard Time
lasted.  A little trial and error gives:

debian:~$ date --date='1968-02-18 01:59:59'
Sun Feb 18 01:59:59 GMT 1968
debian:~$ date --date='1968-02-18 02:00:00'
Sun Feb 18 03:00:00 BST 1968

The system knows that 2am is meaningless; the clocks were put forward
one hour at 2am GMT.

debian:~$ date --date='1969-01-01 00:00:00'
Wed Jan  1 00:00:00 BST 1969
debian:~$ date --date='1970-01-01 00:00:00'
Thu Jan  1 00:00:00 BST 1970
debian:~$ date --date='1971-01-01 00:00:00'
Fri Jan  1 00:00:00 BST 1971

For three winters, local time was GMT+0100.  Unfortunately for the
author of the date manual, that includes the winter in which the unix
date epoch began.

debian:~$ date --date='1971-10-31 01:59:59'
Sun Oct 31 01:59:59 BST 1971
debian:~$ date --date='1971-10-31 02:00:00'
Sun Oct 31 02:00:00 GMT 1971

The normal pattern of GMT in winter and BST in summer was restored in
October 1971.



* (5) Suggested correction of manual

I suggest changing the manual to read as follows.

<new>
     Suppose you had _not_ specified time zone information in the
     example above.  Then, date would have used your computer's idea of
     the local time zone when interpreting the string.  Here's what you
     might expect to see if you were in Greenwich, England:

          # local time zone used
          date --date='1970-01-01 00:00:01' +%s
          1                                                                    

     In fact, if you try this example, you get

          # local time zone is Europe/London
          date --date='1970-01-01 00:00:01' +%s
          -3599
                                                                               
     This may be surprising, but it is correct.  For three years from
     1968 to 1971, Britain used GMT+0100 even in the winter (it was
     called BST or "British Standard Time").

     Thus, it is not safe to omit the time zone from such
     calculations, even if your local time zone is GMT.
</new>

The last example also needs correction, since omission of "UTC" will
lead to surprises:

# local time is used: GMT+0100 even in winter
$ date -d '1970-01-01 946684800 sec' +"%Y-%m-%d %T %z"
1999-12-31 23:00:00 +0000

# specifying GMT (UTC) gives the expected result
$ date -d '1970-01-01 UTC 946684800 sec' +"%Y-%m-%d %T %z"
2000-01-01 00:00:00 +0000

I suggest correcting the last example as follows:

<new>
     To convert such an unwieldy number of seconds back to a more
     readable form, use a command like this:

          date -d '1970-01-01 UTC 946684800 sec' +"%Y-%m-%d %T %z"
          2000-01-01 00:00:00 +0000

     Remember to include UTC to avoid surprises.
</new>


----------------------------------------------------------------------

* (6) Appendix

I first noticed this bug on potato, using
shellutils     2.0-7          The GNU shell programming utilities.
libc6          2.1.3-19       GNU C Library: Shared libraries and Timezone

On that system, the answer last example "wrong" with or without UTC:

debian:~$ date -d '1970-01-01 UTC 946684800 sec' +"%Y-%m-%d %T %z"
1999-12-31 23:00:00 +0000

It's nice to see that this bug has been fixed!


-- 
-----------------------------------------------------------------------------
Dr J S Bygott, Oxford.    Tel: +44 (01865) 558178     Fax: +44 (01865) 556256
-----------------------------------------------------------------------------