4 @cindex standard Simple Network Time Protocol client program
7 # EDIT THIS FILE WITH CAUTION (invoke-sntp.texi)
9 # It has been AutoGen-ed June 2, 2016 at 07:19:58 AM 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.8p8
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 the option 'ipv6'
110 -6 no ipv6 Force IPv6 DNS name resolution
111 - prohibits the option 'ipv4'
112 -a Num authentication Enable authentication with the key auth-keynumber
113 -b Str broadcast Listen to the address specified for broadcast time sync
114 - may appear multiple times
115 -c Str concurrent Concurrently query all IPs returned for host-name
116 - may appear multiple times
117 -d no debug-level Increase debug verbosity level
118 - may appear multiple times
119 -D Num set-debug-level Set the debug verbosity level
120 - may appear multiple times
121 -g Num gap The gap (in milliseconds) between time requests
122 -K Fil kod KoD history filename
123 -k Fil keyfile Look in this file for the key specified with -a
124 -l Fil logfile Log to specified logfile
125 -M Num steplimit Adjustments less than steplimit msec will be slewed
126 - it must be in the range:
127 greater than or equal to 0
128 -o Num ntpversion Send int as our NTP protocol version
129 - it must be in the range:
131 -r no usereservedport Use the NTP Reserved Port (port 123)
132 -S no step OK to 'step' the time with settimeofday(2)
133 -s no slew OK to 'slew' the time with adjtime(2)
134 -t Num timeout The number of seconds to wait for responses
135 no wait Wait for pending replies (if not setting the time)
136 - disabled as '--no-wait'
138 opt version output version information and exit
139 -? no help display extended usage information and exit
140 -! no more-help extended usage information passed thru pager
141 -> opt save-opts save the option state to a config file
142 -< Str load-opts load options from a config file
143 - disabled as '--no-load-opts'
144 - may appear multiple times
146 Options are specified by doubled hyphens and their name or by a single
147 hyphen and the flag character.
150 The following option preset mechanisms are supported:
151 - reading file $HOME/.ntprc
152 - reading file ./.ntprc
153 - examining environment variables named SNTP_*
155 Please send bug reports to: <http://bugs.ntp.org, bugs@@ntp.org>
160 @subsection ipv4 option (-4)
163 This is the ``force ipv4 dns name resolution'' option.
166 This option has some usage constraints. It:
169 must not appear in combination with any of the following options:
173 Force DNS resolution of the following host names on the command line
174 to the IPv4 namespace.
176 @subsection ipv6 option (-6)
179 This is the ``force ipv6 dns name resolution'' option.
182 This option has some usage constraints. It:
185 must not appear in combination with any of the following options:
189 Force DNS resolution of the following host names on the command line
190 to the IPv6 namespace.
191 @node sntp authentication
192 @subsection authentication option (-a)
193 @cindex sntp-authentication
195 This is the ``enable authentication with the key @var{auth-keynumber}'' option.
196 This option takes a number argument @file{auth-keynumber}.
197 Enable authentication using the key specified in this option's
198 argument. The argument of this option is the @option{keyid}, a
199 number specified in the @option{keyfile} as this key's identifier.
200 See the @option{keyfile} option (@option{-k}) for more details.
202 @subsection broadcast option (-b)
203 @cindex sntp-broadcast
205 This is the ``listen to the address specified for broadcast time sync'' option.
206 This option takes a string argument @file{broadcast-address}.
209 This option has some usage constraints. It:
212 may appear an unlimited number of times.
215 If specified @code{sntp} will listen to the specified address
216 for NTP broadcasts. The default maximum wait time
217 can (and probably should) be modified with @option{-t}.
218 @node sntp concurrent
219 @subsection concurrent option (-c)
220 @cindex sntp-concurrent
222 This is the ``concurrently query all ips returned for host-name'' option.
223 This option takes a string argument @file{host-name}.
226 This option has some usage constraints. It:
229 may appear an unlimited number of times.
232 Requests from an NTP "client" to a "server" should never be sent
233 more rapidly than one every 2 seconds. By default, any IPs returned
234 as part of a DNS lookup are assumed to be for a single instance of
235 @code{ntpd}, and therefore @code{sntp} will send queries to these IPs
236 one after another, with a 2-second gap in between each query.
238 The @option{-c} or @option{--concurrent} flag says that any IPs
239 returned for the DNS lookup of the supplied host-name are on
240 different machines, so we can send concurrent queries.
242 @subsection gap option (-g)
245 This is the ``the gap (in milliseconds) between time requests'' option.
246 This option takes a number argument @file{milliseconds}.
247 Since we're only going to use the first valid response we get and
248 there is benefit to specifying a good number of servers to query,
249 separate the queries we send out by the specified number of
252 @subsection kod option (-K)
255 This is the ``kod history filename'' option.
256 This option takes a file argument @file{file-name}.
257 Specifies the filename to be used for the persistent history of KoD
258 responses received from servers. If the file does not exist, a
259 warning message will be displayed. The file will not be created.
261 @subsection keyfile option (-k)
264 This is the ``look in this file for the key specified with @option{-a}'' option.
265 This option takes a file argument @file{file-name}.
266 This option specifies the keyfile.
267 @code{sntp} will search for the key specified with @option{-a}
268 @file{keyno} in this file. See @command{ntp.keys(5)} for more
271 @subsection logfile option (-l)
274 This is the ``log to specified logfile'' option.
275 This option takes a file argument @file{file-name}.
276 This option causes the client to write log messages to the specified
279 @subsection steplimit option (-M)
280 @cindex sntp-steplimit
282 This is the ``adjustments less than @var{steplimit} msec will be slewed'' option.
283 This option takes a number argument.
284 If the time adjustment is less than @file{steplimit} milliseconds,
285 slew the amount using @command{adjtime(2)}. Otherwise, step the
286 correction using @command{settimeofday(2)}. The default value is 0,
287 which means all adjustments will be stepped. This is a feature, as
288 different situations demand different values.
289 @node sntp ntpversion
290 @subsection ntpversion option (-o)
291 @cindex sntp-ntpversion
293 This is the ``send @var{int} as our ntp protocol version'' option.
294 This option takes a number argument.
295 When sending requests to a remote server, tell them we are running
296 NTP protocol version @file{ntpversion} .
297 @node sntp usereservedport
298 @subsection usereservedport option (-r)
299 @cindex sntp-usereservedport
301 This is the ``use the ntp reserved port (port 123)'' option.
302 Use port 123, which is reserved for NTP, for our network
305 @subsection timeout option (-t)
308 This is the ``the number of seconds to wait for responses'' option.
309 This option takes a number argument @file{seconds}.
310 When waiting for a reply, @code{sntp} will wait the number
311 of seconds specified before giving up. The default should be
312 more than enough for a unicast response. If @code{sntp} is
313 only waiting for a broadcast response a longer timeout is
316 @subsection wait option
319 This is the ``wait for pending replies (if not setting the time)'' option.
322 This option has some usage constraints. It:
325 can be disabled with --no-wait.
327 It is enabled by default.
330 If we are not setting the time, wait for all pending responses.
334 @subsection presetting/configuring sntp
336 Any option that is not marked as @i{not presettable} may be preset by
337 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
338 the options listed above in upper case and segmented with underscores.
339 The @code{SNTP} variable will be tokenized and parsed like
340 the command line. The remaining variables are tested for existence and their
341 values are treated like option arguments.
345 @code{libopts} will search in 2 places for configuration files:
352 The environment variables @code{HOME}, and @code{PWD}
353 are expanded and replaced when @file{sntp} runs.
354 For any of these that are plain files, they are simply processed.
355 For any that are directories, then a file named @file{.ntprc} is searched for
356 within that directory and processed.
358 Configuration files may be in a wide variety of formats.
359 The basic format is an option name followed by a value (argument) on the
360 same line. Values may be separated from the option name with a colon,
361 equal sign or simply white space. Values may be continued across multiple
362 lines by escaping the newline with a backslash.
364 Multiple programs may also share the same initialization file.
365 Common options are collected at the top, followed by program specific
366 segments. The segments are separated by lines like:
376 Do not mix these styles within one configuration file.
378 Compound values and carefully constructed string values may also be
379 specified using XML syntax:
382 <sub-opt>...<...>...</sub-opt>
386 yielding an @code{option-name.sub-opt} string value of
390 @code{AutoOpts} does not track suboptions. You simply note that it is a
391 hierarchicly valued option. @code{AutoOpts} does provide a means for searching
392 the associated name/value pair list (see: optionFindValue).
394 The command line options relating to configuration and/or usage help are:
396 @subsubheading version (-)
398 Print the program version to standard out, optionally with licensing
399 information, then exit 0. The optional argument specifies how much licensing
400 detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument.
401 Only the first letter of the argument is examined:
405 Only print the version. This is the default.
407 Name the copyright usage licensing terms.
409 Print the full copyright usage licensing terms.
412 @node sntp exit status
413 @subsection sntp exit status
415 One of the following exit values will be returned:
417 @item 0 (EXIT_SUCCESS)
418 Successful program execution.
419 @item 1 (EXIT_FAILURE)
420 The operation failed or the command syntax was not valid.
421 @item 66 (EX_NOINPUT)
422 A specified configuration file could not be loaded.
423 @item 70 (EX_SOFTWARE)
424 libopts had an internal operational error. Please report
425 it to autogen-users@@lists.sourceforge.net. Thank you.
428 @subsection sntp Usage
430 @subsection sntp Authors