SETTIME(1)

NAME
settime - Set system time from atomic clock

SYNOPSIS
settime [ -e ] [ -mmodem_port ] [ -ndial_string ] [ -ttimeout ]

DESCRIPTION
Don't you just hate it when your computer clock doesn't keep accurate time? Not only is a balky clock irritating, it can lead to more serious problems such as make failing to recompile files or files not being backed up, particularly in a local network environment.

For a good time, call (303) 494-4774. It's from the government, and it's there to help you. The National Institute of Standards and Technology, NIST, (formerly the National Bureau of Standards) maintains the master time standard for the United States with a bank of cesium atomic clocks in Boulder, Colorado. They provide a dial-up service which furnishes a time and date directly traceable to the national time standard which, in turn, is based on the definition of the second. You don't get any more accurate than that. The service is free of charge (other than the regular long distance telephone cost).

The time and date are provided at 1200 baud, with compensation for line and modem delays. By carefully adjusting for speed of light lag, modem character serialisation and assembly time, and computer response time, it is usually possible to obtain the time to within two milliseconds of the correct value. In practice, it is rarely worth going to all the added difficulty since most computer clocks drift sufficiently to erase such a precision setting within a couple of hours. A very simple time setting procedure suffices to obtain the time to within 10 or 20 milliseconds of the standard, which is usually more than adequate.

settime is a Unix program that dials the NIST time service with a Hayes-like modem, obtains the time from the standard, performing validity checking to guard against communication errors, then, if run by the super-user, sets the computer's time of day clock with the settimeofday() call.

OPTIONS

-e  Echo modem input and output to standard output. This option is intended for debugging only; using it introduces delays which reduce the accuracy with with the system clock is set.

-mmodem_port
    Use modem_port to dial the NIST time service. If omitted, the default port of /dev/cua0 is used.

-ndial_string
    The given dial_string is sent to the modem to dial the NIST time service. The string may contain all required modem commands in addition to the telephone number. A carriage return is automatically appended to the given string. If the option is omitted, a default dial string of ATDT13034944774 is used. If you require pulse dialing, a prefix to get an outside line, or special modem setup, specify an alternative dial string with the required modes.

-ttimeout
    settime allows two minutes to obtain the time from NIST; this usually suffices and the time limit prevents running up large phone bills if NIST is out of service. You can change the timeout, if desired, by specifying the length in seconds, with this option.

BUGS
The program has currently been tested only on a Sun SPARCStation 2 with a Hayes Smartmodem 2400. Although I've tried to use only the simplest and most portable facilities in this program, data communications always involves a modicum of pain when porting to a new system, and this program will probably prove no exception. Please send me any portability or other fixes you make for your system.

The program could be even more careful than at present in verifying correctness of the received time and date and in checking for odd communications failures. So far, the level of checking in the program has proven adequate.

If run by a user other than the super-user, no warning is given that the system time is not changed.

The ultra-precise mode in which the actual modem and line delay is measured by the NIST computer and compensated for is not implemented. This mode requires instantaneous local echo-back of received characters. Unix systems cannot, in my experience, provide the consistent real-time response required by this mode.

SEE ALSO
settimeofday(2)

AUTHOR
    John Walker
    Autodesk SA
    Avenue des Champs-Montants 14b
    CH-2074 MARIN
    Switzerland
    Fax: 038/33 88 15
    Voice: 038/33 76 33
    Usenet: kelvin@Autodesk.com

DETAILS OF THE TIME SERVICE
DESCRIPTION OF THE AUTOMATED COMPUTER TELEPHONE SERVICE (ACTS) The following is transmitted (at 1200 Baud) after completion of the telephone connection.
     ? = HELP
     National Institute of Standards and Technology
     Telephone Time Service
                             D  L D
      MJD  YR MO DA H  M  S  ST S UT1 msADV        <OTM>
     47999 90-04-18 21:39:15 50 0 +.1 045.0 UTC(NIST) *
     47999 90-04-18 21:39:16 50 0 +.1 045.0 UTC(NIST) *
     47999 90-04-18 21:39:17 50 0 +.1 045.0 UTC(NIST) *
     47999 90-04-18 21:39:18 50 0 +.1 045.0 UTC(NIST) *
     47999 90-04-18 21:39:19 50 0 +.1 037.6 UTC(NIST) #
     47999 90-04-18 21:39:20 50 0 +.1 037.6 UTC(NIST) #
     etc..etc...etc.......
UTC = Universal Time Coordinated, the official world time referred to the zero meridian.

DST = Daylight savings time characters, valid for the continental U.S., are set as follows:
  00 = We are on standard time (ST).
  50 = We are on DST.
  99 to 51 = Now on ST, go to DST when your local time is
             2:00 am and the count is 51.    The count is
             decremented daily at 00 (UTC).
  49 to 01 = Now on DST, go to ST when your local time is
             2:00 am and the count is 01.    The count is
             decremented daily at 00 (UTC).

The two DST characters provide up to 48 days advance notice of a change in time. The count remains at 00 or 50 at other times.

LS = Leap second flag is set to "1" to indicate that a leap second is to be added as 23:59:60 (UTC) on the last day of the current UTC month. The LS flag will be reset to "0" starting with 23:59:60 (UTC). The flag will remain on for the entire month before the second is added. Leap seconds are added as needed at the end of any month. Usually June and/or December are chosen.

DUT1 = Approximate difference between earth rotation time (UT1) and UTC, in steps of 0.1 second. DUT1 = UT1 - UTC

MJD = Modified Julian Date, often used to tag certain scientific data.

The full time format is sent at 1200 Baud, 8 bit, 1 stop, no parity. The format at 300 Baud is also 8 bit, 1 stop, no parity. At 300 Baud the MJD and DUT1 values are deleted and the time is transmitted only on even seconds.

Maximum on line time will be 56 seconds. If all lines are busy at any time, the oldest call will be terminated if it has been on line more than 28 seconds, else, the call that first reaches 28 seconds will be terminated.

Current time is valid at the "on-time" marker (OTM), either "*" or "#". The nominal on-time marker (*) will be transmitted 45 ms early to account for the 8 ms required to send 1 character at 1200 Baud, plus an additional 7 ms for delay from NIST to the user, and approximately 30 ms "scrambler" delay inherent in 1200 Baud modems. If the caller echoes all characters, NIST will measure the round trip delay and advance the on-time marker so that the midpoint of the stop bit arrives at the user on time. The amount of msADV will reflect the actual required advance in milliseconds and the OTM will be a "#". The NIST system requires 4 or 5 consecutive delay measurements which are consistent before switching from "*" to "#". If the user has a 1200 Baud modem with the same internal delay as that used by NIST, then the "#" OTM should arrive at the user within +-2 ms of the correct time. However, NIST has studied different brands of 1200 Baud modems and found internal delays from 24 ms to 40 ms and offsets of the "#" OTM of +-10 ms. For many computer users, +-10 ms accuracy should be more than adequate since many computer internal clocks can only be set with granularity of 20 to 50 ms. In any case, the repeatability of the offset for the "#" OTM should be within +-2 ms, if the dial-up path is reciprocal and the user doesn't change the brand or model of modem used. This should be true even if the dial-up path on one day is a land-line of less than 40 ms (one way) and on the next day is a satellite link of 260 to 300 ms. In the rare event that the path is one way by satellite and the other way by land line with a round trip measurement in the range of 90 to 260 ms, the OTM will remain a "*" indicating 45 ms advance.

For user comments write:
NIST-ACTS
Time and Frequency Division
Mail Stop 524
325 Broadway
Boulder, CO  80303
USA
Software for setting (PC)DOS compatable machines is available on a 360-kbyte diskette for $35.00 from:

NIST Office of Standard Reference Materials B311-Chemistry Bldg, NIST, Gaithersburg, MD, 20899, USA, (301) 975-6776