From: Harlan Stenn Date: Sat, 20 Aug 2011 02:51:43 +0000 (+0000) Subject: sntp documentation and behavior improvements suggested by Steven Sommars X-Git-Tag: NTP_4_2_7P206~1^2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=380e9fcc5ae24b88ce0c65eb52657110c26641a9;p=thirdparty%2Fntp.git sntp documentation and behavior improvements suggested by Steven Sommars bk: 4e4f213fNbAAuHLi0gfkr6hawHO9aQ --- diff --git a/ChangeLog b/ChangeLog index f0e8dcf20..9cc1967b7 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,5 @@ +* sntp documentation and behavior improvements suggested by + Steven Sommars. * Have sntp report synchronization distance instead of root dispersion. * Clean up ntp-wait-opts.def . (4.2.7p205) 2011/08/19 Released by Harlan Stenn diff --git a/sntp/sntp-opts.def b/sntp/sntp-opts.def index 99984531f..8bfb05734 100644 --- a/sntp/sntp-opts.def +++ b/sntp/sntp-opts.def @@ -6,7 +6,7 @@ autogen definitions options; #include copyright.def prog-name = "sntp"; -prog-title = "standard Simple Network Time Protocol program"; +prog-title = "standard Simple Network Time Protocol client program"; argument = '[ hostname-or-IP ...]'; #include homerc.def @@ -97,12 +97,12 @@ flag = { Requests from an NTP "client" to a "server" should never be sent more rapidly than one every 2 seconds. By default, any IPs returned as part of a DNS lookup are assumed to be for a single instance of - ntpd, and therefore @code{sntp} will send queries to these IPs one after - another, with a 2-second gap in between each query. + ntpd, and therefore @code{sntp} will send queries to these IPs one + after another, with a 2-second gap in between each query. - The -c or --concurrent flag says that any IPs returned for the DNS - lookup of the supplied host-name are on different machines, so we - can send concurrent queries. + The @code{-c} or @code{--concurrent} flag says that any IPs + returned for the DNS lookup of the supplied host-name are on + different machines, so we can send concurrent queries. _EndOfDoc_; }; @@ -144,17 +144,17 @@ flag = { arg-name = "file-name"; doc = <<- _EndOfDoc_ This option specifies the keyfile. - @code{sntp} will search for the key specified with -a keyno in this - file. Key files follow the following format: + @code{sntp} will search for the key specified with @code{-a} + @file{keyno} in this file. Key files follow the following format: - keyid keytype key + @file{keyid keytype key} - Where keyid is a number identifying this key - keytype is one of the following: - S Key is a 64 Bit hexadecimal number as specified in in the DES specification. - N Key is a 64 Bit hexadecimal number as specified in the NTP standard. - A Key is a 1-to-8 character ASCII string. - M Key is a 1-to-8 character ASCII string using the MD5 authentication scheme. + Where @file{keyid} is a number identifying this key + @file{keytype} is one of the following: + @code{S} Key is a 64 Bit hexadecimal number as specified in in the DES specification. + @code{N} Key is a 64 Bit hexadecimal number as specified in the NTP standard. + @code{A} Key is a 1-to-8 character ASCII string. + @code{M} Key is a 1-to-8 character ASCII string using the MD5 authentication scheme. For more information see ntp.keys(5). _EndOfDoc_; @@ -168,7 +168,7 @@ flag = { descrip = "Log to specified logfile"; doc = <<- _EndOfDoc_ This option causes the client to write log messages to the specified - logfile. + @file{logfile}. _EndOfDoc_; }; @@ -177,11 +177,11 @@ flag = { value = M; arg-type = number; arg-range = "0->"; - descrip = "Adjustments less than steplimit msec will be slewed"; + descrip = "Adjustments less than @file{steplimit} msec will be slewed"; doc = <<- _EndOfDoc_ - If the time adjustment is less than steplimit milliseconds, slew the - amount using adjtime(). Otherwise, step the correction using - settimeofday(). + If the time adjustment is less than @file{steplimit} milliseconds, + slew the amount using adjtime(2). Otherwise, step the correction + using settimeofday(2). _EndOfDoc_; }; @@ -194,7 +194,7 @@ flag = { arg-range = "0->7"; doc = <<- _EndOfDoc_ When sending requests to a remote server, tell them we are running - NTP protocol version . + NTP protocol version @file{ntpversion} . _EndOfDoc_; }; @@ -211,7 +211,7 @@ flag = { flag = { name = step; value = S; - descrip = "OK to 'step' the time with settimeofday()"; + descrip = "OK to 'step' the time with settimeofday(2)"; doc = <<- _EndOfDoc_ _EndOfDoc_; }; @@ -219,7 +219,7 @@ flag = { flag = { name = slew; value = s; - descrip = "OK to 'slew' the time with adjtime()"; + descrip = "OK to 'slew' the time with adjtime(2)"; doc = <<- _EndOfDoc_ _EndOfDoc_; }; @@ -260,7 +260,7 @@ doc-section = { .Nm can be used as an SNTP client to query a NTP or SNTP server and either display the time or set the local system's time (given suitable privilege). It can be -run as an interactive command or in a +run as an interactive command or from a .Ic cron job. @@ -271,21 +271,36 @@ are defined and described by RFC 5905. The default is to write the estimated correct local date and time (i.e. not UTC) to the standard output in a format like: -.Ic "'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 secs'" +.Ic "'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 [host] IP sN'" where the .Ic "'(+0800)'" means that to get to UTC from the reported local time one must add 8 hours and 0 minutes, -and the -.Ic "'+4.567 +/- 0.089 secs'" +the +.Ic "'+4.567'" indicates the local clock is 4.567 seconds behind the correct time -(so 4.567 seconds must be added to the local clock to get it to be correct), -and the date/time of -'1996-10-15 20:17:25.123' -is believed to be correct to within -+/- 0.089 -seconds. +(so 4.567 seconds must be added to the local clock to get it to be correct). +Note that the number of decimals printed for this value will change +based on the reported precision of the server. +.Ic "'+/- 0.089'" +is the reported +.Em synchronization distance +(in seconds), which represents the maximum error due to all causes. +If the server does not report valid data needed to calculate the +synchronization distance, this will be reported as +.Ic "'+/- ?'" . +If the +.Em host +is different from the +.Em IP , +both will be displayed. +Otherwise, only the +.Em IP +is displayed. +Finally, the +.Em stratum +of the host is reported. _END_PROG_MDOC_DESCRIP; }; @@ -304,20 +319,35 @@ are defined and described by RFC 5905. The default is to write the estimated correct local date and time (i.e. not UTC) to the standard output in a format like @example -1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 secs +1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 [host] IP sN @end example where the @example -+4.567 +/- 0.089 secs +(+0800) +@end example +means that to get to UTC from the reported local time one must +add 8 hours and 0 minutes, +the +@example ++4.567 @end example indicates the local clock is 4.567 seconds behind the correct time -(so 4.567 seconds must be added to the local clock to get it to be correct), -and the (local) time of -@code{1996-10-15 20:17:25.123} -can be converted to UTC time by adding 8 hours and 0 minutes, and -is believed to be correct to within -@code{+/- 0.089} -seconds. +(so 4.567 seconds must be added to the local clock to get it to be correct). +Note that the number of decimals printed for this value will change +based on the reported precision of the server. +@example ++/- 0.089 +@end example +is the reported @file{synchronization distance} (in seconds), +which represents the maximum error due to all causes. +If the server does not report valid data needed to calculate the +synchronization distance, this will be reported as +@example ++/- ? +@end example +If the @file{host} is different from the @file{IP}, both will be displayed. +Otherwise, only the @file{IP} is displayed. +Finally, the @file{stratum} is reported. _END_PROG_INFO_DESCRIP; doc-section = {