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 27, 2018 at 05:13:11 PM by AutoGen 5.18.5
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
60 and the leap indicator is decoded and displayed.
62 This section was generated by @strong{AutoGen},
63 using the @code{agtexi-cmd} template and the option descriptions for the @code{sntp} program.
64 This software is released under the NTP license, <http://ntp.org/license>.
67 * sntp usage:: sntp help/usage (@option{--help})
68 * sntp ipv4:: ipv4 option (-4)
69 * sntp ipv6:: ipv6 option (-6)
70 * sntp authentication:: authentication option (-a)
71 * sntp broadcast:: broadcast option (-b)
72 * sntp concurrent:: concurrent option (-c)
73 * sntp gap:: gap option (-g)
74 * sntp kod:: kod option (-K)
75 * sntp keyfile:: keyfile option (-k)
76 * sntp logfile:: logfile option (-l)
77 * sntp steplimit:: steplimit option (-M)
78 * sntp ntpversion:: ntpversion option (-o)
79 * sntp usereservedport:: usereservedport option (-r)
80 * sntp timeout:: timeout option (-t)
81 * sntp wait:: wait option
82 * sntp config:: presetting/configuring sntp
83 * sntp exit status:: exit status
85 * sntp Authors:: Authors
89 @subsection sntp help/usage (@option{--help})
92 This is the automatically generated usage text for sntp.
94 The text printed is the same whether selected with the @code{help} option
95 (@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print
96 the usage text by passing it through a pager program.
97 @code{more-help} is disabled on platforms without a working
98 @code{fork(2)} function. The @code{PAGER} environment variable is
99 used to select the program, defaulting to @file{more}. Both will exit
100 with a status code of 0.
104 sntp - standard Simple Network Time Protocol client program - Ver. 4.2.7p245
105 USAGE: sntp [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... \
106 [ hostname-or-IP ...]
107 Flg Arg Option-Name Description
108 -4 no ipv4 Force IPv4 DNS name resolution
109 - prohibits these options:
111 -6 no ipv6 Force IPv6 DNS name resolution
112 - prohibits these options:
114 -a Num authentication Enable authentication with the key @@var@{auth-keynumber@}
115 -B Num bctimeout The number of seconds to wait for broadcasts
116 -b Str broadcast Listen to the address specified for broadcast time sync
117 - may appear multiple times
118 -c Str concurrent Concurrently query all IPs returned for host-name
119 - may appear multiple times
120 -d no debug-level Increase debug verbosity level
121 - may appear multiple times
122 -D Str set-debug-level Set the debug verbosity level
123 - may appear multiple times
124 -g Num gap The gap (in milliseconds) between time requests
125 -K Fil kod KoD history filename
126 -k Fil keyfile Look in this file for the key specified with @@option@{-a@}
127 -l Fil logfile Log to specified logfile
128 -M Num steplimit Adjustments less than @@var@{steplimit@} msec will be slewed
129 - It must be in the range:
130 greater than or equal to 0
131 -o Num ntpversion Send @@var@{int@} as our NTP version
132 - It must be in the range:
134 -r no usereservedport Use the NTP Reserved Port (port 123)
135 -S no step OK to 'step' the time with @@command@{settimeofday(2)@}
136 -s no slew OK to 'slew' the time with @@command@{adjtime(2)@}
137 -u Num uctimeout The number of seconds to wait for unicast responses
138 no wait Wait for pending replies (if not setting the time)
139 - disabled as --no-wait
141 opt version Output version information and exit
142 -? no help Display extended usage information and exit
143 -! no more-help Extended usage information passed thru pager
144 -> opt save-opts Save the option state to a config file
145 -< Str load-opts Load options from a config file
146 - disabled as --no-load-opts
147 - may appear multiple times
149 Options are specified by doubled hyphens and their name or by a single
150 hyphen and the flag character.
154 The following option preset mechanisms are supported:
155 - reading file $HOME/.ntprc
156 - reading file ./.ntprc
157 - examining environment variables named SNTP_*
159 please send bug reports to: http://bugs.ntp.org, bugs@@ntp.org
164 @subsection ipv4 option (-4)
167 This is the ``force ipv4 dns name resolution'' option.
170 This option has some usage constraints. It:
173 must not appear in combination with any of the following options:
177 Force DNS resolution of the following host names on the command line
178 to the IPv4 namespace.
180 @subsection ipv6 option (-6)
183 This is the ``force ipv6 dns name resolution'' option.
186 This option has some usage constraints. It:
189 must not appear in combination with any of the following options:
193 Force DNS resolution of the following host names on the command line
194 to the IPv6 namespace.
195 @node sntp authentication
196 @subsection authentication option (-a)
197 @cindex sntp-authentication
199 This is the ``enable authentication with the key @var{auth-keynumber}'' option.
200 This option takes a number argument @file{auth-keynumber}.
201 Enable authentication using the key specified in this option's
202 argument. The argument of this option is the @option{keyid}, a
203 number specified in the @option{keyfile} as this key's identifier.
204 See the @option{keyfile} option (@option{-k}) for more details.
206 @subsection broadcast option (-b)
207 @cindex sntp-broadcast
209 This is the ``listen to the address specified for broadcast time sync'' option.
210 This option takes a string argument @file{broadcast-address}.
213 This option has some usage constraints. It:
216 may appear an unlimited number of times.
219 If specified @code{sntp} will listen to the specified address
220 for NTP broadcasts. The default maximum wait time
221 can (and probably should) be modified with @option{-t}.
222 @node sntp concurrent
223 @subsection concurrent option (-c)
224 @cindex sntp-concurrent
226 This is the ``concurrently query all ips returned for host-name'' option.
227 This option takes a string argument @file{host-name}.
230 This option has some usage constraints. It:
233 may appear an unlimited number of times.
236 Requests from an NTP "client" to a "server" should never be sent
237 more rapidly than one every 2 seconds. By default, any IPs returned
238 as part of a DNS lookup are assumed to be for a single instance of
239 @code{ntpd}, and therefore @code{sntp} will send queries to these IPs
240 one after another, with a 2-second gap in between each query.
242 The @option{-c} or @option{--concurrent} flag says that any IPs
243 returned for the DNS lookup of the supplied host-name are on
244 different machines, so we can send concurrent queries.
246 @subsection gap option (-g)
249 This is the ``the gap (in milliseconds) between time requests'' option.
250 This option takes a number argument @file{milliseconds}.
251 Since we're only going to use the first valid response we get and
252 there is benefit to specifying a good number of servers to query,
253 separate the queries we send out by the specified number of
256 @subsection kod option (-K)
259 This is the ``kod history filename'' option.
260 This option takes a file argument @file{file-name}.
261 Specifies the filename to be used for the persistent history of KoD
262 responses received from servers. If the file does not exist, a
263 warning message will be displayed. The file will not be created.
265 @subsection keyfile option (-k)
268 This is the ``look in this file for the key specified with @option{-a}'' option.
269 This option takes a file argument @file{file-name}.
270 This option specifies the keyfile.
271 @code{sntp} will search for the key specified with @option{-a}
272 @file{keyno} in this file. See @command{ntp.keys(5)} for more
275 @subsection logfile option (-l)
278 This is the ``log to specified logfile'' option.
279 This option takes a file argument @file{file-name}.
280 This option causes the client to write log messages to the specified
283 @subsection steplimit option (-M)
284 @cindex sntp-steplimit
286 This is the ``adjustments less than @var{steplimit} msec will be slewed'' option.
287 This option takes a number argument.
288 If the time adjustment is less than @file{steplimit} milliseconds,
289 slew the amount using @command{adjtime(2)}. Otherwise, step the
290 correction using @command{settimeofday(2)}. The default value is 0,
291 which means all adjustments will be stepped. This is a feature, as
292 different situations demand different values.
293 @node sntp ntpversion
294 @subsection ntpversion option (-o)
295 @cindex sntp-ntpversion
297 This is the ``send @var{int} as our ntp protocol version'' option.
298 This option takes a number argument.
299 When sending requests to a remote server, tell them we are running
300 NTP protocol version @file{ntpversion} .
301 @node sntp usereservedport
302 @subsection usereservedport option (-r)
303 @cindex sntp-usereservedport
305 This is the ``use the ntp reserved port (port 123)'' option.
306 Use port 123, which is reserved for NTP, for our network
309 @subsection timeout option (-t)
312 This is the ``the number of seconds to wait for responses'' option.
313 This option takes a number argument @file{seconds}.
314 When waiting for a reply, @code{sntp} will wait the number
315 of seconds specified before giving up. The default should be
316 more than enough for a unicast response. If @code{sntp} is
317 only waiting for a broadcast response a longer timeout is
320 @subsection wait option
323 This is the ``wait for pending replies (if not setting the time)'' option.
326 This option has some usage constraints. It:
329 can be disabled with --no-wait.
331 It is enabled by default.
334 If we are not setting the time, wait for all pending responses.
338 @subsection presetting/configuring sntp
340 Any option that is not marked as @i{not presettable} may be preset by
341 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
342 the options listed above in upper case and segmented with underscores.
343 The @code{SNTP} variable will be tokenized and parsed like
344 the command line. The remaining variables are tested for existence and their
345 values are treated like option arguments.
349 @code{libopts} will search in 2 places for configuration files:
356 The environment variables @code{HOME}, and @code{PWD}
357 are expanded and replaced when @file{sntp} runs.
358 For any of these that are plain files, they are simply processed.
359 For any that are directories, then a file named @file{.ntprc} is searched for
360 within that directory and processed.
362 Configuration files may be in a wide variety of formats.
363 The basic format is an option name followed by a value (argument) on the
364 same line. Values may be separated from the option name with a colon,
365 equal sign or simply white space. Values may be continued across multiple
366 lines by escaping the newline with a backslash.
368 Multiple programs may also share the same initialization file.
369 Common options are collected at the top, followed by program specific
370 segments. The segments are separated by lines like:
380 Do not mix these styles within one configuration file.
382 Compound values and carefully constructed string values may also be
383 specified using XML syntax:
386 <sub-opt>...<...>...</sub-opt>
390 yielding an @code{option-name.sub-opt} string value of
394 @code{AutoOpts} does not track suboptions. You simply note that it is a
395 hierarchicly valued option. @code{AutoOpts} does provide a means for searching
396 the associated name/value pair list (see: optionFindValue).
398 The command line options relating to configuration and/or usage help are:
400 @subsubheading version (-)
402 Print the program version to standard out, optionally with licensing
403 information, then exit 0. The optional argument specifies how much licensing
404 detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument.
405 Only the first letter of the argument is examined:
409 Only print the version. This is the default.
411 Name the copyright usage licensing terms.
413 Print the full copyright usage licensing terms.
416 @node sntp exit status
417 @subsection sntp exit status
419 One of the following exit values will be returned:
421 @item 0 (EXIT_SUCCESS)
422 Successful program execution.
423 @item 1 (EXIT_FAILURE)
424 The operation failed or the command syntax was not valid.
425 @item 66 (EX_NOINPUT)
426 A specified configuration file could not be loaded.
427 @item 70 (EX_SOFTWARE)
428 libopts had an internal operational error. Please report
429 it to autogen-users@@lists.sourceforge.net. Thank you.
432 @subsection sntp Usage
434 @subsection sntp Authors