." $Id:$
.TH adj_clock 8 "2006-10-18" 
.SH "NAME" 
adj_clock \(em Synchronize system clock to zaptel clock
.SH "SYNOPSIS" 
.B adj_clock 
.I [ -c
.B count
.I ] [ -i 
.B interval
.I ] [ -t 
.B period
.I ] [ -v ]

.SH "DESCRIPTION" 
.B adj_clock
compares synchronizes the system clock from Zaptel's clock: in each cycle
It will read 1024 * 
.B interval
ticks from a Zaptel pseudo channel, which should take exactly 
.B interval
seconds. It measures the time it did take, and uses 
.I adjtimex(3)
to fix the system clock accordingly.

Note that NTP servers usually use adjtimex. You may get strange behaviour 
if you have a NTP server (such as ntpd(8)) running on the system.

Output is sent to both the standard error and to the syslog. Syslog 
messages are with facility daemon.

.SH OPTIONS
.I -c
.B count
.RS
Run just 
.B count
synchronization cycles. Default is to run forever.
.RE

.I -i 
.B interval
.RS
Loop interval (in seconds). Optional, as program should provide a sane value.

Small values allow faster synchronization when the system is quiet. Even 
a value as low as 10 should work. However they are much more suspectable 
to short interruptions. 

.RE

.I -t
.B period
.RS
Set the synchronization tolerance priod (micro-seconds). The default
is 100. Don't touch it unless you know what you're doing.
.RE

.I -v
.RS
Be more verbose: log status messages even when synchronized.
.RE

.SH FILES
.B /dev/zap/pseudo
.RS
.RE
The device file used to open a "pseudo" channel (a channels that
constantly streams voice and is synchronized by the master Zaptel
device).

.SH SYNCHRONIZATION
Some more technical details. This explains the strange numbers the
program prints.

In each cycle
.B adj_clock 
measures 
.B interval
seconds using Zaptel ticks. It then compares that to the system time
from gettimeofday(2). It then calls adjtimex(2) to slightly change the 
rate of the system clock. It uses two parameters: 
.B ticks, 
which is a more
coarse one (1 tick will give roughly a change of rate of 9 seconds per
day) and 
.I frequency, 
which allows much finer settings.

The program tries to set what it can by ticks, and the rest through
frequency. It considers itself "synchronized" when the rate difference
is small enough so 
.I (a)
It does not have to use ticks anymore. And
.I (b) 
The rest of the interval to change is smaller than the tolerance period
(100 micro-seconds, by default).

The meaning of the parameters it prints is, thus:

.I interval
.RS
The current interval parameter (seconds).
.RE

.I diff_tick
.RS
The number of ticks it tries to set through adjtimex(2). 
Anything different than 0 means we're still way off mark.
.RE

.I diff_usec
.RS
The time difference (micro-seconds) that we need to overcome in the 
first place. This is the difference between the system clock and the
measured zaptel clock.
.RE

.I usec_left
.RS
How much of this difference (microseconds) we still need to adjust
after using ticks. This should be low enough (less than the tolerance
period).
.RE

.SH SIGNALS
.B adj_clock
is so far an interactive program, and thus killed by SIGHUP. SIGUSR is 
used to increase verbosity level and SIGUSR2 is used to reset verbosity
level to 0. When SIGUSR1 is recieved a status message will also be sent 
to the logs.

.SH SEE ALSO 
ztcfg(8), zttest(8), adjtimex(2), gettimeofday(2), adjtimex(8)

.SH AUTHOR 

This manual page was written by Tzafrir Cohen <tzafrir.cohen@xorcom.com> 
Permission is granted to copy, distribute and/or modify this document under 
the terms of the GNU General Public License, Version 2 any  
later version published by the Free Software Foundation. 
 
On Debian systems, the complete text of the GNU General Public 
License can be found in /usr/share/common-licenses/GPL.