hwclock: add TZDIR

Add information about TZDIR and improve the
ENVIRONMENT section.

---
 sys-utils/hwclock.8.in | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

index fbc10ca..65ab99a 100644
@@ -1039,11 +1039,18 @@ time conversion.
 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
-.
+or 'right', as described above, or by assigning a database path to the
+.SB TZDIR
+environment variable.
+.SH ENVIRONMENT
+.TP
+.B TZ
+If this variable is set its value takes precedence over the system
+configured timezone.
+.TP
+.B TZDIR
+If this variable is set its value takes precedence over the system
+configured timezone database directory path.
 .SH FILES
 .br
 .I @ADJTIME_PATH@

---
 sys-utils/hwclock.8.in | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

index 65ab99a..51367a4 100644
@@ -1052,10 +1052,19 @@ configured timezone.
 If this variable is set its value takes precedence over the system
 configured timezone database directory path.
 .SH FILES
-.br
+.TP
 .I @ADJTIME_PATH@
-.br
+The configuration and state file for hwclock.
+.TP
 .I /etc/localtime
+The system timezone file.
+.TP
+.I /usr/share/zoneinfo/
+The system timezone database directory.
+.PP
+Device files
+.B hwclock
+may try for Hardware Clock access:
 .br
 .I /dev/rtc
 .br

@@ -1070,9 +1079,6 @@ configured timezone database directory path.
 .I /dev/port
 .br
 .I /dev/tty1
-.br
-.I /proc/cpuinfo
-.
 .SH "SEE ALSO"
 .BR date (1),
 .BR adjtimex (8),

Replace references to the depreciated ntpdate with sntp.

---
 sys-utils/hwclock.8.in | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

index 51367a4..0c294af 100644
@@ -888,7 +888,7 @@ 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
+.BR \%sntp ", 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

@@ -931,7 +931,7 @@ results it will likely need to be adjusted by directly editing the
 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
+.BR \%sntp ", or " \%date\ \-Ins
 and a precision timepiece, immediately after startup.
 .PP
 Both clocks typically use a quartz crystal oscillator.  Crystals are

Add that '11 minute mode' is a kernel compile time option. Add details regarding its activation and how to check its status.

---
 sys-utils/hwclock.8.in | 25 +++++++++++++++----------
 1 file changed, 15 insertions(+), 10 deletions(-)

index 0c294af..8cf86a3 100644
@@ -758,25 +758,30 @@ You can use an adjtime file that was previously used with the
 .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.
+copies the System Time to the Hardware Clock every 11 minutes. This mode
+is a compile time option, so not all kernels will have this capability.
 This is a good mode to use when you are using something sophisticated
 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
-can turn it off by running anything, including
+If the kernel is compiled with the \%'11\ minute\ mode' option it will
+be active when the kernel's clock discipline is in a synchronized state.
+When in this state the binary 64's bit of the kernel's
+.I \%time_status
+variable is unset (10111111). This value is output as the 'status' line of the
+.BR \%adjtimex\ --print " or " \%ntptime " commands."
+.PP
+It takes an outside influence, like the NTP daemon
+.BR ntpd (1),
+to put the kernel's clock discipline into a synchronized state, and
+therefore turn on \%'11\ minute\ mode'.
+It can be turned off by running anything, including
 .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
+still running, it will turn \%'11\ minute\ mode' back on again the next time it
 synchronizes the System Clock.
 .PP
-When \%'11\ minute\ mode' is active the 64 bit of the kernel's
-.I time_status
-variable is unset. The status variable can be checked with the
-.BR \%adjtimex\ --print " or " \%ntptime " commands."
-.PP
 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 use

The information I wrote regarding clock crystals was not only incomplete, it was wrong. The characteristics of quartz crystals is beyond the scope of this man-page. It was misguided to attempt to include it. This commit removes said information.

---
 sys-utils/hwclock.8.in | 22 ----------------------
 1 file changed, 22 deletions(-)

index 8cf86a3..79c7907 100644
@@ -938,28 +938,6 @@ Clock is corrected properly at startup.  To check this, first make sure
 that the System Time is correct before shutdown and then use
 .BR \%sntp ", 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:

s/depreciated/deprecated/

Hmm, maybe it's a bit to early to delete the mention of ntpdate? My fairly recent Linux Mint doesn't have sntp yet. Maybe add sntp to the list instead of replacing ntpdate?

Oh, in the previous patch you used an inconsistent capital in the subject line. And the same s/system/system's/ applies.

Benno

http://www.fastmail.com - Accessible with your email software
                          or over the web

These patches only touch the man page of hwclock. For changes to documentation only, the normal marker is "docs:". So I think your subject line should be something like:

docs: add TZDIR to the man page of hwclock

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

Ow. That is puzzling. As if all the other bits have to be set in order for bit 6 to be unset. I would instead say something like:

"When in this state, bit 6 (the bit that is set in the mask 0x0040) of the kernel's time_status variable is *unset*."

I would move the "including..." phrase to the end of the sentence, as now one at first thinks that really *anything* can turn 11-minute mode off.

Benno

http://www.fastmail.com - Email service worth paying for. Try it for free

Hmm... "man-page errata" is a really vague description of this patch. Better: "docs: snip section about crystals from man page of hwclock". When so, the above two last sentences become superfluous. Oh, and s/is beyond/are beyond/.

Benno

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

On Debian Jessie, there's ntpdate, no sntp, and apt-cache search sntp only shows rdate (which can use the SNTP protocol).

Thanks,
Isaac Dunham

Frankly, I prefer "<utilname>: ...." for patches. The "docs:" is better only for some generic and global cleanups.

Karel

 Karel Zak  <[email protected]>
 http://karelzak.blogspot.com

Good point, it would be better to use something like "ntpdate or more recent sntp".

Karel

 Karel Zak  <[email protected]>
 http://karelzak.blogspot.com

No, it is not a good point. I assume he means *too* early, that's the funniest thing I've heard all day. No wait, "doesn't have sntp yet", that's the funniest thing I've heard all day.

The sntp client and ntpdate are both from the same project and approximately the same age. Nobody was interested in maintaining ntpdate so it *depreciated* over many years before being officially *deprecated* by the project.

The sntp client is in the ntp package for Mint/Debian/Ubuntu. Try opening a terminal and typing 'sntp' or 'man sntp'.

Before I added ntpdate two months ago, the hwclock man-page had gone 20 years without it. Now there's concern over removing it?

Disclaimer: This program has known bugs and deficiencies and nobody has volunteered to fix them in a long time. The good news is the functionality originally intended for this program is available in the ntpd and sntp programs. See the [2]Deprecating ntpdate topic in the NTP Support wiki for a thorough discussion and analysis of the issues. See the -q command line option in the [3]ntpd - Network Time Protocol (NTP) daemon page and/or the [4]sntp - Simple Network Time Protocol (SNTP) Client page. After a suitable period of mourning, the ntpdate program will be retired from this distribution.

You miss the point, after util-linux update, someone will read the man page and then type "sntp" on command line, but because he has old / stupid distro it will be unsuccessful. What next if there is no any pointer to any other alternative?

You're absolutely right with ntpdate vs. sntp, but it seems reality is so painful that people still have systems where is no sntp.

OK :-) I'm going to apply the patches, it's nothing critical.

Karel

 Karel Zak  <[email protected]>
 http://karelzak.blogspot.com

Yes, this is more readable (at least for me:-).

I have applied this two changes.

Karel

 Karel Zak  <[email protected]>
 http://karelzak.blogspot.com

All set of the patches merged from github, thanks!

Karel

 Karel Zak  <[email protected]>
 http://karelzak.blogspot.com

I understand the point, Karel. I am saying it is not valid in this case because...

... I do not believe such a distribution exists. Any distribution that ships with util-linux also has an ntp package available. The sntp client is part of the ntp package. Do you know of a non-embedded mainstream Linux distro that doesn't offer the ntp package? It would be a very odd thing to do I believe.

Furthermore, this section of the man-page is dealing with '11 minute mode'; if the system does not have the ntp package installed then none of this even applies to them.

I explained to Mr Schulenbuerg that I wrote it that way for layman users. Are they going to understand 'the bit that is set in the mask 0x0040'? What does that even mean? What does 'mask' have to do with it? It could simply say "the bit that is set by binary 0x0040"
How does that differ from saying the binary 64's bit?

Using hex will help the average user how?

I used decimal because adjtimex displays the status variable as a decimal number:

adjtimex -p
status: 8193

adjtimex -p
status: 8257

Which one is synchronized?

The adjtimex man-page says:

"status" gives the value of the time_status variable in the kernel.
64 clock unsynchronized

The average user will likely have trouble with this.

By saying 'the binary 64 bit' it will allow average users to understand the relationship. When Bryan originally wrote this section (it was removed because of the adjtimex issue), he used the same language 'the 64 bit'. I suspect he did it for the same reasons. I added the binary number example to help people that do not understand binary to visualize exactly where the the unset bit would be. Then if they manage to convert the adjtimex output from decimal to binary it should be clear to them.

Calling it bit 6 will likely cause average users to make an off-by-one error. There is no ambiguity with the binary 64 bit.

Karel, it makes good sense to you because you have a clear understanding of binary bit masks. Does the rest of the world have the same understanding?

What I wrote is far from optimum, but I do not think this is an improvement.

I have doubts it will be readable for layman users at all independently on used words :-) Now it's at least readable for advanced users. If you want to make it really readable for layman users than add and example to the man page.

$ echo $((8193 & 0x0040))
0

$ echo $((8257 & 0x0040))
64

and frankly it's adjtimex mistake that it does not provide the information in more human readable way.

Karel

 Karel Zak  <[email protected]>
 http://karelzak.blogspot.com