.TH READCLOCK 8
.SH NAME
readclock \- read the AT's real time clock
.SH SYNOPSIS
\fBreadclock\fP [\fB\-bcnw\fP]
.SH DESCRIPTION
.B Readclock
reads the AT's real time clock and sets the machine's time.  It is usually
the second thing done in
.BR /etc/rc ,
the first thing is setting the time zone by sourcing
.BR /etc/timeinfo .
This means that the clock is assumed to tell the wall clock time.  If you
want to run the clock in GMT then you can set the TZ boot environment variable
to GMT to tell
.B readclock
the time zone the hardware clock is running in.  Any other timezone is
possible too, so you can run the clock in winter time for instance.
.PP
.B /etc/timeinfo
is also the place where
.B readclock
looks for information on how to calibrate a badly running clock.  This
information consists of a base and two offsets.  The base is the time the
internal clock was exactly equal to wall clock time, the first offset is
the number of seconds the hardware clock has ticked since the last time it
was correct, the second offset is the number of seconds it should have
ticked.  These offsets are used to compute the clock gain or loss since the
base time.
.SH OPTIONS
.TP
.B \-b
Rebase.  The hardware clock has been adjusted to the current time, so a
new base needs to be used.  Before doing this or the next option, first
set the time of the system using
.BR date (1),
or
.BR stime (1).
.TP
.B \-c
Calibrate.  The correction offsets must be recomputed.  Run this just now
and then to recompute the calibration offsets.  The more time between this
and the last rebase the better.
.TP
.B \-n
Play-act, don't set the time nor change the calibration data, just show what
would be done.
.TP
.B \-w
Write the current time to the CMOS clock.  Dangerous, see
.BR BUGS .
.TP
.B \-W
Like
.BR \-w ,
but also sets the status registers of the CMOS clock to their proper values.
(For if the clock suddenly runs at an odd pace or has stopped and the BIOS
doesn't repair it.)
.SS How To Calibrate
First set system time precisely with
.B date
or
.BR stime .
Then use the
.B \-w
and
.B \-b
options to set the hardware clock and the calibration base to the current
time, like this:
.BR "readclock \-bw" .
.PP
After a week or so when the clock's mistake becomes apparent, set the
system time again with
.B date
or
.B stime
and run
.BR "readclock \-c" .
You can repeat this every now and then to set the offsets more accurately.
.PP
If after some time you want to set the hardware clock right again, set
system time and rerun
.BR "readclock \-bw" .
You don't need to run
.B readclock \-c
anymore after this, the offsets are now known.
.SH FILES
.TP 20n
/etc/timeinfo
Timezone and calibration data.
.SH "SEE ALSO"
.BR date (1),
.BR utime (1),
.BR rdate (8).
.SH BUGS
Reported to not work on some AT's.
.PP
May mess up the clock royally when setting it
.RB ( \-w ).
Only if you have a very standard AT and you are not afraid of having your
CMOS setup reset to the default with a "checksum error" should you use
.BR readclock
to set the time of the CMOS clock.  You have been warned.
.PP
The clock must be reliably wrong for the calibration to work.
.SH AUTHOR
Kees J. Bot (kjb@cs.vu.nl)