bug#11866: command date doesn't accept 61 sec. minutes

[Paul Eggert]

On 07/05/2012 01:05 PM, Juergen Heine wrote:
> If i'm correct, can we add this information to the manual for
> people who don't understand the simple line "leap seconds are
> getting ignored"?

Sure, I added the following and am marking this as done.


>From bfda96e0ac5552bb1784f5e1dc311918ce077d50 Mon Sep 17 00:00:00 2001
From: Paul Eggert <address@hidden>
Date: Thu, 5 Jul 2012 16:11:49 -0700
Subject: [PATCH 2/2] doc: document leap seconds better

* doc/coreutils.texi (touch invocation, Time conversion specifiers)
(Options for date, Examples of date): Index "leap seconds" and
improve their documentation a bit.
---
 doc/coreutils.texi |   39 ++++++++++++++++++++++++++++++++++++++-
 1 files changed, 38 insertions(+), 1 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 3c7f4e5..751a920 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -10493,13 +10493,15 @@ If @var{file} is a symbolic link, the reference 
timestamp is taken
 from the target of the symlink, unless @option{-h} was also in effect.
 
 @item -t address@hidden@address@hidden@var{ss}]
address@hidden leap seconds
 Use the argument (optional four-digit or two-digit years, months,
 days, hours, minutes, optional seconds) instead of the current time.
 If the year is specified with only two digits, then @var{cc}
 is 20 for years in the range 0 @dots{} 68, and 19 for years in
 69 @dots{} 99.  If no digits of the year are specified,
 the argument is interpreted as a date in the current year.
-Note that @var{ss} may be @samp{60}, to accommodate leap seconds.
+On the atypical systems that support leap seconds, @var{ss} may be
address@hidden
 
 @end table
 
@@ -14243,11 +14245,13 @@ locale's 12-hour clock time (e.g., @samp{11:11:04 PM})
 @cindex epoch, seconds since
 @cindex seconds since the epoch
 @cindex beginning of time
address@hidden leap seconds
 seconds since the epoch, i.e., since 1970-01-01 00:00:00 address@hidden
 Leap seconds are not counted unless leap second support is available.
 @xref{%s-examples}, for examples.
 This is a @acronym{GNU} extension.
 @item %S
address@hidden leap seconds
 second (@address@hidden@samp{60}).
 This may be @samp{60} if leap seconds are supported.
 @item %T
@@ -14650,12 +14654,15 @@ See also @ref{Setting the time}.
 @cindex UTC
 @cindex Greenwich Mean Time
 @cindex GMT
address@hidden leap seconds
 @vindex TZ
 Use Coordinated Universal Time (@acronym{UTC}) by operating as if the
 @env{TZ} environment variable were set to the string @samp{UTC0}.
 Coordinated
 Universal Time is often called ``Greenwich Mean Time'' (@sc{gmt}) for
 historical reasons.
+Typically, systems ignore leap seconds and thus implement an
+approximation to UTC rather than true UTC.
 @end table
 
 
@@ -14806,6 +14813,36 @@ date -u -d '1970-01-01 946684800 seconds' +"%Y-%m-%d 
%T %z"
 2000-01-01 00:00:00 +0000
 @end smallexample
 
address@hidden
address@hidden leap seconds
+Typically the seconds count omits leap seconds, but some systems are
+exceptions.  Because leap seconds are not predictable, the mapping
+between the seconds count and a future timestamp is not reliable on
+the atypical systems that include leap seconds in their counts.
+
+Here is how the two kinds of systems handle the leap second at
+2012-06-30 23:59:60 UTC:
+
address@hidden
+# Typical systems ignore leap seconds:
+date --date='2012-06-30 23:59:59 +0000' +%s
+1341100799
+date --date='2012-06-30 23:59:60 +0000' +%s
+date: invalid date '2012-06-30 23:59:60 +0000'
+date --date='2012-07-01 00:00:00 +0000' +%s
+1341100800
address@hidden example
+
address@hidden
+# Atypical systems count leap seconds:
+date --date='2012-06-30 23:59:59 +0000' +%s
+1341100823
+date --date='2012-06-30 23:59:60 +0000' +%s
+1341100824
+date --date='2012-07-01 00:00:00 +0000' +%s
+1341100825
address@hidden example
+
 @end itemize
 
 
-- 
1.7.6.5