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).



BUILDING
--------

$ ./configure
$ make

I.e. with the Hwclock source directory as your current directory, run
'./configure' with no parameters, then 'make' with no parameters.

'configure' is very simple so if it gives you any trouble, you can easily work
around it.  The only choice it makes is whether directio.h includes <sys/io.h>
or <asm/io.h>.  Newer systems have the former, while older systems have the
latter.  So you can just edit directio.c to fit your system, then create
an empty config.mk and config.h.



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.


It was once (ca. 1996 common to install Hwclock or its predecessor
setuid root because it requires superuser privilege even to read the
clock.  But until 2003, that was safe because 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.


SERVICE
-------

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


MISCELLANEOUS
-------------

Hwclock calls option processing routines that are derived from
Sverre H. Huseby's "shhopt" package.


LICENSE
-------

Hwclock is offered to the public under the GNU Public License.  See
the file GPL_LICENSE.txt.

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