From 589e18a1f759698693029f1c3d4beed60deefc6c Mon Sep 17 00:00:00 2001 From: Jim Meyering Date: Mon, 14 Jul 1997 14:41:16 +0000 Subject: Tweak new examples based on Karl B.s suggestions. --- doc/sh-utils.texi | 39 +++++++++++++++++++++------------------ 1 file changed, 21 insertions(+), 18 deletions(-) (limited to 'doc') diff --git a/doc/sh-utils.texi b/doc/sh-utils.texi index 2f626e840..925f0473e 100644 --- a/doc/sh-utils.texi +++ b/doc/sh-utils.texi @@ -2454,29 +2454,37 @@ Mon, 25 Mar 1996 23:34:17 -0600 @end example @item -To convert a date string to the number of seconds since 1970-01-01 00:00:00, -use the @samp{--date} option with the @samp{%s} format. -That can be useful in sorting and graphing data by date. -The command in the following example prints the number of seconds that -elapsed between the epoch and the specified date: one second after midnight -on 1970-01-01. -But it is important to note that the date string is interpreted relative -to the local time zone, UTC+2, so it is two hours and one second -or @samp{7201} seconds after the @code{epoch}. +To convert a date string to the number of seconds since the epoch +(which is 1970-01-01 00:00:00 UTC), use the @samp{--date} option with +the @samp{%s} format. That can be useful in sorting and/or graphing +and/or comparing data by date. The following command outputs the +number of the seconds since the epoch for the time one second later +than the epoch, but in the time zone two hours later, thus a total +of two hours and one second after the epoch: @example -% env TZ=UTC+2 date --date='1970-01-01 00:00:01' +%s +date --date='1970-01-01 00:00:01 UTC +2 hours' +%s 7201 @end example +Suppose you had @emph{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 six +hours later than UTC on that day: + +@example +date --date='1970-01-01 00:00:01' +%s +21601 +@end example + @item If you're sorting or graphing dated data, your raw date values may be represented as seconds since the epoch. But few people can look at the date @samp{946684800} and casually note ``Oh, that's the first second -of the third millenium.'' +of the year 2000.'' @example -% env TZ=UTC date --date='2000-01-01' +%s +date --date='2000-01-01 UTC' +%s 946684800 @end example @@ -2484,15 +2492,10 @@ To convert such an unwieldy number of seconds back to a more readable form, use a command like this: @smallexample -% env TZ=UTC date -d '1970-01-01 UTC 946684800 sec' +"%Y-%m-%d %T %z" +date -d '1970-01-01 946684800 sec' +"%Y-%m-%d %T %z" 2000-01-01 00:00:00 +0000 @end smallexample -Note that in the few preceding examples, the timezone was set to -a specific value through the @samp{TZ} environment variable. -If you do not set @samp{TZ}, you must remember that @samp{--date} -strings are converted relative to the local time zone. - @end itemize -- cgit v1.2.3-70-g09d2