[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
sh-utils.info misdocuments the date command
From: |
jeremy |
Subject: |
sh-utils.info misdocuments the date command |
Date: |
Thu, 5 Sep 2002 20:34:43 +0100 (BST) |
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
-----------------------------------------------------------------------------
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- sh-utils.info misdocuments the date command,
jeremy <=