4 @cindex standard Simple Network Time Protocol client program
7 # EDIT THIS FILE WITH CAUTION (invoke-sntp.texi)
9 # It has been AutoGen-ed February 4, 2015 at 02:34:17 AM by AutoGen 5.18.5pre4
10 # From the definitions sntp-opts.def
11 # and the template file agtexi-cmd.tpl
17 can be used as an SNTP client to query a NTP or SNTP server and either display
18 the time or set the local system's time (given suitable privilege). It can be
19 run as an interactive command or from a
23 NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol)
24 are defined and described by RFC 5905.
27 The default is to write the estimated correct local date and time (i.e. not
28 UTC) to the standard output in a format like:
30 @code{'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 [host] IP sN'}
34 means that to get to UTC from the reported local time one must
35 add 8 hours and 0 minutes,
38 indicates the local clock is 4.567 seconds behind the correct time
39 (so 4.567 seconds must be added to the local clock to get it to be correct).
40 Note that the number of decimals printed for this value will change
41 based on the reported precision of the server.
44 @emph{synchronization} @emph{distance}
45 (in seconds), which represents the maximum error due to all causes.
46 If the server does not report valid data needed to calculate the
47 synchronization distance, this will be reported as
53 both will be displayed.
59 of the host is reported.
61 This section was generated by @strong{AutoGen},
62 using the @code{agtexi-cmd} template and the option descriptions for the @code{sntp} program.
63 This software is released under the NTP license, <http://ntp.org/license>.
66 * sntp usage:: sntp help/usage (@option{--help})
67 * sntp ipv4:: ipv4 option (-4)
68 * sntp ipv6:: ipv6 option (-6)
69 * sntp authentication:: authentication option (-a)
70 * sntp broadcast:: broadcast option (-b)
71 * sntp concurrent:: concurrent option (-c)
72 * sntp gap:: gap option (-g)
73 * sntp kod:: kod option (-K)
74 * sntp keyfile:: keyfile option (-k)
75 * sntp logfile:: logfile option (-l)
76 * sntp steplimit:: steplimit option (-M)
77 * sntp ntpversion:: ntpversion option (-o)
78 * sntp usereservedport:: usereservedport option (-r)
79 * sntp timeout:: timeout option (-t)
80 * sntp wait:: wait option
81 * sntp config:: presetting/configuring sntp
82 * sntp exit status:: exit status
84 * sntp Authors:: Authors
88 @subsection sntp help/usage (@option{--help})
91 This is the automatically generated usage text for sntp.
93 The text printed is the same whether selected with the @code{help} option
94 (@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print
95 the usage text by passing it through a pager program.
96 @code{more-help} is disabled on platforms without a working
97 @code{fork(2)} function. The @code{PAGER} environment variable is
98 used to select the program, defaulting to @file{more}. Both will exit
99 with a status code of 0.
103 sntp - standard Simple Network Time Protocol client program - Ver. 4.2.8p1
104 Usage: sntp [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... \
105 [ hostname-or-IP ...]
106 Flg Arg Option-Name Description
107 -4 no ipv4 Force IPv4 DNS name resolution
108 - prohibits the option 'ipv6'
109 -6 no ipv6 Force IPv6 DNS name resolution
110 - prohibits the option 'ipv4'
111 -a Num authentication Enable authentication with the key auth-keynumber
112 -b Str broadcast Listen to the address specified for broadcast time sync
113 - may appear multiple times
114 -c Str concurrent Concurrently query all IPs returned for host-name
115 - may appear multiple times
116 -d no debug-level Increase debug verbosity level
117 - may appear multiple times
118 -D Num set-debug-level Set the debug verbosity level
119 - may appear multiple times
120 -g Num gap The gap (in milliseconds) between time requests
121 -K Fil kod KoD history filename
122 -k Fil keyfile Look in this file for the key specified with -a
123 -l Fil logfile Log to specified logfile
124 -M Num steplimit Adjustments less than steplimit msec will be slewed
125 - it must be in the range:
126 greater than or equal to 0
127 -o Num ntpversion Send int as our NTP protocol version
128 - it must be in the range:
130 -r no usereservedport Use the NTP Reserved Port (port 123)
131 -S no step OK to 'step' the time with settimeofday(2)
132 -s no slew OK to 'slew' the time with adjtime(2)
133 -t Num timeout The number of seconds to wait for responses
134 no wait Wait for pending replies (if not setting the time)
135 - disabled as '--no-wait'
137 opt version output version information and exit
138 -? no help display extended usage information and exit
139 -! no more-help extended usage information passed thru pager
140 -> opt save-opts save the option state to a config file
141 -< Str load-opts load options from a config file
142 - disabled as '--no-load-opts'
143 - may appear multiple times
145 Options are specified by doubled hyphens and their name or by a single
146 hyphen and the flag character.
149 The following option preset mechanisms are supported:
150 - reading file $HOME/.ntprc
151 - reading file ./.ntprc
152 - examining environment variables named SNTP_*
154 Please send bug reports to: <http://bugs.ntp.org, bugs@@ntp.org>
159 @subsection ipv4 option (-4)
162 This is the ``force ipv4 dns name resolution'' option.
165 This option has some usage constraints. It:
168 must not appear in combination with any of the following options:
172 Force DNS resolution of the following host names on the command line
173 to the IPv4 namespace.
175 @subsection ipv6 option (-6)
178 This is the ``force ipv6 dns name resolution'' option.
181 This option has some usage constraints. It:
184 must not appear in combination with any of the following options:
188 Force DNS resolution of the following host names on the command line
189 to the IPv6 namespace.
190 @node sntp authentication
191 @subsection authentication option (-a)
192 @cindex sntp-authentication
194 This is the ``enable authentication with the key @var{auth-keynumber}'' option.
195 This option takes a number argument @file{auth-keynumber}.
196 Enable authentication using the key specified in this option's
197 argument. The argument of this option is the @option{keyid}, a
198 number specified in the @option{keyfile} as this key's identifier.
199 See the @option{keyfile} option (@option{-k}) for more details.
201 @subsection broadcast option (-b)
202 @cindex sntp-broadcast
204 This is the ``listen to the address specified for broadcast time sync'' option.
205 This option takes a string argument @file{broadcast-address}.
208 This option has some usage constraints. It:
211 may appear an unlimited number of times.
214 If specified @code{sntp} will listen to the specified address
215 for NTP broadcasts. The default maximum wait time
216 can (and probably should) be modified with @option{-t}.
217 @node sntp concurrent
218 @subsection concurrent option (-c)
219 @cindex sntp-concurrent
221 This is the ``concurrently query all ips returned for host-name'' option.
222 This option takes a string argument @file{host-name}.
225 This option has some usage constraints. It:
228 may appear an unlimited number of times.
231 Requests from an NTP "client" to a "server" should never be sent
232 more rapidly than one every 2 seconds. By default, any IPs returned
233 as part of a DNS lookup are assumed to be for a single instance of
234 @code{ntpd}, and therefore @code{sntp} will send queries to these IPs
235 one after another, with a 2-second gap in between each query.
237 The @option{-c} or @option{--concurrent} flag says that any IPs
238 returned for the DNS lookup of the supplied host-name are on
239 different machines, so we can send concurrent queries.
241 @subsection gap option (-g)
244 This is the ``the gap (in milliseconds) between time requests'' option.
245 This option takes a number argument @file{milliseconds}.
246 Since we're only going to use the first valid response we get and
247 there is benefit to specifying a good number of servers to query,
248 separate the queries we send out by the specified number of
251 @subsection kod option (-K)
254 This is the ``kod history filename'' option.
255 This option takes a file argument @file{file-name}.
256 Specifies the filename to be used for the persistent history of KoD
257 responses received from servers. If the file does not exist, a
258 warning message will be displayed. The file will not be created.
260 @subsection keyfile option (-k)
263 This is the ``look in this file for the key specified with @option{-a}'' option.
264 This option takes a file argument @file{file-name}.
265 This option specifies the keyfile.
266 @code{sntp} will search for the key specified with @option{-a}
267 @file{keyno} in this file. See @command{ntp.keys(5)} for more
270 @subsection logfile option (-l)
273 This is the ``log to specified logfile'' option.
274 This option takes a file argument @file{file-name}.
275 This option causes the client to write log messages to the specified
278 @subsection steplimit option (-M)
279 @cindex sntp-steplimit
281 This is the ``adjustments less than @var{steplimit} msec will be slewed'' option.
282 This option takes a number argument.
283 If the time adjustment is less than @file{steplimit} milliseconds,
284 slew the amount using @command{adjtime(2)}. Otherwise, step the
285 correction using @command{settimeofday(2)}. The default value is 0,
286 which means all adjustments will be stepped. This is a feature, as
287 different situations demand different values.
288 @node sntp ntpversion
289 @subsection ntpversion option (-o)
290 @cindex sntp-ntpversion
292 This is the ``send @var{int} as our ntp protocol version'' option.
293 This option takes a number argument.
294 When sending requests to a remote server, tell them we are running
295 NTP protocol version @file{ntpversion} .
296 @node sntp usereservedport
297 @subsection usereservedport option (-r)
298 @cindex sntp-usereservedport
300 This is the ``use the ntp reserved port (port 123)'' option.
301 Use port 123, which is reserved for NTP, for our network
304 @subsection timeout option (-t)
307 This is the ``the number of seconds to wait for responses'' option.
308 This option takes a number argument @file{seconds}.
309 When waiting for a reply, @code{sntp} will wait the number
310 of seconds specified before giving up. The default should be
311 more than enough for a unicast response. If @code{sntp} is
312 only waiting for a broadcast response a longer timeout is
315 @subsection wait option
318 This is the ``wait for pending replies (if not setting the time)'' option.
321 This option has some usage constraints. It:
324 can be disabled with --no-wait.
326 It is enabled by default.
329 If we are not setting the time, wait for all pending responses.
333 @subsection presetting/configuring sntp
335 Any option that is not marked as @i{not presettable} may be preset by
336 loading values from configuration ("rc" or "ini") files, and values from environment variables named @code{SNTP} and @code{SNTP_<OPTION_NAME>}. @code{<OPTION_NAME>} must be one of
337 the options listed above in upper case and segmented with underscores.
338 The @code{SNTP} variable will be tokenized and parsed like
339 the command line. The remaining variables are tested for existence and their
340 values are treated like option arguments.
344 @code{libopts} will search in 2 places for configuration files:
351 The environment variables @code{HOME}, and @code{PWD}
352 are expanded and replaced when @file{sntp} runs.
353 For any of these that are plain files, they are simply processed.
354 For any that are directories, then a file named @file{.ntprc} is searched for
355 within that directory and processed.
357 Configuration files may be in a wide variety of formats.
358 The basic format is an option name followed by a value (argument) on the
359 same line. Values may be separated from the option name with a colon,
360 equal sign or simply white space. Values may be continued across multiple
361 lines by escaping the newline with a backslash.
363 Multiple programs may also share the same initialization file.
364 Common options are collected at the top, followed by program specific
365 segments. The segments are separated by lines like:
375 Do not mix these styles within one configuration file.
377 Compound values and carefully constructed string values may also be
378 specified using XML syntax:
381 <sub-opt>...<...>...</sub-opt>
385 yielding an @code{option-name.sub-opt} string value of
389 @code{AutoOpts} does not track suboptions. You simply note that it is a
390 hierarchicly valued option. @code{AutoOpts} does provide a means for searching
391 the associated name/value pair list (see: optionFindValue).
393 The command line options relating to configuration and/or usage help are:
395 @subsubheading version (-)
397 Print the program version to standard out, optionally with licensing
398 information, then exit 0. The optional argument specifies how much licensing
399 detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument.
400 Only the first letter of the argument is examined:
404 Only print the version. This is the default.
406 Name the copyright usage licensing terms.
408 Print the full copyright usage licensing terms.
411 @node sntp exit status
412 @subsection sntp exit status
414 One of the following exit values will be returned:
416 @item 0 (EXIT_SUCCESS)
417 Successful program execution.
418 @item 1 (EXIT_FAILURE)
419 The operation failed or the command syntax was not valid.
420 @item 66 (EX_NOINPUT)
421 A specified configuration file could not be loaded.
422 @item 70 (EX_SOFTWARE)
423 libopts had an internal operational error. Please report
424 it to autogen-users@@lists.sourceforge.net. Thank you.
427 @subsection sntp Usage
429 @subsection sntp Authors