4 @cindex standard NTP query program
7 # EDIT THIS FILE WITH CAUTION (invoke-ntpq.texi)
9 # It has been AutoGen-ed August 14, 2018 at 08:30:02 AM by AutoGen 5.18.5
10 # From the definitions ntpq-opts.def
11 # and the template file agtexi-cmd.tpl
17 utility program is used to query NTP servers to monitor NTP operations
18 and performance, requesting
19 information about current state and/or changes in that state.
20 The program may be run either in interactive mode or controlled using
21 command line arguments.
22 Requests to read and write arbitrary
23 variables can be assembled, with raw and pretty-printed output
24 options being available.
27 utility can also obtain and print a
28 list of peers in a common format by sending multiple queries to the
31 If one or more request options is included on the command line
34 is executed, each of the requests will be sent
35 to the NTP servers running on each of the hosts given as command
36 line arguments, or on localhost by default.
40 will attempt to read commands from the
41 standard input and execute these on the NTP server running on the
42 first host given on the command line, again defaulting to localhost
43 when no other host is specified.
46 utility will prompt for
47 commands if the standard input is a terminal device.
50 uses NTP mode 6 packets to communicate with the
51 NTP server, and hence can be used to query any compatible server on
52 the network which permits it.
53 Note that since NTP is a UDP protocol
54 this communication will be somewhat unreliable, especially over
55 large distances in terms of network topology.
59 one attempt to retransmit requests, and will time requests out if
60 the remote host is not heard from within a suitable timeout
63 Note that in contexts where a host name is expected, a
65 qualifier preceding the host name forces resolution to the IPv4
68 qualifier forces resolution to the IPv6 namespace.
69 For examples and usage, see the
70 @quotedblleft{}NTP Debugging Techniques@quotedblright{}
74 command line option other than
79 cause the specified query (queries) to be sent to the indicated
84 interactive format commands from the standard input.
86 @subsubsection Internal Commands
88 Interactive format commands consist of a keyword followed by zero
90 Only enough characters of the full keyword to
91 uniquely identify the command need be typed.
94 number of interactive format commands are executed entirely within
97 utility itself and do not result in NTP
98 requests being sent to a server.
99 These are described following.
101 @item @code{?} @code{[@kbd{command}]}
102 @item @code{help} @code{[@kbd{command}]}
104 @quoteleft{}?@quoteright{}
105 by itself will print a list of all the commands
109 @quoteleft{}?@quoteright{}
110 followed by a command name will print function and usage
111 information about the command.
112 @item @code{addvars} @kbd{name}@code{[=@kbd{value}]}@code{[,...]}
113 @item @code{rmvars} @kbd{name}@code{[,...]}
114 @item @code{clearvars}
115 @item @code{showvars}
116 The arguments to this command consist of a list of
118 @kbd{name}@code{[=@kbd{value}]},
121 is ignored, and can be omitted,
122 in requests to the server to read variables.
125 utility maintains an internal list in which data to be included in
126 messages can be assembled, and displayed or set using the
130 commands described below.
133 command allows variables and their optional values to be added to
135 If more than one variable is to be added, the list should
136 be comma-separated and not contain white space.
139 command can be used to remove individual variables from the list,
142 command removes all variables from the
146 command displays the current list of optional variables.
147 @item @code{authenticate} @code{[@code{yes}|@code{no}]}
150 does not authenticate requests unless
151 they are write requests.
153 @code{authenticate} @code{yes}
156 to send authentication with all requests it
158 Authenticated requests causes some servers to handle
159 requests slightly differently.
164 to display whether or not
165 it is currently authenticating requests.
167 Causes output from query commands to be "cooked", so that
168 variables which are recognized by
171 values reformatted for human consumption.
174 could not decode completely are
175 marked with a trailing
176 @quoteleft{}?@quoteright{}.
177 @item @code{debug} @code{[@code{more}|@code{less}|@code{off}]}
178 With no argument, displays the current debug level.
179 Otherwise, the debugging level is changed as indicated.
180 @item @code{delay} @code{[@kbd{milliseconds}]}
181 Specify a time interval to be added to timestamps included in
182 requests which require authentication.
183 This is used to enable
184 (unreliable) server reconfiguration over long delay network paths
185 or between machines whose clocks are unsynchronized.
187 server does not now require timestamps in authenticated requests,
188 so this command may be obsolete.
189 Without any arguments, displays the current delay.
190 @item @code{drefid} @code{[@code{hash}|@code{ipv4}]}
191 Display refids as IPv4 or hash.
192 Without any arguments, displays whether refids are shown as IPv4
197 @item @code{host} @code{[@kbd{name}]}
198 Set the host to which future queries will be sent.
201 may be either a host name or a numeric address.
202 Without any arguments, displays the current host.
203 @item @code{hostnames} @code{[@code{yes}|@code{no}]}
206 is specified, host names are printed in
207 information displays.
210 is specified, numeric
211 addresses are printed instead.
215 modified using the command line
218 Without any arguments, displays whether host names or numeric addresses
220 @item @code{keyid} @code{[@kbd{keyid}]}
221 This command allows the specification of a key number to be
222 used to authenticate configuration requests.
226 key number the server has been configured to use for this
228 Without any arguments, displays the current
230 @item @code{keytype} @code{[@kbd{digest}]}
231 Specify the digest algorithm to use for authenticating requests, with default
235 was built with OpenSSL support, and OpenSSL is installed,
237 can be any message digest algorithm supported by OpenSSL.
238 If no argument is given, the current
239 @code{keytype} @kbd{digest}
240 algorithm used is displayed.
241 @item @code{ntpversion} @code{[@code{1}|@code{2}|@code{3}|@code{4}]}
242 Sets the NTP version number which
246 Defaults to 3, and note that mode 6 control messages (and
247 modes, for that matter) didn't exist in NTP version 1.
249 to be no servers left which demand version 1.
250 With no argument, displays the current NTP version that will be used
251 when communicating with servers.
253 This command prompts you to type in a password (which will not
254 be echoed) which will be used to authenticate configuration
256 The password must correspond to the key configured for
257 use by the NTP server for this purpose if such requests are to be
259 @item @code{poll} @code{[@kbd{n}]} @code{[@code{verbose}]}
260 Poll an NTP server in client mode
263 Poll not implemented yet.
268 Causes all output from query commands is printed as received
269 from the remote server.
270 The only formating/interpretation done on
271 the data is to transform nonascii data into a printable (but barely
272 understandable) form.
273 @item @code{timeout} @code{[@kbd{milliseconds}]}
274 Specify a timeout period for responses to server queries.
276 default is about 5000 milliseconds.
277 Without any arguments, displays the current timeout period.
280 retries each query once after a timeout, the total waiting time for
281 a timeout will be twice the timeout value set.
283 Display the version of the
288 @subsubsection Control Message Commands
289 Association ids are used to identify system, peer and clock variables.
290 System variables are assigned an association id of zero and system name
291 space, while each association is assigned a nonzero association id and
293 Most control commands send a single message to the server and expect a
294 single response message.
295 The exceptions are the
297 command, which sends a series of messages,
302 commands, which iterate over a range of associations.
305 Display a list of peers in the form:
307 [tally]remote refid assid st t when pool reach delay offset jitter
309 where the output is just like the
311 command except that the
313 is displayed in hex format and the association number is also displayed.
314 @item @code{associations}
315 Display a list of mobilized associations in the form:
317 ind assid status conf reach auth condition last_event cnt
320 @item Sy Variable Ta Sy Description
321 @item @code{ind} @code{Ta} @code{index} @code{on} @code{this} @code{list}
322 @item @code{assid} @code{Ta} @code{association} @code{id}
323 @item @code{status} @code{Ta} @code{peer} @code{status} @code{word}
324 @item @code{conf} @code{Ta} @code{yes}: @code{No} @code{persistent,} @code{no}: @code{No} @code{ephemeral}
325 @item @code{reach} @code{Ta} @code{yes}: @code{No} @code{reachable,} @code{no}: @code{No} @code{unreachable}
326 @item @code{auth} @code{Ta} @code{ok}, @code{yes}, @code{bad} @code{No} @code{and} @code{none}
327 @item @code{condition} @code{Ta} @code{selection} @code{status} @code{(see} @code{the} @code{select} @code{No} @code{field} @code{of} @code{the} @code{peer} @code{status} @code{word)}
328 @item @code{last_event} @code{Ta} @code{event} @code{report} @code{(see} @code{the} @code{event} @code{No} @code{field} @code{of} @code{the} @code{peer} @code{status} @code{word)}
329 @item @code{cnt} @code{Ta} @code{event} @code{count} @code{(see} @code{the} @code{count} @code{No} @code{field} @code{of} @code{the} @code{peer} @code{status} @code{word)}
331 @item @code{authinfo}
332 Display the authentication statistics counters:
333 time since reset, stored keys, free keys, key lookups, keys not found,
334 uncached keys, expired keys, encryptions, decryptions.
335 @item @code{clocklist} @code{[@kbd{associd}]}
336 @item @code{cl} @code{[@kbd{associd}]}
337 Display all clock variables in the variable list for those associations
338 supporting a reference clock.
339 @item @code{clockvar} @code{[@kbd{associd}]} @code{[@kbd{name}@code{[=@kbd{value}]}]}@code{[,...]}
340 @item @code{cv} @code{[@kbd{associd}]} @code{[@kbd{name}@code{[=@kbd{value}]}]}@code{[,...]}
341 Display a list of clock variables for those associations supporting a
343 @item @code{:config} @kbd{configuration command line}
344 Send the remainder of the command line, including whitespace, to the
345 server as a run-time configuration command in the same format as a line
346 in the configuration file.
347 This command is experimental until further notice and clarification.
348 Authentication is of course required.
349 @item @code{config-from-file} @kbd{filename}
352 to the server as run-time configuration commands in the same format as
353 lines in the configuration file.
354 This command is experimental until further notice and clarification.
355 Authentication is required.
357 Display status and statistics counters for each local network interface address:
358 interface number, interface name and address or broadcast, drop, flag,
359 ttl, mc, received, sent, send failed, peers, uptime.
360 Authentication is required.
362 Display network and reference clock I/O statistics:
363 time since reset, receive buffers, free receive buffers, used receive buffers,
364 low water refills, dropped packets, ignored packets, received packets,
365 packets sent, packet send failures, input wakeups, useful input wakeups.
366 @item @code{kerninfo}
367 Display kernel loop and PPS statistics:
368 associd, status, pll offset, pll frequency, maximum error,
369 estimated error, kernel status, pll time constant, precision,
370 frequency tolerance, pps frequency, pps stability, pps jitter,
371 calibration interval, calibration cycles, jitter exceeded,
372 stability exceeded, calibration errors.
373 As with other ntpq output, times are in milliseconds; very small values
374 may be shown as exponentials.
375 The precision value displayed is in milliseconds as well, unlike the
376 precision system variable.
377 @item @code{lassociations}
378 Perform the same function as the associations command, except display
379 mobilized and unmobilized associations, including all clients.
380 @item @code{lopeers} @code{[@code{-4}|@code{-6}]}
381 Display a list of all peers and clients showing
383 (associated with the given IP version).
384 @item @code{lpassociations}
385 Display the last obtained list of associations, including all clients.
386 @item @code{lpeers} @code{[@code{-4}|@code{-6}]}
387 Display a list of all peers and clients (associated with the given IP version).
388 @item @code{monstats}
389 Display monitor facility status, statistics, and limits:
390 enabled, addresses, peak addresses, maximum addresses,
391 reclaim above count, reclaim older than, kilobytes, maximum kilobytes.
392 @item @code{mreadlist} @kbd{associdlo} @kbd{associdhi}
393 @item @code{mrl} @kbd{associdlo} @kbd{associdhi}
394 Perform the same function as the
396 command for a range of association ids.
397 @item @code{mreadvar} @kbd{associdlo} @kbd{associdhi} @code{[@kbd{name}]}@code{[,...]}
398 This range may be determined from the list displayed by any
399 command showing associations.
400 @item @code{mrv} @kbd{associdlo} @kbd{associdhi} @code{[@kbd{name}]}@code{[,...]}
401 Perform the same function as the
403 command for a range of association ids.
404 This range may be determined from the list displayed by any
405 command showing associations.
406 @item @code{mrulist} @code{[@code{limited} | @code{kod} | @code{mincount}=@kbd{count} | @code{laddr}=@kbd{localaddr} | @code{sort}=@code{[-]}@kbd{sortorder} | @code{resany}=@kbd{hexmask} | @code{resall}=@kbd{hexmask}]}
407 Display traffic counts of the most recently seen source addresses
408 collected and maintained by the monitor facility.
409 With the exception of
410 @code{sort}=@code{[-]}@kbd{sortorder},
411 the options filter the list returned by
417 options return only entries representing client addresses from which the
418 last packet received triggered either discarding or a KoD response.
420 @code{mincount}=@kbd{count}
421 option filters entries representing less than
425 @code{laddr}=@kbd{localaddr}
426 option filters entries for packets received on any local address other than
428 @code{resany}=@kbd{hexmask}
430 @code{resall}=@kbd{hexmask}
431 filter entries containing none or less than all, respectively, of the bits in
433 which must begin with
444 or any of those preceded by
445 @quoteleft{}-@quoteright{}
446 to reverse the sort order.
447 The output columns are:
452 Interval in seconds between the receipt of the most recent packet from
453 this address and the completion of the retrieval of the MRU list by
456 Average interval in s between packets from this address.
458 Restriction flags associated with this address.
459 Most are copied unchanged from the matching
461 command, however 0x400 (kod) and 0x20 (limited) flags are cleared unless
462 the last packet from this address triggered a rate control response.
464 Rate control indicator, either
469 for no rate control response,
470 rate limiting by discarding, or rate limiting with a KoD response, respectively.
474 Packet version number.
476 Packets received from this address.
478 Source port of last packet from this address.
479 @item @code{remote} @code{address}
480 host or DNS name, numeric address, or address followed by
481 claimed DNS name which could not be verified in parentheses.
483 @item @code{opeers} @code{[@code{-4} | @code{-6}]}
484 Obtain and print the old-style list of all peers and clients showing
486 (associated with the given IP version),
489 @item @code{passociations}
490 Perform the same function as the
493 except that it uses previously stored data rather than making a new query.
495 Display a list of peers in the form:
497 [tally]remote refid st t when pool reach delay offset jitter
503 single-character code indicating current value of the
506 .Lk decode.html#peer "peer status word"
508 host name (or IP number) of peer.
509 The value displayed will be truncated to 15 characters unless the
512 option is given, in which case the full value will be displayed
513 on the first line, and if too long,
514 the remaining data will be displayed on the next line.
517 .Lk decode.html#kiss "'kiss code"
519 stratum: 0 for local reference clocks, 1 for servers with local
520 reference clocks, ..., 16 for unsynchronized server clocks
523 unicast or manycast client,
525 broadcast or multicast client,
529 local (reference clock),
539 time in seconds, minutes, hours, or days since the last packet
541 @quoteleft{}-@quoteright{}
542 if a packet has never been received
546 reach shift register (octal)
550 offset of server relative to this host
552 offset RMS error estimate.
554 @item @code{pstats} @kbd{associd}
555 Display the statistics for the peer with the given
557 associd, status, remote host, local address, time last received,
558 time until next send, reachability change, packets sent,
559 packets received, bad authentication, bogus origin, duplicate,
560 bad dispersion, bad reference time, candidate order.
561 @item @code{readlist} @code{[@kbd{associd}]}
562 @item @code{rl} @code{[@kbd{associd}]}
563 Display all system or peer variables.
566 is omitted, it is assumed to be zero.
567 @item @code{readvar} @code{[@kbd{associd} @kbd{name}@code{[=@kbd{value}]} @code{[, ...]}]}
568 @item @code{rv} @code{[@kbd{associd} @kbd{name}@code{[=@kbd{value}]} @code{[, ...]}]}
569 Display the specified system or peer variables.
572 is zero, the variables are from the
573 @ref{System Variables}
574 name space, otherwise they are from the
579 is required, as the same name can occur in both spaces.
582 is included, all operative variables in the name space are displayed.
583 In this case only, if the
585 is omitted, it is assumed to be zero.
586 Multiple names are specified with comma separators and without whitespace.
587 Note that time values are represented in milliseconds
588 and frequency values in parts-per-million (PPM).
589 Some NTP timestamps are represented in the format
590 @kbd{YYYY}@kbd{MM} @kbd{DD} @kbd{TTTT},
601 Display the access control (restrict) list for
603 Authentication is required.
604 @item @code{saveconfig} @kbd{filename}
605 Save the current configuration,
606 including any runtime modifications made by
609 @code{config-from-file},
610 to the NTP server host file
612 This command will be rejected by the server unless
613 .Lk miscopt.html#saveconfigdir "saveconfigdir"
620 format specifiers to substitute the current date and time, for
623 @code{saveconfig} @file{ntp-%Y%m%d-%H%M%S.conf}.
625 The filename used is stored in system variable
627 Authentication is required.
629 Display system operational summary:
630 associd, status, system peer, system peer mode, leap indicator,
631 stratum, log2 precision, root delay, root dispersion,
632 reference id, reference time, system jitter, clock jitter,
633 clock wander, broadcast delay, symm. auth. delay.
634 @item @code{sysstats}
635 Display system uptime and packet counts maintained in the
637 uptime, sysstats reset, packets received, current version,
638 older version, bad length or format, authentication failed,
639 declined, restricted, rate limited, KoD responses,
641 @item @code{timerstats}
642 Display interval timer counters:
643 time since reset, timer overruns, calls to transmit.
644 @item @code{writelist} @kbd{associd}
645 Set all system or peer variables included in the variable list.
646 @item @code{writevar} @kbd{associd} @kbd{name}=@kbd{value} @code{[, ...]}
647 Set the specified variables in the variable list.
650 is zero, the variables are from the
651 @ref{System Variables}
652 name space, otherwise they are from the
657 is required, as the same name can occur in both spaces.
658 Authentication is required.
661 @subsubsection Status Words and Kiss Codes
662 The current state of the operating program is shown
663 in a set of status words
664 maintained by the system.
665 Status information is also available on a per-association basis.
666 These words are displayed by the
670 commands both in hexadecimal and in decoded short tip strings.
671 The codes, tips and short explanations are documented on the
672 .Lk decode.html "Event Messages and Status Words"
674 The page also includes a list of system and peer messages,
675 the code for the latest of which is included in the status word.
677 Information resulting from protocol machine state transitions
678 is displayed using an informal set of ASCII strings called
679 .Lk decode.html#kiss "kiss codes" .
680 The original purpose was for kiss-o'-death (KoD) packets
681 sent by the server to advise the client of an unusual condition.
682 They are now displayed, when appropriate,
683 in the reference identifier field in various billboards.
685 @subsubsection System Variables
686 The following system variables appear in the
689 Not all variables are displayed in some configurations.
695 .Lk decode.html#sys "system status word"
697 NTP software version and build time
698 @item @code{processor}
699 hardware platform and version
701 operating system and version
703 leap warning indicator (0-3)
706 @item @code{precision}
708 @item @code{rootdelay}
709 total roundtrip delay to the primary reference clock
710 @item @code{rootdisp}
711 total dispersion to the primary reference clock
714 .Lk decode.html#kiss "kiss code"
720 system peer association id
722 time constant and poll exponent (log2 s) (3-17)
724 minimum time constant (log2 s) (3-10)
726 combined offset of server relative to this host
727 @item @code{frequency}
728 frequency drift (PPM) relative to hardware clock
729 @item @code{sys_jitter}
730 combined system jitter
731 @item @code{clk_wander}
732 clock frequency wander (PPM)
733 @item @code{clk_jitter}
738 NTP seconds when the next leap second is/was inserted
740 NTP seconds when the NIST leapseconds file expires
742 The jitter and wander statistics are exponentially-weighted RMS averages.
743 The system jitter is defined in the NTPv4 specification;
744 the clock jitter statistic is computed by the clock discipline module.
746 When the NTPv4 daemon is compiled with the OpenSSL software library,
747 additional system variables are displayed,
748 including some or all of the following,
749 depending on the particular Autokey dance:
754 Autokey host name for this host
756 Autokey group name for this host
758 host flags (see Autokey specification)
760 OpenSSL message digest algorithm
761 @item @code{signature}
762 OpenSSL digest/signature scheme
764 NTP seconds at last signature update
766 certificate subject, issuer and certificate flags
768 NTP seconds when the certificate expires
770 @subsubsection Peer Variables
771 The following peer variables appear in the
773 billboard for each association.
774 Not all variables are displayed in some configurations.
782 .Lk decode.html#peer "peer status word"
784 source (remote) IP address
788 destination (local) IP address
790 destination (local) port
795 @item @code{precision}
797 @item @code{rootdelay}
798 total roundtrip delay to the primary reference clock
799 @item @code{rootdisp}
800 total root dispersion to the primary reference clock
803 .Lk decode.html#kiss "kiss code"
807 last packet received time
809 reach register (octal)
817 host poll exponent (log2 s) (3-17)
819 peer poll exponent (log2 s) (3-17)
822 .Lk rate.html "Rate Management and the Kiss-o'-Death Packet" )
824 .Lk decode.html#flash "flash status word"
831 @item @code{dispersion}
836 unicast/broadcast bias
838 interleave delay (see
839 .Lk xleave.html "NTP Interleaved Modes" )
843 variable is calculated when the first broadcast packet is received
844 after the calibration volley.
845 It represents the offset of the broadcast subgraph relative to the
849 variable appears only for the interleaved symmetric and interleaved modes.
850 It represents the internal queuing, buffering and transmission delays
851 for the preceding packet.
853 When the NTPv4 daemon is compiled with the OpenSSL software library,
854 additional peer variables are displayed, including the following:
859 peer flags (see Autokey specification)
863 peer flags (see Autokey specification)
864 @item @code{signature}
865 OpenSSL digest/signature scheme
866 @item @code{initsequence}
870 @item @code{timestamp}
871 Autokey signature timestamp
873 Autokey group name for this association
876 @subsubsection Clock Variables
877 The following clock variables appear in the
879 billboard for each association with a reference clock.
880 Not all variables are displayed in some configurations.
887 .Lk decode.html#clock "clock status word"
890 @item @code{timecode}
891 ASCII time code string (specific to device)
896 @item @code{badformat}
900 @item @code{fudgetime1}
902 @item @code{fudgetime2}
912 This section was generated by @strong{AutoGen},
913 using the @code{agtexi-cmd} template and the option descriptions for the @code{ntpq} program.
914 This software is released under the NTP license, <http://ntp.org/license>.
917 * ntpq usage:: ntpq help/usage (@option{--help})
918 * ntpq ipv4:: ipv4 option (-4)
919 * ntpq ipv6:: ipv6 option (-6)
920 * ntpq command:: command option (-c)
921 * ntpq interactive:: interactive option (-i)
922 * ntpq numeric:: numeric option (-n)
923 * ntpq old-rv:: old-rv option
924 * ntpq peers:: peers option (-p)
925 * ntpq refid:: refid option (-r)
926 * ntpq wide:: wide option (-w)
927 * ntpq config:: presetting/configuring ntpq
928 * ntpq exit status:: exit status
932 @subsection ntpq help/usage (@option{--help})
935 This is the automatically generated usage text for ntpq.
937 The text printed is the same whether selected with the @code{help} option
938 (@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print
939 the usage text by passing it through a pager program.
940 @code{more-help} is disabled on platforms without a working
941 @code{fork(2)} function. The @code{PAGER} environment variable is
942 used to select the program, defaulting to @file{more}. Both will exit
943 with a status code of 0.
947 ntpq - standard NTP query program - Ver. 4.2.8p12
948 Usage: ntpq [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... [ host ...]
949 Flg Arg Option-Name Description
950 -4 no ipv4 Force IPv4 name resolution
951 - prohibits the option 'ipv6'
952 -6 no ipv6 Force IPv6 name resolution
953 - prohibits the option 'ipv4'
954 -c Str command run a command and exit
955 - may appear multiple times
956 -d no debug-level Increase debug verbosity level
957 - may appear multiple times
958 -D Num set-debug-level Set the debug verbosity level
959 - may appear multiple times
960 -i no interactive Force ntpq to operate in interactive mode
961 - prohibits these options:
964 -n no numeric numeric host addresses
965 no old-rv Always output status line with readvar
966 -p no peers Print a list of the peers
967 - prohibits the option 'interactive'
968 -r KWd refid Set default display type for S2+ refids
969 -w no wide Display the full 'remote' value
970 opt version output version information and exit
971 -? no help display extended usage information and exit
972 -! no more-help extended usage information passed thru pager
973 -> opt save-opts save the option state to a config file
974 -< Str load-opts load options from a config file
975 - disabled as '--no-load-opts'
976 - may appear multiple times
978 Options are specified by doubled hyphens and their name or by a single
979 hyphen and the flag character.
981 The following option preset mechanisms are supported:
982 - reading file $HOME/.ntprc
983 - reading file ./.ntprc
984 - examining environment variables named NTPQ_*
986 The valid "refid" option keywords are:
988 or an integer from 0 through 1
990 Please send bug reports to: <http://bugs.ntp.org, bugs@@ntp.org>
995 @subsection ipv4 option (-4)
998 This is the ``force ipv4 name resolution'' option.
1001 This option has some usage constraints. It:
1004 must not appear in combination with any of the following options:
1008 Force resolution of following host names on the command line
1009 to the IPv4 namespace.
1011 @subsection ipv6 option (-6)
1014 This is the ``force ipv6 name resolution'' option.
1017 This option has some usage constraints. It:
1020 must not appear in combination with any of the following options:
1024 Force resolution of following host names on the command line
1025 to the IPv6 namespace.
1027 @subsection command option (-c)
1028 @cindex ntpq-command
1030 This is the ``run a command and exit'' option.
1031 This option takes a string argument @file{cmd}.
1034 This option has some usage constraints. It:
1037 may appear an unlimited number of times.
1040 The following argument is interpreted as an interactive format command
1041 and is added to the list of commands to be executed on the specified
1043 @node ntpq interactive
1044 @subsection interactive option (-i)
1045 @cindex ntpq-interactive
1047 This is the ``force ntpq to operate in interactive mode'' option.
1050 This option has some usage constraints. It:
1053 must not appear in combination with any of the following options:
1057 Force @code{ntpq} to operate in interactive mode.
1058 Prompts will be written to the standard output and
1059 commands read from the standard input.
1061 @subsection numeric option (-n)
1062 @cindex ntpq-numeric
1064 This is the ``numeric host addresses'' option.
1065 Output all host addresses in dotted-quad numeric format rather than
1066 converting to the canonical host names.
1068 @subsection old-rv option
1071 This is the ``always output status line with readvar'' option.
1072 By default, @code{ntpq} now suppresses the @code{associd=...}
1073 line that precedes the output of @code{readvar}
1074 (alias @code{rv}) when a single variable is requested, such as
1075 @code{ntpq -c "rv 0 offset"}.
1076 This option causes @code{ntpq} to include both lines of output
1077 for a single-variable @code{readvar}.
1078 Using an environment variable to
1079 preset this option in a script will enable both older and
1080 newer @code{ntpq} to behave identically in this regard.
1082 @subsection peers option (-p)
1085 This is the ``print a list of the peers'' option.
1088 This option has some usage constraints. It:
1091 must not appear in combination with any of the following options:
1095 Print a list of the peers known to the server as well as a summary
1096 of their state. This is equivalent to the 'peers' interactive command.
1098 @subsection refid option (-r)
1101 This is the ``set default display type for s2+ refids'' option.
1102 This option takes a keyword argument.
1105 This option has some usage constraints. It:
1108 This option takes a keyword as its argument.
1109 The argument sets an enumeration value that can be tested by comparing the option value macro (OPT_VALUE_REFID).
1110 The available keywords are:
1115 or their numeric equivalent.@end itemize
1117 Set the default display format for S2+ refids.
1119 @subsection wide option (-w)
1122 This is the ``display the full 'remote' value'' option.
1123 Display the full value of the 'remote' value. If this requires
1124 more than 15 characters, display the full value, emit a newline,
1125 and continue the data display properly indented on the next line.
1129 @subsection presetting/configuring ntpq
1131 Any option that is not marked as @i{not presettable} may be preset by
1132 loading values from configuration ("rc" or "ini") files, and values from environment variables named @code{NTPQ} and @code{NTPQ_<OPTION_NAME>}. @code{<OPTION_NAME>} must be one of
1133 the options listed above in upper case and segmented with underscores.
1134 The @code{NTPQ} variable will be tokenized and parsed like
1135 the command line. The remaining variables are tested for existence and their
1136 values are treated like option arguments.
1140 @code{libopts} will search in 2 places for configuration files:
1147 The environment variables @code{HOME}, and @code{PWD}
1148 are expanded and replaced when @file{ntpq} runs.
1149 For any of these that are plain files, they are simply processed.
1150 For any that are directories, then a file named @file{.ntprc} is searched for
1151 within that directory and processed.
1153 Configuration files may be in a wide variety of formats.
1154 The basic format is an option name followed by a value (argument) on the
1155 same line. Values may be separated from the option name with a colon,
1156 equal sign or simply white space. Values may be continued across multiple
1157 lines by escaping the newline with a backslash.
1159 Multiple programs may also share the same initialization file.
1160 Common options are collected at the top, followed by program specific
1161 segments. The segments are separated by lines like:
1171 Do not mix these styles within one configuration file.
1173 Compound values and carefully constructed string values may also be
1174 specified using XML syntax:
1177 <sub-opt>...<...>...</sub-opt>
1181 yielding an @code{option-name.sub-opt} string value of
1185 @code{AutoOpts} does not track suboptions. You simply note that it is a
1186 hierarchicly valued option. @code{AutoOpts} does provide a means for searching
1187 the associated name/value pair list (see: optionFindValue).
1189 The command line options relating to configuration and/or usage help are:
1191 @subsubheading version (-)
1193 Print the program version to standard out, optionally with licensing
1194 information, then exit 0. The optional argument specifies how much licensing
1195 detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument.
1196 Only the first letter of the argument is examined:
1200 Only print the version. This is the default.
1202 Name the copyright usage licensing terms.
1204 Print the full copyright usage licensing terms.
1207 @node ntpq exit status
1208 @subsection ntpq exit status
1210 One of the following exit values will be returned:
1212 @item 0 (EXIT_SUCCESS)
1213 Successful program execution.
1214 @item 1 (EXIT_FAILURE)
1215 The operation failed or the command syntax was not valid.
1216 @item 66 (EX_NOINPUT)
1217 A specified configuration file could not be loaded.
1218 @item 70 (EX_SOFTWARE)
1219 libopts had an internal operational error. Please report
1220 it to autogen-users@@lists.sourceforge.net. Thank you.