home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / nistime2.zip / nistime.man < prev    next >
Text File  |  2001-11-02  |  6KB  |  150 lines
  1. Name
  2.    nistime -- compare time of local clock with a NIST time server
  3.               and optionally adjust the local clock.
  4. Syntax
  5.    nistime  [ options ] [ server ]
  6.  
  7. Description
  8.    This program connects to the daytime service on a NIST time server
  9.    using tcp/ip port 13.  The time server returns the current time
  10.    which is then compared with the time of the local clock.
  11.    The difference may be used to adjust the time of the local clock.
  12.  
  13.    NISTIME uses the timezone information set in the TZ variable to 
  14.    convert from UTC to local time.  Copy the value from one of your 
  15.    UNIX systems or create form "set TZ=CST6CDT" where the 6 represents
  16.    number of hours from UTC (6 for Central Time in the US).  Default
  17.    if no TZ is set is EST5EDT, Eastern Standard Time.
  18.  
  19.    The optional 'server' command-line argument specifies an alternate
  20.    time server to use, in place of the default.  It may be given as
  21.    either a host name or a (dotted-decimal) IP address.
  22.  
  23. Options
  24.  
  25.    -dnnn        Maximum network delay.  If the round-trip network delay
  26.                 is greater than nnn milliseconds, the packet is ignored.
  27.                 Default value is 250 msec.
  28.  
  29.    -m0        Do not display the received time message.  Only the 
  30.         time difference in seconds is written to the standard
  31.         output.  A positive value for the difference means 
  32.         that the local clock is fast with respect to NIST.
  33.  
  34.    -m1 or -M    Display short time messages.
  35.  
  36.    -m2        Display longer time messages.
  37.  
  38.    -s0        Do not set the local clock.
  39.  
  40.    -s1 or -S    Set the local clock if the server is healthy.
  41.  
  42.    -s2        Set the local clock even if the server is not healthy.
  43.  
  44.    -s3        Query operator before setting the clock. 
  45.  
  46. If no options are used, the default is -M -s3. The local clock will
  47. not be adjusted if the measured time difference is less than 0.55 sec.
  48.  
  49. Message Format
  50.  
  51.         The message received from NIST is shown below:
  52.  
  53.                         D  L
  54.  MJD  YY MM DD HH MM SS ST S H  Adv.
  55. 49010 93-01-23 22:01:22 00 0 0  50.0 UTC(NIST) * 
  56.  
  57.  
  58. The heading is not part of the message and is shown only to identify the
  59. parameters.  The first number is the date expressed as a Modified Julian Day
  60. number (MJD), and the next 6 values give the Universal Coordinated date and
  61. time (formerly called Greenwich Mean Time) as year, month, day, hour, minute
  62. and second.
  63.  
  64. The eighth number is the daylight saving time flag, DST.
  65. It is based on the continental US system, which has transitions on
  66. the first Sunday in April and the last Sunday in October.
  67.  
  68. DST =  0 means standard time is currently in effect.
  69. DST = 50 means daylight saving time is currently in effect.
  70. DST = 51 means the transition from standard time to daylight time is
  71.          at 2am local time today.
  72. DST =  1 means the transition from daylight time to standard time is
  73.          at 2am local time today.
  74.  
  75. DST > 51 gives advance notice of the number of days to the transition 
  76.          to daylight time.  The DST parameter is decremented at 0000 
  77.          every day during this advance notice period, and the transition
  78.      will occur when the parameter reaches 51 as discussed above.
  79.  
  80. 1 < DST < 50  gives advance notice of the number of days to the 
  81.               transition to standard time.  The DST parameter is 
  82.               decremented at 0000 every day during this advance 
  83.               notice period, and the transition will occur when the
  84.               parameter reaches 1 as discussed above.
  85.  
  86. The DST parameter is usually not needed for UNIX systems which 
  87. keep time internally using Universal Time. 
  88.  
  89. The next number is the leap second flag, LS.
  90.  
  91. LS = 0 means no leap second is scheduled.
  92.  
  93. LS = 1 means that a leap second is to be added as 23:59:60 on the
  94.        last day of the current month.  The last minute will therefore
  95.        be 61 seconds long. Leap seconds are usually added at the end
  96.        of either June or December.
  97.  
  98. LS = 2 means that second 23:59:59 is to be dropped on the last day of 
  99.        the current month.  The second following 23:59:58 will be 00:00:00
  100.        of the next day.  This minute will therefore be 59 seconds 
  101.        long.  This situation is unlikely to be necessary in the
  102.        foreseeable future.
  103.  
  104.     Note that leap seconds are inserted or deleted at the specified
  105.         Universal Times, while daylight savings transitions are always 
  106.         with respect to local time.
  107.         
  108. The health parameter, H, gives the health of the server:
  109.  
  110.   H = 0 means that the server is healthy.
  111.  
  112.   H = 1 means that the server is operating properly but that its
  113.         time may be in error by up to 5 seconds. This state should
  114.         change to fully healthy within 10 minutes.
  115.  
  116.   H = 2 means that the server is operating properly but that its
  117.         time is known to be wrong by more than 5 seconds.  
  118.  
  119.   H = 3 means that the hardware or software have failed and that the
  120.         time error is unknown.
  121.  
  122.     The advance parameter, ADV, gives the time advance of the
  123.         transmissions, in milliseconds.  Each time packet is sent 
  124.         out early by this amount to compensate (approximately) for
  125.         the network delay.
  126.  
  127.     The remaining characters on the line identify the time 
  128.         source and are included for compatibility with the ACTS 
  129.         time system.
  130.  
  131. Restrictions
  132.  
  133.     The local time is expected to be given as a number of 
  134.     seconds since 1 January 1970.
  135.  
  136. Bugs
  137.  
  138.         The local time is set to the nearest half-second (+/- 0.5 sec.)
  139.         even though the NIST time message allows for better precision.
  140.         This is because the OS/2 DosSetDateTime API will not set the
  141.         local clock to fractional seconds.
  142.  
  143.         The time is instantaneously reset using DosSetDateTime.  If 
  144.         the local clock was ahead of the standard, then time will be
  145.         momentarily non-monotonic.  This has the potential to screw
  146.         up file timestamps used in makefiles.  I don't think it is
  147.         worth the effort to create the equivalent of adjtime (2) to
  148.         avoid this problem.
  149.  
  150.