MDATE(1L) MDATE(1L)
June 1995
NAME
mdate - get the time of day from a remote host
SYNOPSIS
mdate [ -a|-s ] [ -c count ] [ -d ] [ -t tol ] [ -w wait ] host ...
DESCRIPTION
Mdate requests the time of day from host, which may be a host name or
an IP address. If more than one host is specified, they are queried
in order until a response is received. It calculates the time of day
on the host and the estimated time difference between remote and local
host. A positive difference means the remote host is ahead of the
local host.
The superuser can set the local time of day to agree with the time on
the remote host to within a small error.
OPTIONS
-a|-s
If the caller is the super-user and the time difference is large
enough, then mdate will use adjtime(2) or settimeofday(2)
respectively to synchronise the local host's time with the remote
host. The -a flag is only allowed if adjtime(2) is actually
available.
-c count
Repeat the call count times.
-d Print verbose output for debugging. More -d flags increase the
verbosity.
-t tol
Change the tolerance to tol quanta (default=3).
-w wait
Wait for n seconds before calling the server, where n is a
pseudo-random number in the range 0 < n < wait
USAGE
Mdate is intended to be used as a simple device for keeping several
machine clocks in sync over a small size local area network. It is
based on the older programs rdate and in.timed . The most important
change is that mdate uses ICMP timestamps. This makes it far more
accurate than rdate. Over short distances (say, within a building)
mdate can synchronise to within about 10 milliseconds, which should be
close enough for most purposes. The disadvantage is that you have to
be super-user to use mdate even just for testing.
- 1 - Formatted: October 29, 2025
MDATE(1L) MDATE(1L)
June 1995
Before starting to compile mdate, the installer should determine the
quantum, which is the smallest time interval that the local machine
can measure. I have provided a supplementary program called tick to
help with this. You should then edit the source file site.h to define
quantum correctly. A time difference is deemed to be significant
if it exceeds tolerance * quantum and mdate will not alter the local
time if the estimated difference is less than this amount. The -t flag
changes the tolerance (default=3).
The -c flag makes mdate call the remote host count times. This has 2
purposes. It can be used to probe the system's behaviour: mdate -d -d
-c10 host This prints a small table. Also ICMP is not a reliable
protocol, so if some calls fail to get through, you can increase the
chance of success by making repeated calls. As the distances get
larger, the round-trip times get larger and more variable. By
repeating the call you have a much better chance of getting an
accurate value. mdate does not attempt any statistical analysis of
the resulting data. It merely accepts the time difference that goes
with the shortest trip time.
By default, mdate prints nothing except error messages. It is intended
to be called automatically by cron and (on our machines) cron seems to
get confused by output. The -d flag makes mdate print a line
indicating success or failure. A 2nd and 3rd -d increase the
verbosity.
To keep a log, use just one -d and pipe the output to a file or to
logger (or syslog ). It is advisable to do this at least for the first
few days: there may be bugs; also the log will help to estimate your
clock's rate of drift.
mdate is intended as a lightweight mechanism for keeping time in a
small local network. The normal setup is to name one machine as local
server. This gets its time from a national timeserver: you should
first ask permission from that server's manager. Then all the other
local machines would do something like: mdate -c5 -w100 local-server
and you would use cron to make this happen at regular intervals.
If the clients all start pestering the server at once, there is a
danger that the server or net or both will overload. The flag -w wait
spreads the load. If this flag is present, mdate will wait for a
pseudo-random number of seconds in the range 0 .. wait . We suggest a
wait about 5 times the number of clients.
With these additional features, mdate should be able to keep time to
within about 0.001 sec for local networks of up to around 100
machines. If you have more, you should either arrange a hierarchy of
timeservers or install a more elephantine protocol such as xntp.
The multiple-host feature can be used to provide backups if one server
is down. Suppose there were 2 prospective local servers A and B and a
- 2 - Formatted: October 29, 2025
MDATE(1L) MDATE(1L)
June 1995
national server N . Then A might do mdate (args) N (say, at 1AM) and B
might do mdate (args) A N at 2AM and the clients would do mdate (args)
A B at 3AM.
DIAGNOSTICS
Mdate checks the return status of system functions and uses perror to
print error messages (which are usually not very informative). Errors
specific to Mdate include the following;
packet too short.
means we received something that looked like a truncated ICMP
packet.
huge difference.
A huge difference is a time difference > about 2 hours. This is
almost certainly caused by a bug in Mdate , or maybe the server
has gone mad. If any machine is really that far out, set its
date manually.
time unchanged.
This should be either because the time diff was too small to be
significant or because the caller did not specify either -a or
-s.
Exit status is 0 on success, otherwise 1.
DEFECTS
Since the ICMP timer wraps around at midnight you may get a "huge
difference" error if you run mdate shortly before or after. You should
try very hard to avoid using mdate near midnight. Note this is
midnight GMT not local time.
Some machines do not respond to ICMP time requests; they cannot act as
servers but you might be able to run mdate on them.
You have some protection against servers crashing (use multiple
hosts); some protection against servers going wild (the huge
difference check) but no protection at all against servers that drift.
Mysterious loss of accuracy. If mdate measured a round-trip time of 3
msec, this ought to mean that the subsequent settimeofday is that
accurate.
AUTHOR
R.M.Damerell, Maths Dept, Royal Holloway College, Egham, Surrey, UK.
Program uses parts of rdate.c (by Dartmouth College) and ping.c (Mike
Muuss, US Army Ballistic Research Lab modified by Berkeley). Their
copyright notices are reproduced in full in the source code. Program
is offered free of charge, "AS IS" with absolutely no guarantees.
- 3 - Formatted: October 29, 2025
MDATE(1L) MDATE(1L)
June 1995
Bug reports etc to RMD at this address: uhah208@ma.rhbnc.ac.uk (but no
promise to fix).
SEE ALSO
adjtime(2), gettimeofday(2), settimeofday(2), tick(1), utimed(1),
- 4 - Formatted: October 29, 2025
