1 files changed, 144 insertions, 0 deletions
diff --git a/xpp/utils/adj_clock.8 b/xpp/utils/adj_clock.8
new file mode 100644
index 0000000..0e9cf71
--- /dev/null
+++ b/xpp/utils/adj_clock.8
@@ -0,0 +1,144 @@
+." $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.