Hwclock is a program that runs under Linux and sets and queries the 
Hardware Clock, which is often called the Real Time Clock, RTC, or
CMOS clock.

You can set the Hardware Clock to a particular time or from the Linux
System Time.  You can set the Linux System Time from the Hardware
Clock, and a typical usage is to invoke Hwclock from a system startup
script to initialize the System Time.

Hwclock's --adjust function corrects systematic drift in the Hardware
Clock.  You just invoke it regularly and it corrects for a fast or
slow Hardware Clock.  Hwclock automatically computes how fast or slow
the Hardware Clock is every time you set it.

Hwclock also can get and set the Linux kernel "epoch" value.

Hwclock normally uses the rtc device driver (typically /dev/rtc) to
access the hardware clock.  But it knows several other methods too.

You will find complete documentation of Hwclock in the man page
(hwclock.8 in the src/ directory).


INSTALLATION
------------

DO NOT INSTALL HWCLOCK SETUID ROOT unless you really know what you're
doing.  If you install it setuid root, anyone with permission to
execute Hwclock can modify the Hardware Clock, the System Time, and
the kernel epoch value, and can write over an arbitrary file by
setting the ADJTIME_PATH environment variable.  And those are just the
things we know of.  There could be other ways, including the results of
bugs, that Hwclock users might have more power than you intend if you
install it setuid root.


Old releases of Hwclock refused to do setting operations unless the
invoker was the real (as opposed to effective) superuser.  Modern
Hwclock doesn't have any such restriction.  It prefers not to
interfere with the normal Linux privilege system, for example /dev/rtc
file permissions.

You may want to preformat and/or compress the man page before installing.

If you want to build Hwclock, just cd to the src directory and invoke
Make with no parameters:

  make

Hwclock calls option processing routines in the libsshopt library,
which is part of Sverre H. Huseby's "shhopt" package.  A copy of the
source code for this library is included in the package and the build
process will build a private copy of the library.  But you can use a
copy that is already on your system by altering the make file.  You
can find a more authoritative copy of this library, and its source
code, on sunsite (ftp://sunsite.unc.edu/pub/Linux/libs/shhopt-X.Y).


SERVICE
-------

Hwclock is enthusiastically maintained by bryanh@giraffe-data.com
(Bryan Henderson).  Please email Bryan any bug reports, questions, or
suggestions.


LICENSE
-------

Hwclock is distributed under the GNU Public License.  See the file
GPL_LICENSE.txt.

The copyright is held by the authors identified in the HISTORY file
and run from the dates of first publication stated in that file.
