home *** CD-ROM | disk | FTP | other *** search
/ nisttime.carsoncity.k12.mi.us / nisttime.carsoncity.k12.mi.us.tar / nisttime.carsoncity.k12.mi.us / pub / daytime / nistime.man < prev    next >
Text File  |  1997-09-20  |  6KB  |  159 lines
  1. Name
  2.    nistime -- compare time of local clock with NIST time server
  3.     This version is intended for UNIX-like environments.
  4.     See file README.DAYTIME for versions for other environments.
  5.  
  6. Syntax
  7.    nistime  [ options ]
  8.  
  9. Description
  10.    This program connects to the daytime service on the NIST time
  11.    server time_a.timefreq.bldrdoc.gov using tcp/ip port 13.  The 
  12.    time server returns the current time which is then compared 
  13.    with the time of the local clock. The difference may be used to 
  14.    adjust the time of the local clock using adjtime (2), and you
  15.    must be the super-user for these adjustments to be performed.
  16.  
  17. Options  (note that upper and lower case letters are distinct)
  18.  
  19.    -m0        Do not display the received time message.  Only the 
  20.         time difference in seconds is written to the standard
  21.         output.  A positive value for the difference means 
  22.         that the local clock is fast with respect to NIST.
  23.  
  24.    -m1 or -M    Display short time messages.
  25.  
  26.    -m2        Display longer time messages.
  27.  
  28.    -s0        Do not set the local clock.
  29.  
  30.    -s1 or -S    Set the local clock if the server is healthy.
  31.  
  32.    -s2        Set the local clock even if the server is not healthy.
  33.  
  34.    -s3        Query operator before setting the clock. 
  35.  
  36.     If no options are used, the default is -M -s3, but these
  37. defaults may be changed by editing the source code and changing 
  38. the values assigned to integers msg and set.  The local clock will
  39. not be adjusted if the measured time difference is 0.
  40.  
  41. Message Format
  42.  
  43.     The message received from NIST is shown below:
  44.  
  45.                         D  L
  46.  MJD  YY MM DD HH MM SS ST S H  Adv.
  47. 49010 93-01-23 22:01:22 00 0 0  50.0 UTC(NIST) * 
  48.  
  49.  
  50. The heading is not part of the message and is shown only
  51. to identify the parameters.  The first number is the date 
  52. expressed as a Modified Julian Day number (MJD), and the next 
  53. 6 values give the Universal Coordinated date and time (formerly 
  54. called Greenwich Mean Time) as year, month, day, hour, minute and 
  55. second.
  56.  
  57.     The eighth number is the daylight saving time flag, DST.
  58. It is based on the continental US system, which has transitions on
  59. the first Sunday in April and the last Sunday in October.
  60.  
  61. DST =  0 means standard time is currently in effect.
  62. DST = 50 means daylight saving time is currently in effect.
  63. DST = 51 means the transition from standard time to daylight time is
  64.          at 2am local time today.
  65. DST =  1 means the transition from daylight time to standard time is
  66.          at 2am local time today.
  67.  
  68. DST > 51 gives advance notice of the number of days to the transition 
  69.          to daylight time.  The DST parameter is decremented at 0000 
  70.          every day during this advance notice period, and the transition
  71.      will occur when the parameter reaches 51 as discussed above.
  72.  
  73. 1 < DST < 50  gives advance notice of the number of days to the 
  74.               transition to standard time.  The DST parameter is 
  75.               decremented at 0000 every day during this advance 
  76.               notice period, and the transition will occur when the
  77.               parameter reaches 1 as discussed above.
  78.  
  79.     The DST parameter is usually not needed for UNIX systems which 
  80. keep time internally using Universal Time. 
  81.  
  82.     The next number is the leap second flag, LS.
  83.  
  84. LS = 0 means no leap second is scheduled.
  85.  
  86. LS = 1 means that a leap second is to be added as 23:59:60 on the
  87.        last day of the current month.  The last minute will therefore
  88.        be 61 seconds long. Leap seconds are usually added at the end
  89.        of either June or December.
  90.  
  91. LS = 2 means that second 23:59:59 is to be dropped on the last day of 
  92.        the current month.  The second following 23:59:58 will be 00:00:00
  93.        of the next day.  This minute will therefore be 59 seconds 
  94.        long.  This situation is unlikely to be necessary in the
  95.        foreseeable future.
  96.  
  97.     Note that leap seconds are inserted or deleted at the specified
  98. Universal Times, while daylight savings transitions are always with
  99. respect to local time.
  100.         
  101.     The health parameter, H, gives the health of the server:
  102.  
  103. H = 0 means that the server is healthy.
  104.  
  105. H = 1 means that the server is operating properly but that its
  106.       time may be in error by up to 5 seconds. This state should
  107.       change to fully healthy within 10 minutes.
  108.  
  109. H = 2 means that the server is operating properly but that its
  110.       time is known to be wrong by more than 5 seconds.  
  111.  
  112. H = 3 means that the hardware or software have failed and that the
  113.       time error is unknown.
  114.  
  115.     The advance parameter, ADV, gives the time advance of the
  116. transmissions, in milliseconds.  Each time packet is sent out early
  117. by this amount to compensate (approximately) for the network delay.
  118.  
  119.     The remaining characters on the line identify the time 
  120. source and are included for compatibility with the ACTS time
  121. system.
  122.  
  123. Restrictions
  124.  
  125.     The local time is expected to be given as a number of 
  126.     seconds since 1 January 1970.
  127.  
  128. Bugs
  129.  
  130.     This version does not estimate the transmission delay 
  131.     in the network.  This is unlikely to be a limitation
  132.     over short distances since the time difference is  
  133.     rounded to the nearest second anyway.
  134.  
  135.     The adjtime function operates very slowly, and large
  136.     adjustments may take a considerable time to complete.
  137.     The slew rate is system dependent and is typically a
  138.     few percent of real time so that times on the order of
  139.     minutes may be needed to adjust the time by 1 second.
  140.  
  141.     Some implementations of the adjtime function may have 
  142.     a problem if the magnitude of the adjustment exceeds 
  143.     about 2100 seconds; the adjustment may be in the wrong 
  144.     direction in this case.  This is true whether the local
  145.     clock is fast or slow.  Large adjustments should be
  146.     performed manually using the date command or using
  147.     this routine several times.
  148.  
  149. Files
  150.     tcp_time_client.c    source code for main program.
  151.     sw.c            switch parser.
  152.     Makefile        compile and link commands.
  153.  
  154.  
  155. See also:
  156.     adjtime (2)
  157.  
  158. Last Modified: 8 December 1993
  159.