[PATCH 0/4] hwclock: x86_64 -- UTC Defaults -- v2.26 man updates

[PATCH 0/4] hwclock: x86_64 -- UTC Defaults -- v2.26 man updates

[JWP]

I think I heard Mr. Zak say RC1 is coming, so I
wanted to add some more documentation details for
the hwclock v2.26 changes.

While testing to make sure what I wrote was
correct, I found 2 new minor bugs.  I want to slip
the patches in for them this release so the manual
will make sense.

Then I decided to do some man page errata and drop
some outdated language... and then I authored a
new configuration section... well it ended up
being a more sizable patch then I intended. I 
apologize for that, but it's not code so I hope it
will be okay. A rewrite of the man page is on my 
todo list after hwclock refactoring is finished; 
this patch puts a good scratch in some of what I 
intended todo.

If the POSIX vs 'RIGHT' section sounds vaguely
familiar, you're probably recalling this commit:
d53f8ecfbf036eddb2aef737dc0973a613d80ced
Which should never have been accepted.

>From his email, Mr. Parmelee appears to be seriously confused.
http://marc.info/?l=util-linux-ng&m=136543342327830&w=2

But I'll bring this discussion up in a hwclock
refactoring RFC later on.

I made the final man page patch separate so it can
be rejected easily. We've already visited that
subject a few times now and perhaps Karel doesn't
want to mess with it anymore.

I wish everyone here a Happy New Year!

J William Piggott (4):
  hwclock: enable --directisa for x86_64
  hwclock: Incorrect UTC defaults
  hwclock: update man page for v2.26 rc
  hwclock: man page 'Since v2.26' notes

 sys-utils/hwclock-cmos.c |    9 +-
 sys-utils/hwclock.8.in   | 1148 ++++++++++++++++++++++++++++++----------------
 sys-utils/hwclock.c      |    4 +-
 3 files changed, 759 insertions(+), 402 deletions(-)

[PATCH 1/4] hwclock: enable --directisa for x86_64

[JWP]

Currently only x86 and Alpha can use --directisa.
This patch allows x86_64 machines to use it as well.

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 sys-utils/hwclock-cmos.c | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/sys-utils/hwclock-cmos.c b/sys-utils/hwclock-cmos.c
index ca6ab1c..8d68808 100644
--- a/sys-utils/hwclock-cmos.c
+++ b/sys-utils/hwclock-cmos.c
@@ -55,7 +55,7 @@
 #include "c.h"
 #include "nls.h"
 
-#if defined(__i386__)
+#if defined(__i386__) || defined(__x86_64__)
 # ifdef HAVE_SYS_IO_H
 #  include <sys/io.h>
 # elif defined(HAVE_ASM_IO_H)
@@ -66,6 +66,7 @@
  * not export that header.
  */
 #undef __i386__
+#undef __x86_64__
 void outb(int a __attribute__ ((__unused__)),
 	  int b __attribute__ ((__unused__)))
 {
@@ -75,7 +76,7 @@ int inb(int c __attribute__ ((__unused__)))
 {
 	return 0;
 }
-#endif				/* __i386__ */
+#endif				/* __i386__ __x86_64__ */
 
 #elif defined(__alpha__)
 /* <asm/io.h> fails to compile, probably because of u8 etc */
@@ -603,7 +604,7 @@ static int set_hardware_clock_cmos(const struct tm *new_broken_time)
 	return 0;
 }
 
-#if defined(__i386__) || defined(__alpha__)
+#if defined(__i386__) || defined(__alpha__) || defined(__x86_64__)
 # if defined(HAVE_IOPL)
 static int i386_iopl(const int level)
 {
@@ -663,7 +664,7 @@ static struct clock_ops cmos = {
 struct clock_ops *probe_for_cmos_clock(void)
 {
 	int have_cmos =
-#if defined(__i386__) || defined(__alpha__)
+#if defined(__i386__) || defined(__alpha__) || defined(__x86_64__)
 	    TRUE;
 #else
 	    FALSE;

[PATCH 2/4] hwclock: Incorrect UTC defaults

[JWP]

Hwclock's default timescale was changed to UTC in:

commit 7894bf0f08740f75610990a2ba76af7a7cbce61e
Date:   Mon Feb 21 13:27:07 2011 +0000

This change was incomplete.

With no /etc/adjtime file the current behavior is:
hwclock --utc --adjust        #Creates a UTC file.
hwclock --localtime --adjust  #File is not created.

That is the opposite of what UTC default should do.

With this patch the behavior is:
hwclock --utc --adjust        #File is not created.
hwclock --localtime --adjust  #Creates a LOCAL file.

'Creates a xxxx file' means: An /etc/adjtime file
is created with zero for all parameters except the
Hardware Clock's timescale field, which is set to
the value indicated by xxxx.

The second item missed in the patch was a test in
the save_adjtime() function that defaults to LOCAL.

Theoretically we cannot get to the save function
without having a value set for adjtime.local_utc,
but the test is there so it needs be correct.

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 sys-utils/hwclock.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/sys-utils/hwclock.c b/sys-utils/hwclock.c
index 008b20a..4d40dc5 100644
--- a/sys-utils/hwclock.c
+++ b/sys-utils/hwclock.c
@@ -272,7 +272,7 @@ static int read_adjtime(struct adjtime *adjtime_p)
 		adjtime_p->last_adj_time = 0;
 		adjtime_p->not_adjusted = 0;
 		adjtime_p->last_calib_time = 0;
-		adjtime_p->local_utc = UNKNOWN;
+		adjtime_p->local_utc = UTC;
 		adjtime_p->dirty = FALSE;	/* don't create a zero adjfile */
 
 		return 0;
@@ -1135,7 +1135,7 @@ static void save_adjtime(const struct adjtime adjtime, const bool testing)
 			(long)adjtime.last_adj_time,
 			adjtime.not_adjusted,
 			(long)adjtime.last_calib_time,
-			(adjtime.local_utc == UTC) ? "UTC" : "LOCAL");
+			(adjtime.local_utc == LOCAL) ? "LOCAL" : "UTC");
 
 		if (testing) {
 			printf(_

[PATCH 3/4] hwclock: update man page for v2.26 rc

[JWP]

Authored new section: DATE-TIME CONFIGURATION.
Subsections: Keeping Time..., LOCAL vs UTC, POSIX vs 'RIGHT'.
Errata and drop outdated language.
Updates for v2.26

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 sys-utils/hwclock.8.in | 1132 ++++++++++++++++++++++++++++++++----------------
 1 file changed, 751 insertions(+), 381 deletions(-)

diff --git a/sys-utils/hwclock.8.in b/sys-utils/hwclock.8.in
index 0c654a5..505ff65 100644
--- a/sys-utils/hwclock.8.in
+++ b/sys-utils/hwclock.8.in
@@ -1,30 +1,48 @@
-.TH HWCLOCK 8 "October 2014" "util-linux" "System Administration"
+.\" hwclock.8.in -- man page for util-linux' hwclock
+.\"
+.\" 2015-01-07 J William Piggott
+.\" Authored new section: DATE-TIME CONFIGURATION.
+.\" Subsections: Keeping Time..., LOCAL vs UTC, POSIX vs 'RIGHT'.
+.\" Errata and drop outdated language.
+.\" Updates for v2.26
+.\"
+.\"
+.\" -------------------------------
+.\" Included for troff portability.
+.\" Continuation line for .TP header.
+.de TQ
+.  br
+.  ns
+.  TP \\$1\" no doublequotes around argument!
+..
+.
+.\" -------------------------------
+.
+.TH HWCLOCK 8 "January 2015" "util-linux" "System Administration"
 .SH NAME
-hwclock \- query or set the hardware clock (RTC)
+hwclock \- read or set the hardware clock (RTC)
 .SH SYNOPSIS
 .B hwclock
 .RI [ function ]
 .RI [ option ...]
-
+.
 .SH DESCRIPTION
 .B hwclock
-is a tool for accessing the Hardware Clock.  You can display the
-current time, set the Hardware Clock to a specified time, set the
-Hardware Clock from the System Time, or set the System Time from the
-Hardware Clock.
+is a tool for accessing the Hardware Clock.  It can: display the
+Hardware Clock time; set the Hardware Clock to a specified time; set the
+Hardware Clock from the System Clock; set the System Clock from the
+Hardware Clock; compensate for Hardware Clock drift; correct the System
+Clock timescale; set the kernel's timezone, NTP timescale, and epoch
+(Alpha only); compare the System and Hardware Clocks; and predict future
+Hardware Clock values based on its drift rate.
 .PP
-You can also run
-.B hwclock
-periodically to add or subtract time from the Hardware Clock to
-compensate for systematic drift (where the clock consistently loses or
-gains time at a certain rate when left to run).
-
 Since v2.26
 .B hwclock
 does not update the Hardware Clock's drift factor in @ADJTIME_PATH@ by default.
 It is necessary to use \fB\-\-update-drift\fR, with \fB\-\-set\fR or
 \fB\-\-systohc\fR, to force drift factor updates.
-
+See the \fB\-\-update\-drift\fR option below for details.
+.PP
 Since v2.26
 .B hwclock \-\-hctosys
 does a better job at setting the System Clock: it no longer simply copies
@@ -35,146 +53,228 @@ then sets the System Clock to the resulting value.)
 Therefore it is no longer necessary to run \fBhwclock --adjust\fR before
 doing \fBhwclock --hctosys\fR, and thus \fBhwclock\fR can be used very
 early on in the boot process when the root filesystem is still read-only.
-
+See the \fB\-\-hctosys\fR function below for information on inhibiting
+this new behavior.
+.
 .SH FUNCTIONS
-You need exactly one of the following options to tell
-.B hwclock
-what function to perform:
+The following functions are mutually exclusive, only one can be given at
+a time. If none are given the default is
+.BR \-\-show .
 .TP
 .B \-\-adjust
 Add or subtract time from the Hardware Clock to account for systematic
 drift since the last time the clock was set or adjusted.  See the
-discussion below, under \fBThe Adjust Function\fR.
+discussion below, under
+.BR "The Adjust Function" .
+.
 .TP
 .BR \-c , \ \-\-compare
 Periodically compare the Hardware Clock to the System Time and output
 the difference every 10 seconds.  This will also print the frequency
 offset and tick.
+.
 .TP
 .B \-\-getepoch
-Print the kernel's Hardware Clock epoch value to standard output.
-This is the number of years into AD to which a zero year value in the
+.TQ
+.B \-\-setepoch
+These functions are for Alpha machines only.
+.sp
+Read and set the kernel's Hardware Clock epoch value.
+Epoch is the number of years into AD to which a zero year value in the
 Hardware Clock refers.  For example, if you are using the convention
 that the year counter in your Hardware Clock contains the number of
 full years since 1952, then the kernel's Hardware Clock epoch value
 must be 1952.
 .sp
+The set function requires using the
+.B \%\-\-epoch
+option.
+.sp
 This epoch value is used whenever
-.B hwclock
+.B \%hwclock
 reads or sets the Hardware Clock.
+.
 .TP
-.BI \-\-predict
-Predict what the RTC will read at the time given by the
+.B \-\-predict
+Predict what the Hardware Clock will read in the future based upon the
+time given by the
 .B \-\-date
-option, based on the adjtime file.  This is useful for example if you
-need to set an RTC wakeup time to a distant future and want to account
-for the RTC drift.
+option and the information in
+.IR @ADJTIME_PATH@ .
+This is useful, for example, to account for drift when setting a
+Hardware Clock wakeup (aka alarm). See
+.BR \%rtcwake (8).
+.sp
+Do not use this function if the Hardware Clock is being modified by
+anything other than the current operating system's
+.B \%hwclock
+command, such as \%'11\ minute\ mode' or from dual-booting another OS.
+.
 .TP
 .BR \-r , \ \-\-show
+.TQ
+.B \-\-get
+.br
 Read the Hardware Clock and print the time on standard output.
 The time shown is always in local time, even if you keep your Hardware Clock
-in Coordinated Universal Time.  See the
-.B \-\-utc
+in UTC.  See the
+.B \%\-\-localtime
 option.
+.sp
 Showing the Hardware Clock time is the default when no function is specified.
-.TP
+.sp
+The
 .B \-\-get
-Like
-.B --show
-only with drift correction applied to the time read. This is useful when the
-Hardware Clock is not being periodically updated by something such as NTP's
-11 minute mode or when not using
-.BR --adjust .
+function also applies drift correction to the time read, based upon the
+information in
+.IR @ADJTIME_PATH@ .
+Do not use this function if the Hardware Clock is being modified by
+anything other than the current operating system's
+.B \%hwclock
+command, such as \%'11\ minute\ mode' or from dual-booting another OS.
+.
 .TP
 .BR \-s , \ \-\-hctosys
-Set the System Time from the Hardware Clock.  The time read from the Hardware
+Set the System Clock from the Hardware Clock.  The time read from the Hardware
 Clock is compensated to account for systematic drift before using it to set the
-System Clock.  See the discussion below, under \fBThe Adjust Function\fR.
+System Clock.  See the discussion below, under
+.BR "The Adjust Function" .
 .sp
-Also set the kernel's timezone value to the local timezone
-as indicated by the TZ environment variable and/or
-.IR /usr/share/zoneinfo ,
-as
-.BR tzset (3)
+The System Clock must be kept in the UTC timescale for date-time
+applications to work correctly in conjunction with the timezone configured
+for the system.  If the Hardware Clock is kept in local time then the time read
+from it must be shifted to the UTC timescale before using it to set the System
+Clock.  The
+.B \%\-\-hctosys
+function does this based upon the information in the
+.I @ADJTIME_PATH@
+file or the command line arguments
+.BR \%\-\-localtime " and " \-\-utc .
+Note: no daylight saving adjustment is made. See the discussion below under
+.BR "LOCAL vs UTC" .
+.sp
+The kernel also keeps a timezone value, the
+.B \%\-\-hctosys
+function sets it to the timezone configured for the system.  The system
+timezone is configured by the TZ environment variable or the
+.I \%/etc/localtime
+file, as
+.BR \%tzset (3)
 would interpret them.
 The obsolete tz_dsttime field of the kernel's timezone value is set
-to DST_NONE.  (For details on what this field used to mean, see
-.BR settimeofday (2).)
+to zero.  (For details on what this field used to mean, see
+.BR \%settimeofday (2).)
 .sp
-When used in a startup script, making it the first caller of
-.BR settimeofday (2)
-from boot, it will set the NTP 11 minute mode time scale via the
-.I persistent_clock_is_local
-kernel variable.  See the discussion below, under
+When used in a startup script, making the
+.B \%\-\-hctosys
+function the first caller of
+.BR \%settimeofday (2)
+from boot, it will set the NTP \%'11\ minute\ mode' timescale via the
+.I \%persistent_clock_is_local
+kernel variable.  If the Hardware Clock's timescale configuration is
+changed then a reboot is required to inform the kernel.  See the
+discussion below, under
 .BR "Automatic Hardware Clock Synchronization by the Kernel" .
 .sp
-This is a good option to use in one of the system startup scripts.
+This is a good function to use in one of the system startup scripts before the
+file systems are mounted read/write.
 .sp
-This option should never be used on a running system. Jumping system time
-will cause problems, such as, corrupted file system timestamps.
-Also, if NTP 11 minute mode is active then
-.B --hctosys
-will set the time incorrectly by
-including drift compensation. Drift compensation can be inhibited by using the
-.B --noadjfile
-option.
+This function should never be used on a running system. Jumping system time
+will cause problems, such as, corrupted filesystem timestamps.  Also, if
+something has changed the Hardware Clock, like NTP's \%'11\ minute\ mode', then
+.B \%\-\-hctosys
+will set the time incorrectly by including drift compensation.
+.sp
+Drift compensation can be inhibited by setting the drift factor in
+.I @ADJTIME_PATH@
+to zero.  This setting will be persistent as long as the
+.BR \%\-\-update\-drift " option is not used with " \%\-\-systohc
+at shutdown (or anywhere else).  Another way to inhibit this is by using the
+.BR \%\-\-noadjfile " option when calling the " \%\-\-hctosys
+function.  A third method is to delete the
+.IR @ADJTIME_PATH@ " file."
+.B Hwclock
+will then default to using the UTC timescale for the Hardware Clock.  If
+the Hardware Clock is ticking local time it will need to be defined in
+the file.  This can be done by calling
+.BR hwclock\ \-\-localtime\ \-\-adjust ;
+when the file is not present this command will not actually
+adjust the Clock, but it will create the file with local time
+configured, and a drift factor of zero.
+.sp
+A condition under which inhibiting
+.BR hwclock 's
+drift correction may be desired is when dual-booting multiple operating
+systems.  If while this instance of Linux is stopped, another OS changes
+the Hardware Clock's value, then when this instance is started again the
+drift correction applied will be incorrect.
+.sp
+.RB "For " hwclock 's
+drift correction to work properly it is imperative that nothing changes
+the Hardware Clock while its Linux instance is not running.
+.
 .TP
 .B \-\-set
 Set the Hardware Clock to the time given by the
-.B \-\-date
-option.
-.TP
-.B \-\-setepoch
-Set the kernel's Hardware Clock epoch value to the value specified by the
-.B \-\-epoch
-option.  See the
-.B \-\-getepoch
-option for details.
+.BR \-\-date
+option, and update the timestamps in
+.IR @ADJTIME_PATH@ .
+With the
+.B --update-drift
+option (re)calculate the drift factor.
+.
 .TP
 .B \-\-systz
-Set the kernel's timezone and reset the System Time based on the current timezone.
+This is an alternate to the
+.B \%\-\-hctosys
+function that does not read the Hardware Clock nor set the System Clock;
+consequently there is not any drift correction.  It is intended to be
+used in a startup script on systems with kernels above version 2.6 where
+you know the System Clock has been set from the Hardware Clock by the
+kernel during boot.
 .sp
-The system time is only reset on the first call after boot.
-.sp
-The local timezone is taken to be what is
-indicated by the TZ environment variable and/or
-.IR /usr/share/zoneinfo ,
-as
-.BR tzset (3)
-would interpret them.
-The obsolete tz_dsttime field of the kernel's timezone value is set
-to DST_NONE.  (For details on what this field used to mean, see
-.BR settimeofday (2).)
-.sp
-This is an alternate option to
-.B \-\-hctosys
-that does not read the hardware clock, and may be used in system startup
-scripts for recent 2.6 kernels where you know the System Time contains
-the Hardware Clock time.  If the Hardware Clock is already in UTC, it is
-not reset.
+It does the following things that are detailed above in the
+.BR \%\-\-hctosys " function:"
+.RS
+.IP \(bu 2
+Corrects the System Clock timescale to UTC as needed.  Only instead of
+accomplishing this by setting the System Clock,
+.B hwclock
+simply informs the kernel and it handles the change.
+.IP \(bu 2
+Sets the kernel's NTP \%'11\ minute\ mode' timescale.
+.IP \(bu 2
+Sets the kernel's timezone.
+.PP
+The first two are only available on the first call of
+.BR \%settimeofday (2)
+after boot.  Consequently this option only makes sense when used in a
+startup script.  If the Hardware Clocks timescale configuration is
+changed then a reboot would be required to inform the kernel.
+.RE
+.
 .TP
 .BR \-w , \ \-\-systohc
-Set the Hardware Clock to the current System Time.
+Set the Hardware Clock from the System Clock, and update the timestamps in
+.IR @ADJTIME_PATH@ .
+With the
+.B --update-drift
+option (re)calculate the drift factor.
+.
 .TP
 .BR \-V , \ \-\-version
 Display version information and exit.
+.
 .TP
 .BR \-h , \ \-\-help
 Display help text and exit.
-
+.
 .SH OPTIONS
-
+.
 .TP
 .BI \-\-adjfile= filename
-Override the default @ADJTIME_PATH@.
-
-.TP
-.B \-\-arc
-This option is equivalent to
-.B \-\-epoch=1980
-and is used to specify the most common epoch on Alphas
-with ARC console (but Ruffians have epoch 1900).
-
+.RI "Override the default " @ADJTIME_PATH@ " file path."
+.
 .TP
 .B \-\-badyear
 Indicate that the Hardware Clock is incapable of storing years outside
@@ -183,26 +283,26 @@ Award BIOSes made between 4/26/94 and 5/31/95) wherein they are unable
 to deal with years after 1999.  If one attempts to set the year-of-century
 value to something less than 94 (or 95 in some cases), the value that
 actually gets set is 94 (or 95).  Thus, if you have one of these machines,
-.B hwclock
+.B \%hwclock
 cannot set the year after 1999 and cannot use the value of the clock as
 the true time in the normal way.
 .sp
 To compensate for this (without your getting a BIOS update, which would
 definitely be preferable), always use
-.B \-\-badyear
+.B \%\-\-badyear
 if you have one of these machines.  When
-.B hwclock
+.B \%hwclock
 knows it's working with a brain-damaged clock, it ignores the year part of
 the Hardware Clock value and instead tries to guess the year based on the
 last calibrated date in the adjtime file, by assuming that date is
 within the past year.  For this to work, you had better do a
-.B hwclock \-\-set
+.B \%hwclock\ \-\-set
 or
-.B hwclock \-\-systohc
+.B \%hwclock\ \-\-systohc
 at least once a year!
 .sp
 Though
-.B hwclock
+.B \%hwclock
 ignores the year value when it reads the Hardware Clock, it sets the
 year value when it sets the clock.  It sets it to 1995, 1996, 1997, or
 1998, whichever one has the same position in the leap year cycle as
@@ -211,405 +311,447 @@ they belong.  Again, if you let the Hardware Clock run for more than a
 year without setting it, this scheme could be defeated and you could
 end up losing a day.
 .sp
-.B hwclock
+.B \%hwclock
 warns you that you probably need
-.B \-\-badyear
+.B \%\-\-badyear
 whenever it finds your Hardware Clock set to 1994 or 1995.
-
+.
 .TP
-.BI \-\-date= date_string
+.BI \%\-\-date= date_string
 You need this option if you specify the
 .B \-\-set
 or
-.B \-\-predict
+.B \%\-\-predict
 functions, otherwise it is ignored.
 It specifies the time to which to set the Hardware Clock, or the
 time for which to predict the Hardware Clock reading.
-The value of this option is an argument to the
-.BR date (1)
-program.
-For example:
-.sp
-.B "    hwclock" --set --date="2011-08-14 16:45:05"
-.sp
+The value of this option is used as an argument to the
+.BR date "(1) program's " \-\-date
+option.  For example:
+.RS
+.IP "" 4
+.BI "\%hwclock\ \-\-set\ \-\-date='" 2011-08-14\ 16:45:05 '
+.PP
 The argument must be in local time, even if you keep your Hardware Clock in
-Coordinated Universal time.  See the
-.B \-\-utc
-option.
-
+UTC.  See the
+.B \%\-\-localtime
+option.  The argument must not be a relative time like "+5 minutes", because
+.BR \%hwclock 's
+precision depends upon correlation between the argument's value and when
+the enter key is pressed.
+.RE
+.
 .TP
 .B \-\-debug
 Display a lot of information about what
-.B hwclock
-is doing internally.  Some of its function is complex and this output
+.B \%hwclock
+is doing internally.  Some of its functions are complex and this output
 can help you understand how the program works.
-
+.
 .TP
 .B \-\-directisa
-This option is meaningful only on an ISA machine or an Alpha (which implements
-enough of ISA to be, roughly speaking, an ISA machine for
-.BR hwclock 's
-purposes).  For other machines, it has no effect.  This option tells
-.B hwclock
+This option is meaningful for: ISA compatible machines including x86, and
+x86_64; and Alpha (which has a similar Hardware Clock interface).  For other
+machines, it has no effect.  This option tells
+.B \%hwclock
 to use explicit I/O instructions to access the Hardware Clock.
 Without this option,
-.B hwclock
-will try to use the /dev/rtc device (which it assumes to be driven by the
-RTC device driver).  If it is unable to open the device (for reading), it will
-use the explicit I/O instructions anyway.
-
-.TP
-.BI \-\-epoch= year
-Specifies the year which is the beginning of the Hardware Clock's
-epoch, that is the number of years into AD to which a zero value in the
-Hardware Clock's year counter refers.  It is used together with
-the \fB\-\-setepoch\fR option to set the kernel's idea of the epoch of the
-Hardware Clock, or otherwise to specify the epoch for use with
-direct ISA access.
-.sp
-For example, on a Digital Unix machine:
-.sp
-.B "    hwclock" --setepoch --epoch=1952
-
+.B \%hwclock
+will try to use the rtc device, which it assumes to be driven by the RTC
+device driver.  If it is unable to open the device for reading, it will
+use the explicit I/O instructions anyway.  Direct hardware access from
+userspace should only be used for testing, troubleshooting, and as a
+last resort when all other methods fail.  See the
+.BR \-\-rtc " option."
+.
 .TP
-.BR \-f , \ \-\-rtc=\fIfilename\fB
-Overrides the default /dev file name, which is
-.IR /dev/rtc
-on many platforms but may be
-.IR /dev/rtc0 ,
-.IR /dev/rtc1 ,
-and so on.
-
-.TP
-.B \-\-funky\-toy
-.TP
-.B \-\-jensen
-These two options specify what kind of Alpha machine you have.  They
-are invalid if you don't have an Alpha and are usually unnecessary
-if you do, because
-.B hwclock
-should be able to determine by itself what it's
-running on, at least when
-.I /proc
-is mounted.
-(If you find you need one of these options to make
-.B hwclock
-work, contact the maintainer to see if the program can be improved
-to detect your system automatically.  Output of `hwclock --debug'
-and `cat /proc/cpuinfo' may be of interest.)
-.sp
-Option
-.B \-\-jensen
-means you are running on a Jensen model.  And
-.B \-\-funky\-toy
-means that on your machine one has to use the UF bit instead
-of the UIP bit in the Hardware Clock to detect a time transition.  "Toy"
-in the option name refers to the Time Of Year facility of the machine.
-
+.BR \-f , \ \-\-rtc=\fIfilename\fR
+.RB "Override " \%hwclock 's
+default rtc device file name.  Otherwise it will
+use the first one found in this order:
+.in +4
+.br
+.I /dev/rtc
+.br
+.I /dev/rtc0
+.br
+.I /dev/misc/rtc
+.br
+.in
+.RB "For " IA-64:
+.in +4
+.br
+.I /dev/efirtc
+.br
+.I /dev/misc/efirtc
+.in
+.
 .TP
 .B \-\-localtime
-Indicate that the Hardware Clock is kept in local time.
+.TQ
+.BR \-u ", " \-\-utc
+Indicate which timescale the Hardware Clock is set to.
 .sp
-It is your choice whether to keep
-your clock in UTC or in local time, but nothing in the clock itself
-says which alternative
-you've chosen.  So with \fB\-\-localtime\fR or \fB\-\-utc\fR
-you give this information to
-.BR hwclock .
-If you specify the wrong one (or specify neither and take a wrong default),
-both setting and querying the Hardware Clock will be messed up.
+The Hardware Clock may be configured to use either the UTC or the local
+timescale, but nothing in the clock itself says which alternative is
+being used.  The
+.BR \%\-\-localtime " or " \-\-utc
+options give this information to the
+.B \%hwclock
+command.  If you specify the wrong one (or specify neither and take a
+wrong default), both setting and reading the Hardware Clock will be
+incorrect.
 .sp
 If you specify neither
-.B \-\-utc
-nor
-.BR \-\-localtime ,
-the default is whichever was specified the last time
-.B hwclock
-was used to set the clock (i.e.
-.B hwclock
-was successfully run with the
-.BR \-\-set ,
-.BR \-\-systohc ,
-or
-.B \-\-adjust
-options), as recorded in the adjtime file.  If the adjtime file doesn't
-exist, the default is UTC time.
-
+.BR \-\-utc " nor " \%\-\-localtime
+then the one last given with a set function
+.RB ( \-\-set ", " \%\-\-systohc ", or " \%\-\-adjust ),
+as recorded in
+.IR @ADJTIME_PATH@ ,
+will be used.  If the adjtime file doesn't exist, the default is UTC.
+.sp
+Note: daylight saving time changes may be inconsistent when the
+Hardware Clock is kept in local time. See the discussion below under
+.BR "LOCAL vs UTC" .
+.
 .TP
 .B \-\-noadjfile
 Disable the facilities provided by
 .IR @ADJTIME_PATH@ .
-.B hwclock
+.B \%hwclock
 will not read nor write to that file with this option.  Either
-.B \-\-utc
-or
-.B \-\-localtime
+.BR \-\-utc " or " \%\-\-localtime
 must be specified when using this option.
-
-.TP
-.B \-\-srm
-This option is equivalent to
-.B \-\-epoch=1900
-and is used to specify the most common epoch on Alphas
-with SRM console.
-
+.
 .TP
 .B \-\-test
-Do everything except actually updating the Hardware Clock or anything
-else.  This is useful, especially in conjunction with
-.BR \-\-debug ,
+Do not actually change anything on the system, i.e., the Clocks or
+adjtime file.  This is useful, especially in conjunction with
+.BR \%\-\-debug ,
 in learning about the internal operations of hwclock.
-
+.
 .TP
-.B \-\-update-drift
+.B \-\-update\-drift
 Update the Hardware Clock's drift factor in
 .IR @ADJTIME_PATH@ .
 It is used with
-.BR --set\  or \ --systohc ,
+.BR \-\-set " or " \%\-\-systohc ,
 otherwise it is ignored.
-See the discussion below, under \fBThe Adjust Function\fR.
-
+.sp
+A minimum four hour period between settings is required.  This is to
+avoid invalid calculations.  The longer the period, the more precise the
+resulting drift factor will be.
+.sp
+This option was added in v2.26, because
+it is typical for systems to call
+.B \%hwclock\ \-\-systohc
+at shutdown; with the old behaviour this would automatically
+(re)calculate the drift factor which caused several problems:
+.RS
+.IP \(bu 2
+When using ntpd with an \%'11\ minute\ mode' kernel the drift factor
+would be clobbered to near zero.
+.IP \(bu 2
+It would not allow the use of 'cold' drift correction.  With most
+configurations using 'cold' drift will yield favorable results.  Cold,
+means when the machine is turned off which can have a significant impact
+on the drift factor.
+.IP \(bu 2
+(Re)calculating drift factor on every shutdown delivers suboptimal
+results.  For example, if ephemeral conditions cause the machine to be
+abnormally hot the drift factor calculation would be out of range.
+.PP
+.RB "Having " \%hwclock
+calculate the drift factor is a good starting point, but for optimal
+results it will likely need to be adjusted by directly editing the
+.I @ADJTIME_PATH@
+file.  For most configurations once a machine's optimal drift factor is
+crafted it should not need to be changed.  Therefore, the old behavior to
+automatically (re)calculate drift was changed and now requires this
+option to be used.  See the discussion below, under
+.BR "The Adjust Function" .
+.RE
+.
+.SH OPTIONS FOR ALPHA MACHINES ONLY
+.
+.TP
+.B \-\-arc
+This option is equivalent to
+.BI \%\-\-epoch= 1980
+and is used to specify the most common epoch on Alphas
+with ARC console (but Ruffians have an epoch of 1900).
+.
+.TP
+.BI \-\-epoch= year
+Specifies the year which is the beginning of the Hardware Clock's epoch,
+that is the number of years into AD to which a zero value in the
+Hardware Clock's year counter refers.  It is used together with the
+.B \%\-\-setepoch
+option to set the kernel's idea of the epoch of the Hardware Clock, or
+otherwise to specify the epoch for use with direct ISA access.
+.sp
+For example, on a Digital Unix machine:
+.RS
+.IP "" 4
+.BI hwclock\ \-\-setepoch\ \-\-epoch= 1952
+.RE
+.
 .TP
-.BR \-u , \ \-\-utc
-Indicate that the Hardware Clock is kept in Coordinated Universal Time.
-See the discussion under \fB\-\-localtime\fR.
-
-
+.B \-\-funky\-toy
+.TQ
+.B \-\-jensen
+These two options specify what kind of Alpha machine you have.  They
+are invalid if you do not have an Alpha and are usually unnecessary
+if you do;
+.B \%hwclock
+should be able to determine what it is running on when
+.I \%/proc
+is mounted.
+.sp
+.RB "The " \%\-\-jensen
+option is used for Jensen models;
+.B \%\-\-funky\-toy
+means that the machine requires the UF bit instead of the UIP bit in
+the Hardware Clock to detect a time transition.  "Toy" in the option
+name refers to the Time Of Year facility of the machine.
+.
+.TP
+.B \-\-srm
+This option is equivalent to
+.BI \%\-\-epoch= 1900
+and is used to specify the most common epoch on Alphas
+with SRM console.
+.
 .SH NOTES
-
+.
 .SS Clocks in a Linux System
 .PP
-There are two main clocks in a Linux system:
+There are two types of date-time clocks:
 .PP
 .B The Hardware Clock:
-This is a clock that runs independently of any control program running
-in the CPU and even when the machine is powered off.
+This clock is an independent hardware device, with its own power domain
+(battery, capacitor, etc), that operates when the machine is powered off,
+or even unplugged.
 .PP
-On an ISA system, this clock is specified as part of the ISA standard.
-The control program can read or set this clock to a whole second, but
-the control program can also detect the edges of the 1 second clock
-ticks, so the clock actually has virtually infinite precision.
+On an ISA compatible system, this clock is specified as part of the ISA
+standard.  A control program can read or set this clock only to a whole
+second, but it can also detect the edges of the 1 second clock ticks, so
+the clock actually has virtually infinite precision.
 .PP
 This clock is commonly called the hardware clock, the real time clock,
 the RTC, the BIOS clock, and the CMOS clock.  Hardware Clock, in its
 capitalized form, was coined for use by
-.B hwclock
-because all of the other names are inappropriate to the point of being
-misleading.
+.BR \%hwclock .
+The Linux kernel also refers to it as the persistent clock.
 .PP
-So for example, some non-ISA systems have a few real time clocks with
+Some non-ISA systems have a few real time clocks with
 only one of them having its own power domain.
 A very low power external I2C or SPI clock chip might be used with a
 backup battery as the hardware clock to initialize a more functional
 integrated real-time clock which is used for most other purposes.
 .PP
-.B The System Time:
-This is the time kept by a clock inside the Linux kernel and driven by
+.B The System Clock:
+This clock is part of the Linux kernel and is driven by
 a timer interrupt.  (On an ISA machine, the timer interrupt is part of
 the ISA standard.)  It has meaning only while Linux is running on the
 machine.  The System Time is the number of seconds since 00:00:00
 January 1, 1970 UTC (or more succinctly, the number of seconds since
-1969).  The System Time is not an integer, though.  It has virtually
+1969 UTC).  The System Time is not an integer, though.  It has virtually
 infinite precision.
 .PP
 The System Time is the time that matters.  The Hardware Clock's basic
-purpose in a Linux system is to keep time when Linux is not running.  You
-initialize the System Time to the time from the Hardware Clock when Linux
-starts up, and then never use the Hardware Clock again.  Note that in DOS,
-for which ISA was designed, the Hardware Clock is the only real time clock.
+purpose is to keep time when Linux is not running so that the System
+Clock can be initialized from it at boot.  Note that in DOS, for which
+ISA was designed, the Hardware Clock is the only real time clock.
 .PP
 It is important that the System Time not have any discontinuities such as
 would happen if you used the
-.BR date (1L)
+.BR \%date (1)
 program to set it while the system is running.  You can, however, do whatever
 you want to the Hardware Clock while the system is running, and the next
 time Linux starts up, it will do so with the adjusted time from the Hardware
-Clock.
+Clock.  Note: currently this is not possible on most systems because
+.B \%hwclock\ \-\-systohc
+is called at shutdown.
 .PP
-A Linux kernel maintains a concept of a local timezone for the system.
+The Linux kernel's timezone is set by
+.BR hwclock .
 But don't be misled -- almost nobody cares what timezone the kernel
 thinks it is in.  Instead, programs that care about the timezone
 (perhaps because they want to display a local time for you) almost
 always use a more traditional method of determining the timezone: They
-use the TZ environment variable and/or the
-.I /usr/share/zoneinfo
-directory, as explained in the man page for
-.BR tzset (3).
+use the TZ environment variable or the
+.I \%/etc/localtime
+file, as explained in the man page for
+.BR \%tzset (3).
 However, some programs and fringe parts of the Linux kernel such as filesystems
-use the kernel timezone value.  An example is the vfat filesystem.  If the
+use the kernel's timezone value.  An example is the vfat filesystem.  If the
 kernel timezone value is wrong, the vfat filesystem will report and set the
-wrong timestamps on files. Another example is the kernel's NTP 11 minute mode.
+wrong timestamps on files. Another example is the kernel's NTP \%'11\ minute\ mode.'
 If the kernel's timezone value and/or the
-.I persistent_clock_is_local
-variable are wrong, then the Hardware Clock will be set incorrectly by 11 minute
-mode.  See the discussion below, under
+.I \%persistent_clock_is_local
+variable are wrong, then the Hardware Clock will be set incorrectly
+by \%'11\ minute\ mode.'  See the discussion below, under
 .BR "Automatic Hardware Clock Synchronization by the Kernel" .
 .PP
-.B hwclock
-sets the kernel timezone to the value indicated by TZ and/or
-.I /usr/share/zoneinfo
-when you set the System Time using the
-.B \-\-hctosys
-option.
+.B \%hwclock
+sets the kernel's timezone to the value indicated by TZ or
+.IR \%/etc/localtime " with the"
+.BR \%\-\-hctosys " or " \%\-\-systz " functions."
 .PP
-The timezone value actually consists of two parts: 1) a field
+The kernel's timezone value actually consists of two parts: 1) a field
 tz_minuteswest indicating how many minutes local time (not adjusted
 for DST) lags behind UTC, and 2) a field tz_dsttime indicating
 the type of Daylight Savings Time (DST) convention that is in effect
 in the locality at the present time.
 This second field is not used under Linux and is always zero.
-(See also
-.BR settimeofday (2).)
-
+See also
+.BR \%settimeofday (2).
+.
 .SS User access and setuid
 .PP
 Sometimes, you need to install
-.B hwclock
+.B \%hwclock
 setuid root.  If you want users other than the superuser to be able to
 display the clock value using the direct ISA I/O method, install it setuid
-root.  If you have the /dev/rtc interface on your system or are on a non-ISA
-system, there's probably no need for users to use the direct ISA I/O method,
-so don't bother.
+root.  If you have the rtc device interface on your system, or are on a non-ISA
+compatible system, there is probably no need for users to have the direct
+ISA I/O method, so do not bother.  See the
+.BR \-\-rtc " option."
 .PP
 In any case, hwclock will not allow you to set anything unless you have the
 superuser real uid.  (This restriction is not necessary if you haven't
 installed setuid root, but it's there for now.)
-
-.SS How hwclock accesses the Hardware Clock
+.
+.SS Hardware Clock Access Methods
 .PP
-.B hwclock
+.B \%hwclock
 uses many different ways to get and set Hardware Clock values.
-The most normal way is to do I/O to the device special file /dev/rtc,
+The most normal way is to do I/O to the rtc device special file,
 which is presumed to be driven by the rtc device driver.  However,
-this method is not always available.  For one thing, the rtc driver is
-a relatively recent addition to Linux.  Older systems don't have it.
+this method is not always available as older systems do not have it.
 Also, though there are versions of the rtc driver that work on DEC
 Alphas, there appear to be plenty of Alphas on which the rtc driver
 does not work (a common symptom is hwclock hanging).
-Moreover, recent Linux systems have more generic support for RTCs,
-even systems that have more than one, so you might need to override
-the default by specifying
-.I /dev/rtc0
-or
-.I /dev/rtc1
-instead.
+Moreover, Linux systems using the rtc framework with udev, are capable
+of supporting multiple Hardware Clocks.  This may bring about the need
+to override the default rtc device by specifying one with the
+.BR \-\-rtc " option."
+.
 .PP
 On older systems, the method of accessing the Hardware Clock depends on
 the system hardware.
 .PP
-On an ISA system,
-.B hwclock
+On an ISA compatible system,
+.B \%hwclock
 can directly access the "CMOS memory" registers that
 constitute the clock, by doing I/O to Ports 0x70 and 0x71.  It does
 this with actual I/O instructions and consequently can only do it if
 running with superuser effective userid.  (In the case of a Jensen
 Alpha, there is no way for
-.B hwclock
+.B \%hwclock
 to execute those I/O instructions, and so it uses instead the
-/dev/port device special file, which provides almost as low-level an
+\%/dev/port device special file, which provides almost as low-level an
 interface to the I/O subsystem.)
 .PP
 This is a really poor method of accessing the clock, for all the
 reasons that userspace programs are generally not supposed to do
-direct I/O and disable interrupts.  \fBhwclock\fR provides it because it is
-the only method available on ISA and Alpha systems which don't have
-working rtc device drivers available.
+direct I/O and disable interrupts.
+.B \%hwclock
+provides it because it is the only method available on ISA compatible
+and Alpha systems which do not have working rtc device drivers available.
 .PP
 On an m68k system,
-.B hwclock
-can access the clock via the console driver, via the device special
-file /dev/tty1.
+.B \%hwclock
+can access the clock with the console driver, via the device special file
+.IR \%/dev/tty1 .
 .PP
-.B hwclock
-tries to use /dev/rtc.  If it is compiled for a kernel that doesn't have
-that function or it is unable to open /dev/rtc
-(or the alternative special file you've defined on the command line)
-.B hwclock
-will fall back to another method, if available.  On an ISA or Alpha
-machine, you can force
-.B hwclock
-to use the direct manipulation of the CMOS registers without even trying
-.I /dev/rtc
-by specifying the
-.B \-\-directisa
-option.
-
+.B \%hwclock
+tries to use the rtc device interface first.  If it is compiled for a
+kernel that does not have that function or it is unable to open it (or
+the alternative special file defined on the command line with
+.BR \-\-rtc ") " \%hwclock
+will fall back to another method, if available.  On an ISA compatible or
+Alpha machine,
+.B \%hwclock
+can be forced to use the direct manipulation of the CMOS registers
+without even trying the rtc device interface by specifying the
+.BR \%\-\-directisa " option."
+.
 .SS The Adjust Function
 .PP
 The Hardware Clock is usually not very accurate.  However, much of its
 inaccuracy is completely predictable - it gains or loses the same amount
 of time every day.  This is called systematic drift.
-.BR hwclock 's
-.I \-\-adjust
+.BR \%hwclock "'s " \%\-\-adjust
 function lets you apply systematic drift corrections to the
 Hardware Clock.
 .PP
 It works like this:
-.B hwclock
-keeps a file,
+.BR \%hwclock " keeps a file,"
 .IR @ADJTIME_PATH@ ,
 that keeps some historical information.  This is called the adjtime file.
 .PP
 Suppose you start with no adjtime file.  You issue a
-.B hwclock \-\-set
+.B \%hwclock\ \-\-set
 command to set the Hardware Clock to the true current time.
-.B hwclock
+.B \%hwclock
 creates the adjtime file and records in it the current time as the
 last time the clock was calibrated.
 Five days later, the clock has gained 10 seconds, so you issue a
-.B hwclock \-\-set \-\-update-drift
+.B \%hwclock\ \-\-set\ \-\-update\-drift
 command to set it back 10 seconds.
-.B hwclock
+.B \%hwclock
 updates the adjtime file to show the current time as the last time the
 clock was calibrated, and records 2 seconds per day as the systematic
 drift rate.  24 hours go by, and then you issue a
-.B hwclock \-\-adjust
+.B \%hwclock\ \-\-adjust
 command.
-.B hwclock
+.B \%hwclock
 consults the adjtime file and sees that the clock gains 2 seconds per
 day when left alone and that it has been left alone for exactly one
 day.  So it subtracts 2 seconds from the Hardware Clock.  It then
 records the current time as the last time the clock was adjusted.
 Another 24 hours go by and you issue another
-.BR "hwclock \-\-adjust" .
-.B hwclock
+.BR \%hwclock\ \-\-adjust .
+.B \%hwclock
 does the same thing: subtracts 2 seconds and updates the adjtime file
 with the current time as the last time the clock was adjusted.
 .PP
 When you use the
-.B \-\-update-drift
-option with
-.BR \-\-set\  or \ \-\-systohc ,
-the systematic drift rate is (re)calculated based on how long it has been
-since the last calibration, how long it has been since the last
-adjustment, what drift rate was assumed in any intervening
-adjustments, and the amount by which the clock is presently off.  This updated
-drift factor is then saved in
+.BR \%\-\-update\-drift " option with " \-\-set " or " \%\-\-systohc ,
+the systematic drift rate is (re)calculated by comparing the fully drift
+corrected current Hardware Clock time with the new set time, from that
+it derives the 24 hour drift rate based on the last calibrated timestamp
+from the adjtime file.  This updated drift factor is then saved in
 .IR @ADJTIME_PATH@ .
 .PP
 A small amount of error creeps in when
 the Hardware Clock is set, so
-.B \-\-adjust
+.B \%\-\-adjust
 refrains from making any adjustment that is less
 than 1 second.  Later on, when you request an adjustment again, the accumulated
 drift will be more than 1 second and
-.B \-\-adjust
+.B \%\-\-adjust
 will make the adjustment including any fractional amount.
 .PP
-.B hwclock \-\-hctosys
+.B \%hwclock\ \-\-hctosys
 also uses the adjtime file data to compensate the value read from the Hardware
-Clock before using it to set the System Time.  It does not share the 1 second
-limitation of \fB--adjust\fR, and will correct sub-second drift values immediately.
-It does not change the Hardware Clock time or the adjtime file.  This may
-eliminate the need to use \fB--adjust\fR, unless something else on the system needs
-the Hardware Clock to be compensated. The drift compensation can be inhibited
-by using the
-.B --noadjfile
-option.
-.PP
-The adjtime file, while named for its historical purpose of controlling
-adjustments only, actually contains other information for use by hwclock
-in remembering information from one invocation to the next.
+Clock before using it to set the System Clock.  It does not share the 1 second
+limitation of
+.BR \%\-\-adjust ,
+and will correct sub-second drift values immediately.  It does not
+change the Hardware Clock time nor the adjtime file.  This may eliminate
+the need to use
+.BR \%\-\-adjust ,
+unless something else on the system needs the Hardware Clock to be
+compensated.
+.
+.SS The Adjtime File
+While named for its historical purpose of controlling adjustments only,
+it actually contains other information used by
+.B hwclock
+from one invocation to the next.
 .PP
 The format of the adjtime file is, in ASCII:
 .PP
@@ -617,7 +759,7 @@ Line 1: Three numbers, separated by blanks: 1) the systematic drift rate
 in seconds per day, floating point decimal; 2) the resulting number of
 seconds since 1969 UTC of most recent adjustment or calibration,
 decimal integer; 3) zero (for compatibility with
-.BR clock (8))
+.BR \%clock (8))
 as a decimal integer.
 .PP
 Line 2: One number: the resulting number of seconds since 1969 UTC of most
@@ -629,98 +771,326 @@ contain a valid time).  This is a decimal integer.
 Line 3: "UTC" or "LOCAL".  Tells whether the Hardware Clock is set to
 Coordinated Universal Time or local time.  You can always override this
 value with options on the
-.B hwclock
+.B \%hwclock
 command line.
 .PP
 You can use an adjtime file that was previously used with the
-.BR clock (8)
-program with
-.BR hwclock .
-
+.BR \%clock "(8) program with " \%hwclock .
+.
 .SS Automatic Hardware Clock Synchronization by the Kernel
 .PP
 You should be aware of another way that the Hardware Clock is kept
 synchronized in some systems.  The Linux kernel has a mode wherein it
 copies the System Time to the Hardware Clock every 11 minutes.
 This is a good mode to use when you are using something sophisticated
-like ntp to keep your System Time synchronized. (ntp is a way to keep
+like NTP to keep your System Clock synchronized. (NTP is a way to keep
 your System Time synchronized either to a time server somewhere on the
 network or to a radio clock hooked up to your system.  See RFC 1305.)
 .PP
-This mode (we'll call it "11 minute mode") is off until something
-turns it on.  The ntp daemon ntpd is one thing that turns it on.  You
+This mode (we'll call it \%'11\ minute\ mode') is off until something
+turns it on.  The NTP daemon ntpd is one thing that turns it on.  You
 can turn it off by running anything, including
-.BR "hwclock \-\-hctosys" ,
-that sets the System Time the old fashioned way.  However, if the ntp daemon is
+.BR \%hwclock\ \-\-hctosys ,
+that sets the System Clock the old fashioned way.  However, if the NTP daemon is
 still running, it will turn 11 minute mode back on again the next time it
 synchronizes the System Clock.
 .PP
-If your system runs with 11 minute mode on, it may need
-.B hwclock \-\-hctosys
+If your system runs with \%'11\ minute\ mode' on, it may need to use either
+.BR \%\-\-hctosys " or " \%\-\-systz
 in a startup script, especially if the Hardware Clock is configured to to use
-the local timescale.
-
-The first user space command to set the System Clock informs the
+the local timescale. Unless the kernel is informed of what timescale the
+Hardware Clock is using, it may clobber it with the wrong one. The kernel
+uses UTC by default.
+.PP
+The first userspace command to set the System Clock informs the
 kernel what timescale the Hardware Clock is using.  This happens via the
-.I persistent_clock_is_local
+.I \%persistent_clock_is_local
 kernel variable.  If
-.B hwclock \-\-hctosys
+.BR \%\-\-hctosys " or " \%\-\-systz
 is the first, it will set this variable according to the adjtime file or the
 appropriate command-line argument.  Note that when using this capability and the
 Hardware Clock timescale configuration is changed, then a reboot is required to
 notify the kernel.
-
-Don't use
-.B hwclock \-\-adjust
-with 11 minute mode.  You'll just make a mess.
-
+.PP
+.B \%hwclock\ \-\-adjust
+should not be used with NTP \%'11\ minute\ mode.'
+.
 .SS ISA Hardware Clock Century value
 .PP
 There is some sort of standard that defines CMOS memory Byte 50 on an ISA
 machine as an indicator of what century it is.
-.B hwclock
+.B \%hwclock
 does not use or set that byte because there are some machines that
 don't define the byte that way, and it really isn't necessary anyway,
 since the year-of-century does a good job of implying which century it
 is.
 .PP
 If you have a bona fide use for a CMOS century byte, contact the
-.B hwclock
+.B \%hwclock
 maintainer; an option may be appropriate.
 .PP
 Note that this section is only relevant when you are using the "direct
 ISA" method of accessing the Hardware Clock.
 ACPI provides a standard way to access century values, when they
 are supported by the hardware.
-
+.
+.SH DATE-TIME CONFIGURATION
+.in +4
+.SS Keeping Time without External Synchronization
+.in
+.PP
+This discussion is based on the following conditions:
+.IP \(bu 2
+Nothing is running that alters the date-time clocks, e.g.,
+.BR \%ntpd "(1), cron jobs, et al."
+.IP \(bu 2
+The system timezone is configured for the correct local time.  See below
+.BR "POSIX vs 'RIGHT'" .
+.IP \(bu 2
+Early in startup the following are called in this order:
+.br
+.BI \%adjtimex\ \-\-tick \ <value>\  \-\-frequency \ <value>
+.br
+.B \%hwclock\ \-\-hctosys
+.IP \(bu 2
+During shutdown the following is called:
+.br
+.B \%hwclock\ \-\-systohc
+.PP
+Whether maintaining precision time with
+.BR \%ntpd (1)
+or not, it makes sense to configure the system to keep reasonably good
+date-time on its own.
+.PP
+The first step in making that happen is having a clear understanding of
+the big picture.  There are two completely separate hardware devices
+running at their own speed and drifting away from the 'correct' time at
+their own rates.  The methods and software for drift correction are
+different for each of them.  However, most systems are configured to
+exchange values between these two clocks at startup and shutdown.  Now
+the individual device's time keeping errors are transfered back and
+forth between each other.  Attempt to configure drift correction for only
+one of them, and the other's drift will be overlaid upon it.  If the big
+picture is not kept in mind, confusion will soon ensue.
+.PP
+This problem can be avoided when configuring drift correction for the
+System Clock by simply not shutting down the machine.  This, plus the
+fact that all of
+.BR \%hwclock 's
+precision (including calculating drift factors) depends upon the System
+Clock's rate being correct, means that configuration of the System Clock
+should be done first.
+.PP
+The System Clock drift is corrected with the
+.BR \%adjtimex "(8) command's " \-\-tick " and " \%\-\-frequency
+options.  These two work together, tick is the course adjustment and
+frequency is the fine adjustment.
+.PP
+Some Linux distributions attempt to automatically calculate the System
+Clock drift with
+.BR \%adjtimex 's
+compare operation.  Trying to correct one
+drifting clock by using another drifting clock as a reference is akin to
+a dog trying to catch its own tail.  Success may happen eventually, but
+great effort and frustration will likely precede it.  This automation may
+yield an improvement over no configuration, but expecting optimum
+results would be in error.  A better choice for manual configuration
+would be
+.BR \%adjtimex 's " \-\-log " options.
+.PP
+It may be more effective to simply track the System Clock drift with
+.BR \%ntpdate\ \-q " , or " \%date\ \-Ins
+and a precision timepiece, and then calculate the correction manually.
+.PP
+After setting the tick and frequency values, continue to test and refine the
+adjustments until the System Clock keeps good time.  See
+.BR \%adjtimex (8)
+for more information and the example demonstrating manual drift
+calculations.
+.PP
+Once the System Clock is ticking smoothly, move on to the Hardware Clock.
+.PP
+As a rule, cold drift will work best for most use cases.  This should be
+true even for 24/7 machines whose normal downtime consists of a reboot.
+In that case the drift factor value makes little difference, but on the
+rare occasion that the machine is shutdown for an extended period then
+cold drift should yield better results.
+.PP
+.B Steps to calculate cold drift:
+.IP 1 2
+.RB "Confirm that " ntpd "(1) will not be launched at startup."
+.IP 2 2
+.RI The " System Clock " "time must be correct at shutdown!"
+.IP 3 2
+Shutdown the system.
+.IP 4 2
+Let an extended period pass without changing the Hardware Clock.
+.IP 5 2
+Start the system.
+.IP 6 2
+.RB "Immediately use " hwclock " to set the correct time with the"
+.BR \%\-\-update\-drift " option."
+.PP
+Note: if step six uses
+.RB \%\-\-systohc ,
+then the System Clock must be set correctly (step 6a) just before doing so.
+.PP
+.RB "Having " hwclock
+calculate the drift factor is a good starting point, but for optimal
+results it will likely need to be adjusted by directly editing the
+.I @ADJTIME_PATH@
+file.  Continue to test and refine the drift factor until the Hardware
+Clock is corrected properly at startup.  To check this, first make sure
+that the System Time is correct before shutdown and then use
+.BR \%ntpdate\ \-q ", or " \%date\ \-Ins
+and a precision timepiece, immediately after startup.
+.PP
+Both clocks typically use a quartz crystal oscillator.  Crystals are
+used for reference oscillators in electronics because by most measures
+they produce a very clean and stable sine wave.  Their greatest
+shortcoming is that they have a Positive Temperature Coefficient;
+meaning that their frequency increases as the temperature increases and
+vise versa. Therefore, both the Hardware and System Clock's drift rate
+changes with intrinsic and extrinsic machine temperatures.  These
+characteristics will vary by machine depending upon its design.
+.PP
+Drift correction strategies are many, but as a general guide the goal
+would be to find a longterm average.  A year long average to take into
+account seasonal ambient temperature shifts may be a good target period.
+So perhaps the date-time advances a bit in the summer and declines a bit
+in the winter, but at the end of a year it balances to zero.
+.PP
+If this is beginning to sound futile, it is not.  Left on its own a
+machine can lose 3 seconds per day or more.  Accumulated drift over a
+year may easily exceed half an hour.  Using carefully crafted drift
+corrections can make a significant improvement in a machine's ability to
+keep reasonably good date-time.
+.
+.SS LOCAL vs UTC
+Keeping the Hardware Clock in a local timescale causes inconsistent
+daylight saving time results:
+.IP \(bu 2
+If Linux is running during a daylight saving time change, the time
+written to the Hardware Clock will be adjusted for the change.
+.IP \(bu 2
+If Linux is NOT running during a daylight saving time change, the time
+read from the Hardware Clock will NOT be adjusted for the change.
+.PP
+The Hardware Clock on an ISA compatible system keeps only a date and time,
+it has no concept of timezone nor daylight saving. Therefore, when
+.B hwclock
+is told that it is in local time, it assumes it is in the 'correct'
+local time and makes no adjustments to the time read from it.
+.PP
+Linux handles daylight saving time changes transparently only when the
+Hardware Clock is kept in the UTC timescale. Doing so is made easy for
+system administrators as
+.B \%hwclock
+uses local time for its output and as the argument to the
+.BR \%\-\-date " option."
+.PP
+POSIX systems, like Linux, are designed to have the System Clock operate
+in the UTC timescale. The Hardware Clock's purpose is to initialize the
+System Clock, so also keeping it in UTC makes sense.
+.PP
+Linux does, however, attempt to accommodate the Hardware Clock being in
+the local timescale. This is primarily for dual-booting with older
+versions of MS Windows. From Windows 7 on, the RealTimeIsUniversal
+registry key is supposed to be working properly so that its Hardware
+Clock can be kept in UTC.
+.
+.SS POSIX vs 'RIGHT'
+A discussion on date-time configuration would be incomplete without
+addressing timezones, this is mostly well covered by
+.BR tzset (3).
+One area that seems to have no documentation is the 'right'
+directory of the IANA Time Zone Database, aka tz, aka zoneinfo.
+.PP
+There are two separate databases in the zoneinfo system, posix
+and 'right'. 'Right' (now named leaps) includes leap seconds and posix
+does not. To use the 'right' database the System Clock must be kept in
+\%UTC\ +\ leap_seconds, i.e., \%TAI\ \-\ 10. This allows calculating the
+exact number of seconds between two dates that cross a leap second
+epoch. The System Clock is then converted to the correct civil time,
+including UTC, by using the 'right' timezone files which subtract the
+leap seconds. Note: this configuration is considered experimental and is
+known to have issues.
+.PP
+To configure a system to use a particular database all of the files
+located in its directory must be copied to the root of
+.IR \%/usr/share/zoneinfo .
+Files are never used directly from the posix or 'right' subdirectories, e.g.,
+.RI \%TZ=' right/Europe/Dublin '.
+This habit was becoming so common that the upstream zoneinfo project
+restructured the system's file tree by moving the posix and 'right'
+subdirectories out of the zoneinfo directory and into sibling directories:
+.br
+.in +2
+.I /usr/share/zoneinfo
+.br
+.I /usr/share/posix
+.br
+.I /usr/share/leaps
+.PP
+Unfortunately, some Linux distributions are changing it back to the old
+tree structure in their packages. So the problem of system
+administrators reaching into the 'right' subdirectory persists. This
+causes the system timezone to be configured to include leap seconds
+while the zoneinfo database is still configured to exclude them. Then
+when an application such as a World Clock needs the South_Pole timezone
+file; or an email MTA, or
+.B hwclock
+needs the UTC timezone file; they fetch it from the root of
+.I \%/usr/share/zoneinfo
+, because that is what they are supposed to do. Those files exclude leap
+seconds, but the System Clock now includes them, causing an incorrect
+time conversion.
+.PP
+Attempting to mix and match files from these separate databases will not
+work, because they each require the System Clock to use a different
+timescale. The zoneinfo database must be configured to use either posix
+or 'right', as described above.
+.
 .SH "ENVIRONMENT VARIABLES"
 .I TZ
-
+.
 .SH FILES
+.br
 .I @ADJTIME_PATH@
-.I /usr/share/zoneinfo/
-.RI ( /usr/lib/zoneinfo
-on old systems)
+.br
+.I /etc/localtime
+.br
 .I /dev/rtc
+.br
 .I /dev/rtc0
+.br
+.I /dev/misc/rtc
+.br
+.I /dev/efirtc
+.br
+.I /dev/misc/efirtc
+.br
 .I /dev/port
+.br
 .I /dev/tty1
+.br
 .I /proc/cpuinfo
-
+.
 .SH "SEE ALSO"
 .BR date (1),
+.BR adjtimex (8),
 .BR gettimeofday (2),
 .BR settimeofday (2),
 .BR crontab (1),
 .BR tzset (3)
-
+.
 .SH AUTHORS
 Written by Bryan Henderson, September 1996 (bryanh@giraffe-data.com),
 based on work done on the
-.I clock
+.BR \%clock (8)
 program by Charles Hedrick, Rob Hooft, and Harald Koenig.
 See the source code for complete history and credits.
-
+.
 .SH AVAILABILITY
 The hwclock command is part of the util-linux package and is available from
 ftp://ftp.kernel.org/pub/linux/utils/util-linux/.

[PATCH 4/4] hwclock: man page 'Since v2.26' notes

[JWP]

Clean up the 'Since v2.26' man page notes.
They were redundant of information already
in the manual, and became too verbose.

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 sys-utils/hwclock.8.in | 24 +++++-------------------
 1 file changed, 5 insertions(+), 19 deletions(-)

diff --git a/sys-utils/hwclock.8.in b/sys-utils/hwclock.8.in
index 505ff65..20a8dd0 100644
--- a/sys-utils/hwclock.8.in
+++ b/sys-utils/hwclock.8.in
@@ -36,25 +36,11 @@ Clock timescale; set the kernel's timezone, NTP timescale, and epoch
 (Alpha only); compare the System and Hardware Clocks; and predict future
 Hardware Clock values based on its drift rate.
 .PP
-Since v2.26
-.B hwclock
-does not update the Hardware Clock's drift factor in @ADJTIME_PATH@ by default.
-It is necessary to use \fB\-\-update-drift\fR, with \fB\-\-set\fR or
-\fB\-\-systohc\fR, to force drift factor updates.
-See the \fB\-\-update\-drift\fR option below for details.
-.PP
-Since v2.26
-.B hwclock \-\-hctosys
-does a better job at setting the System Clock: it no longer simply copies
-the time from the Hardware Clock to the System Clock, but sets the System
-Clock to a drift-compensated time.  (That is: it reads the Hardware Clock,
-applies a compensation for the systematic drift to this read time, and
-then sets the System Clock to the resulting value.)
-Therefore it is no longer necessary to run \fBhwclock --adjust\fR before
-doing \fBhwclock --hctosys\fR, and thus \fBhwclock\fR can be used very
-early on in the boot process when the root filesystem is still read-only.
-See the \fB\-\-hctosys\fR function below for information on inhibiting
-this new behavior.
+Since v2.26 important changes were made to the
+.B \-\-hctosys
+function, and the new option
+.B \-\-update\-drift
+was added. See their respective sections below.
 .
 .SH FUNCTIONS
 The following functions are mutually exclusive, only one can be given at

Re: [PATCH 1/4] hwclock: enable --directisa for x86_64

[Karel Zak]

On Wed, Jan 07, 2015 at 11:13:21PM -0500, JWP wrote:
>  sys-utils/hwclock-cmos.c | 9 +++++----
>  1 file changed, 5 insertions(+), 4 deletions(-)

 All 4 patches applied. Thanks.

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [PATCH 3/4] hwclock: update man page for v2.26 rc

[Benno Schulenberg]

On Thu, Jan 8, 2015, at 05:18, JWP wrote:
> +.\" 2015-01-07 J William Piggott
> +.\" Authored new section: DATE-TIME CONFIGURATION.
> +.\" Subsections: Keeping Time..., LOCAL vs UTC, POSIX vs 'RIGHT'.
> +.\" Errata and drop outdated language.
> +.\" Updates for v2.26

Please don't add such changelog stuff to files -- this is what git is for.

> +.\" Included for troff portability.
> +.\" Continuation line for .TP header.
> +.de TQ
> [...]

Is this really needed?  Is there any chance that this new hwclock
will get installed on a legacy Unix system (instead of on a recent
Linux system with complete man macros)?

> +is a tool for accessing the Hardware Clock.  It can: display the
> +Hardware Clock time; set the Hardware Clock to a specified time; set the
> +Hardware Clock from the System Clock; set the System Clock from the
> +Hardware Clock; compensate for Hardware Clock drift; correct the System
> +Clock timescale; set the kernel's timezone, NTP timescale, and epoch
> +(Alpha only); compare the System and Hardware Clocks; and predict future
> +Hardware Clock values based on its drift rate.

Nice.

> +.

Why all these added dots?  No other man page contains them.

> +The following functions are mutually exclusive, only one can be given at
> +a time. If none are given the default is
> +.BR \-\-show .

s/none are/none is/
because at most one may be given.

> -.B hwclock
> +.B \%hwclock

What does \% do?  Why is it not used fully everywhere where
.B hwclock occurs?

> [...]

Too much text to review.  :|

For such a huge change, it would have been nice to keep the
formatting changes and text changes in separate patches.

Benno

-- 
http://www.fastmail.com - mmm... Fastmail...

Re: [PATCH 3/4] hwclock: update man page for v2.26 rc

[JWP]

On 01/10/2015 07:44 AM, Benno Schulenberg wrote:
> 
> On Thu, Jan 8, 2015, at 05:18, JWP wrote:
>> +.\" 2015-01-07 J William Piggott
>> +.\" Authored new section: DATE-TIME CONFIGURATION.
>> +.\" Subsections: Keeping Time..., LOCAL vs UTC, POSIX vs 'RIGHT'.
>> +.\" Errata and drop outdated language.
>> +.\" Updates for v2.26
> 
> Please don't add such changelog stuff to files -- this is what git is for.

I went back and fourth on this myself, Benno. I agree we do not want full
changelogs in files. My thinking in this particular case was, that there
has not been a significant update to this man-page in a couple of decades
and not everyone using it will have a local git repo. Someone may question,
who wrote this stuff?

Also, since I authored some completely new content I was thinking of any
copyright/copyleft issues; although I did not actually claim any. At least
the change is dated in the file.

Before adding this I checked other utli-linux man-pages and some of them
have extensive top comments. Including some changelogs, granted they are
old, but there are recent top comments still being added. Take a look:

cat $(find -name "*.[1-9]") | grep '^\.\\"' | less

Anyway, I am fine with striping it out. No big deal either way to me.

> 
>> +.\" Included for troff portability.
>> +.\" Continuation line for .TP header.
>> +.de TQ
>> [...]
> 
> Is this really needed?  Is there any chance that this new hwclock
> will get installed on a legacy Unix system (instead of on a recent
> Linux system with complete man macros)?


I don't know. I did not think this new hwclock would be used in DEC
Alpha's either, but it is. Despite its name, I have read that util-
linux is used elsewhere. BSD comes to mind. This is the most portable
way to do it. Having said that, the howto-man-page.txt does use TQ
without defining it. Again, it's fine with me Karel thinks it is not
needed, I'll strip it out.


> 
>> +is a tool for accessing the Hardware Clock.  It can: display the
>> +Hardware Clock time; set the Hardware Clock to a specified time; set the
>> +Hardware Clock from the System Clock; set the System Clock from the
>> +Hardware Clock; compensate for Hardware Clock drift; correct the System
>> +Clock timescale; set the kernel's timezone, NTP timescale, and epoch
>> +(Alpha only); compare the System and Hardware Clocks; and predict future
>> +Hardware Clock values based on its drift rate.
> 
> Nice.

Thank you!

> 
>> +.
> 
> Why all these added dots?  No other man page contains them.
>


Because troff source is not allowed to have empty lines. Troff
skips lines with only a dot. This is even stated in the 
./Documentation/howto-man-page.txt page.

Perhaps no other util-linux pages use it, but many man-pages do.

I'm fine with not having them at all, but there were existing
empty lines delimiting things like options so I left them there.


>> +The following functions are mutually exclusive, only one can be given at
>> +a time. If none are given the default is
>> +.BR \-\-show .
> 
> s/none are/none is/
> because at most one may be given.

But there are multiple choices and 'none' is plural.
"If it is not given" is singular, but there are multiple choices.
"If one is not given" would work. I like it the way it is.

> 
>> -.B hwclock
>> +.B \%hwclock
> 
> What does \% do?  Why is it not used fully everywhere where
> .B hwclock occurs?


It is a soft hyphen. It should be used to prevent troff from
hyphenating commands, command strings, variable names, and
paths. When they appear in TP or TQ macros, or are otherwise
at that left margin, it is not necessary. It is probably a good
habit to just use them everywhere though. Except, never use it 
in the NAME section, the source format there is critical for
the whatis database. If I missed any it was an error on my part.
Looks like I missed the @ADJTIME_PATH@ macros too.

To see the difference it makes view the previous version with

MANWIDTH=40 man ./sys-utils/hwclock.8

You can try using various widths to hit different word hyphenations.

> 
>> [...]
> 
> Too much text to review.  :|
> 
> For such a huge change, it would have been nice to keep the
> formatting changes and text changes in separate patches.

I know Benno, I am sorry about that. I apologized for it in the
cover letter. I need to do better at remembering to make regular 
commits.

Somewhat in my defense, I attempted to comply with this rule when
I submitted a patch focused on string formatting (line-breaks) and 
was promptly hauled on the carpet for it. I am trying to learn the
the ropes here... hopefully sooner rather than later!

Speaking of the translation stuff, I have a question for you. First,
I admit my ignorance when it comes to the translation process. One of
these days I make the time to read about gettext; the documentation
seems quite lengthy. So, what I do not understand is why translation
software would flag a text line for changes in whitespace, punctuation,
formatting structure like line-breaks, or non-printing characters. I 
understand punctuation can change the meaning, but it seems unlikely that
it would impact the translation, assuming the translator parsed out the 
intended meaning the first time.


> 
> Benno
> 

Re: [PATCH 3/4] hwclock: update man page for v2.26 rc

[Benno Schulenberg]

On Sat, Jan 10, 2015, at 19:08, JWP wrote:
> I agree we do not want full
> changelogs in files. My thinking in this particular case was, that there
> has not been a significant update to this man-page in a couple of decades

Hmm...  Looking at 'git log -p -w --follow sys-utils/hwclock.8.in', the
first version of the man page dates from 1996.  Before 1998 there was a
substantial addition (Alpha stuff) and again for version 2.9i (unfortunately
undated).

BTW, Karel, where are the older versions of util-linux stored
(the ones before 2.13)?  I can't find them on kernel.org, but did find them
on http://ftp.europeonline.com/pub/linux/utils/util-linux/ .

(Also BTW, Karel, where has the homepage of util-linux gone?
It is no longer http://userweb.kernel.org/~kzak/util-linux/ .)

> Also, since I authored some completely new content I was thinking of any
> copyright/copyleft issues; although I did not actually claim any.

Ah!  Probably you should claim copyright.  Davidlohr Bueso did this,
for example, for a substantial addition to partx.  So I would suggest
that, instead of the changelog item, you add the following two lines
to the man page header:

Copyright 1996 Bryan Henderson <bryanh@giraffe-data.com>
Copyright 2015 J. William Piggott <elseifthen@gmx.com>

And if you find out who wrote the other substantial additions, you
could add copyright lines for them too.

(No need to specify which part of the page your copyright applies to,
that is what git is for.)

> Before adding this I checked other utli-linux man-pages and some of them
> have extensive top comments. Including some changelogs,

Well, the extensive top comments are for the most part just verbose
licenses.  The only two changelogs I see are in fstab.5 and swapon.8,
and those things are entirely obsolete.  The recent top comments are
added because they are about recent commands or substantial additions,
and they are just copyright lines, not changelogs.

> I did not think this new hwclock would be used in DEC
> Alpha's either, but it is. Despite its name, I have read that util-
> linux is used elsewhere. BSD comes to mind.

But if this modern hwclock is used, wouldn't the rest of the system
be modern too?  That is: have up-to-date man macros?

> > s/none are/none is/
> > because at most one may be given.
> 
> But there are multiple choices and 'none' is plural.

No, "none" isn't always plural.  :)
http://www.quickanddirtytips.com/education/grammar/none-or-none-are

> So, what I do not understand is why translation
> software would flag a text line for changes in whitespace, punctuation,
> formatting structure like line-breaks, or non-printing characters.

Whitespace might be used to line things up neatly, and gettext has
no way of knowing when this change is relevant or not, so it must
flag each and every change.

> I 
> understand punctuation can change the meaning, but it seems unlikely that
> it would impact the translation, assuming the translator parsed out the 
> intended meaning the first time.

Huh?  If the meaning of a string changes, surely the translation
will be different too...  Aah!  You mean: the translator translated
the string correctly even though it had faulty punctuation or tabbing
or spelling or something similar.  Ah, but you can't be sure of that.
So, the minutest change in a string must invalidate its translation.

Benno

-- 
http://www.fastmail.com - The way an email service should be

Re: [PATCH 3/4] hwclock: update man page for v2.26 rc

[JWP]

On 01/11/2015 06:44 AM, Benno Schulenberg wrote:
> 
> On Sat, Jan 10, 2015, at 19:08, JWP wrote:
>> I agree we do not want full
>> changelogs in files. My thinking in this particular case was, that there
>> has not been a significant update to this man-page in a couple of decades
> 
> Hmm...  Looking at 'git log -p -w --follow sys-utils/hwclock.8.in', the
> first version of the man page dates from 1996.  Before 1998 there was a
> substantial addition (Alpha stuff) and again for version 2.9i (unfortunately
> undated).
Seriously? I use a generalized term of 'a couple of decades' and you say I'm 
wrong it has only been 17 to 19 years?

I do not consider adding options and other code changes a significant update.
I meant, updating the contextual information about what the command does, how
it is used, and how date-time in general operates under Linux... not how many
bytes the file contains. I my opinion, when Bryan rewrote clock(8) in 1996 was
the last time that was done.  Sorry, I was off by one year.

> 
> BTW, Karel, where are the older versions of util-linux stored
> (the ones before 2.13)?  I can't find them on kernel.org, but did find them
> on http://ftp.europeonline.com/pub/linux/utils/util-linux/ .

I am interested in this as well. Specifically the full history of (hw)clock
back to 1992.

> 
> (Also BTW, Karel, where has the homepage of util-linux gone?
> It is no longer http://userweb.kernel.org/~kzak/util-linux/ .)
> 
>> Also, since I authored some completely new content I was thinking of any
>> copyright/copyleft issues; although I did not actually claim any.
> 
> Ah!  Probably you should claim copyright.  Davidlohr Bueso did this,
> for example, for a substantial addition to partx.  So I would suggest
> that, instead of the changelog item, you add the following two lines
> to the man page header:
> 
> Copyright 1996 Bryan Henderson <bryanh@giraffe-data.com>
> Copyright 2015 J. William Piggott <elseifthen@gmx.com>
> 
> And if you find out who wrote the other substantial additions, you
> could add copyright lines for them too.
> 
> (No need to specify which part of the page your copyright applies to,
> that is what git is for.)

As previously stated, I was not thinking of developers. I was considering
users that do not wish to create a git repository, nor browse one online, 
just to see who authored some man-page text.  Again, it is not important
to me, if Karel wants it gone that is fine. 

> 
>> Before adding this I checked other utli-linux man-pages and some of them
>> have extensive top comments. Including some changelogs,
> 
> Well, the extensive top comments are for the most part just verbose
> licenses.  The only two changelogs I see are in fstab.5 and swapon.8,
> and those things are entirely obsolete.  The recent top comments are
> added because they are about recent commands or substantial additions,
> and they are just copyright lines, not changelogs.
> 
>> I did not think this new hwclock would be used in DEC
>> Alpha's either, but it is. Despite its name, I have read that util-
>> linux is used elsewhere. BSD comes to mind.
> 
> But if this modern hwclock is used, wouldn't the rest of the system
> be modern too?  That is: have up-to-date man macros?

I do not know, Benno. I was just trying to maximize portability. I have
also read that some newer html man-page browsers do not implement some of
the extended macros.

> 
>>> s/none are/none is/
>>> because at most one may be given.
>>
>> But there are multiple choices and 'none' is plural.
> 
> No, "none" isn't always plural.  :)
> http://www.quickanddirtytips.com/education/grammar/none-or-none-are

I was not make a general comment about 'none', it was specific to this
instance.

In general, it often encompasses both singular and plural. The only case
where a singular accompanying verb is required is when the noun is 
uncountable.

>From your own reference:

"You may be chided by the uninformed when you follow "none" with a plural verb, 
but don’t be afraid to do so if your sentence calls for it.

> 
>> So, what I do not understand is why translation
>> software would flag a text line for changes in whitespace, punctuation,
>> formatting structure like line-breaks, or non-printing characters.
> 
> Whitespace might be used to line things up neatly, and gettext has
> no way of knowing when this change is relevant or not, so it must
> flag each and every change.

I'm not talking about normal program output, I'm talking about message
strings.

> 
>> I 
>> understand punctuation can change the meaning, but it seems unlikely that
>> it would impact the translation, assuming the translator parsed out the 
>> intended meaning the first time.
> 
> Huh?  If the meaning of a string changes, surely the translation
> will be different too...  Aah!  You mean: the translator translated
> the string correctly even though it had faulty punctuation or tabbing
> or spelling or something similar.  Ah, but you can't be sure of that.
> So, the minutest change in a string must invalidate its translation.

Well, I suppose the folks doing this know better than I. It still seems 
unreasonable to me that if a programmer inadvertently makes a 160 character 
string (s)he is not allowed to fix it by adding a line break, because it
will trip a translation flag... that seems nuts to me. The same for line
ending periods, they are only delimiters and should not change the meaning. 
Arguably, all message strings should be conducive to logging. Meaning single
line output, in grammar terms, single line vertical lists, no delimiters 
required. The last thing anyone wants in log files are paragraphs of text,
which is the reason full stops exist.


> 
> Benno
> 

Re: [PATCH 3/4] hwclock: update man page for v2.26 rc

[Karel Zak]

On Sun, Jan 11, 2015 at 12:44:35PM +0100, Benno Schulenberg wrote:
> BTW, Karel, where are the older versions of util-linux stored
> (the ones before 2.13)?  I can't find them on kernel.org, but did find them
> on http://ftp.europeonline.com/pub/linux/utils/util-linux/ .

Well, all known history has been ported to git (see git tag -l), but I
can push it to kernel.org ftp too (OK, added to may TODO).

> (Also BTW, Karel, where has the homepage of util-linux gone?
> It is no longer http://userweb.kernel.org/~kzak/util-linux/ .)

Yes, after the kernel.org hack the user web pages are no more
supported and I think that

 https://en.wikipedia.org/wiki/Util-linux

is enough, it's better to keep all important information there, than 
create another extra page.

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com