4 @cindex standard NTP query program
7 # EDIT THIS FILE WITH CAUTION (invoke-ntpq.texi)
9 # It has been AutoGen-ed June 2, 2016 at 07:37:46 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 which
18 implement the standard NTP mode 6 control message formats defined
19 in Appendix B of the NTPv3 specification RFC1305, requesting
20 information about current state and/or changes in that state.
21 The same formats are used in NTPv4, although some of the
22 variables have changed and new ones added. The description on this
23 page is for the NTPv4 variables.
24 The program may be run either in interactive mode or controlled using
25 command line arguments.
26 Requests to read and write arbitrary
27 variables can be assembled, with raw and pretty-printed output
28 options being available.
31 utility can also obtain and print a
32 list of peers in a common format by sending multiple queries to the
35 If one or more request options is included on the command line
38 is executed, each of the requests will be sent
39 to the NTP servers running on each of the hosts given as command
40 line arguments, or on localhost by default.
44 will attempt to read commands from the
45 standard input and execute these on the NTP server running on the
46 first host given on the command line, again defaulting to localhost
47 when no other host is specified.
50 utility will prompt for
51 commands if the standard input is a terminal device.
54 uses NTP mode 6 packets to communicate with the
55 NTP server, and hence can be used to query any compatible server on
56 the network which permits it.
57 Note that since NTP is a UDP protocol
58 this communication will be somewhat unreliable, especially over
59 large distances in terms of network topology.
63 one attempt to retransmit requests, and will time requests out if
64 the remote host is not heard from within a suitable timeout
68 command line option other than
73 cause the specified query (queries) to be sent to the indicated
78 interactive format commands from the standard input.
79 @subsubsection Internal Commands
80 Interactive format commands consist of a keyword followed by zero
82 Only enough characters of the full keyword to
83 uniquely identify the command need be typed.
86 number of interactive format commands are executed entirely within
89 utility itself and do not result in NTP mode 6
90 requests being sent to a server.
91 These are described following.
93 @item @code{?} @code{[@kbd{command_keyword}]}
94 @item @code{help} @code{[@kbd{command_keyword}]}
96 @quoteleft{}?@quoteright{}
97 by itself will print a list of all the command
98 keywords known to this incarnation of
101 @quoteleft{}?@quoteright{}
102 followed by a command keyword will print function and usage
103 information about the command.
104 This command is probably a better
105 source of information about
109 @item @code{addvars} @kbd{variable_name}@code{[@code{=value}]} @code{...}
110 @item @code{rmvars} @kbd{variable_name} @code{...}
111 @item @code{clearvars}
112 @item @code{showvars}
113 The data carried by NTP mode 6 messages consists of a list of
115 @quoteleft{}variable_name=value@quoteright{},
117 @quoteleft{}=value@quoteright{}
118 is ignored, and can be omitted,
119 in requests to the server to read variables.
122 utility maintains an internal list in which data to be included in control
123 messages can be assembled, and sent using the
127 commands described below.
130 command allows variables and their optional values to be added to
132 If more than one variable is to be added, the list should
133 be comma-separated and not contain white space.
136 command can be used to remove individual variables from the list,
139 command removes all variables from the
143 command displays the current list of optional variables.
144 @item @code{authenticate} @code{[yes | no]}
147 does not authenticate requests unless
148 they are write requests.
150 @quoteleft{}authenticate yes@quoteright{}
153 to send authentication with all requests it
155 Authenticated requests causes some servers to handle
156 requests slightly differently, and can occasionally melt the CPU in
157 fuzzballs if you turn authentication on before doing a
161 @quoteleft{}authenticate@quoteright{}
164 to display whether or not
166 is currently autheinticating requests.
168 Causes output from query commands to be "cooked", so that
169 variables which are recognized by
172 values reformatted for human consumption.
175 thinks should have a decodable value but didn't are
176 marked with a trailing
177 @quoteleft{}?@quoteright{}.
178 @item @code{debug} @code{[@code{more} | @code{less} | @code{off}]}
179 With no argument, displays the current debug level.
180 Otherwise, the debug level is changed to the indicated level.
181 @item @code{delay} @kbd{milliseconds}
182 Specify a time interval to be added to timestamps included in
183 requests which require authentication.
184 This is used to enable
185 (unreliable) server reconfiguration over long delay network paths
186 or between machines whose clocks are unsynchronized.
188 server does not now require timestamps in authenticated requests,
189 so this command may be obsolete.
193 @item @code{host} @kbd{hostname}
194 Set the host to which future queries will be sent.
196 may be either a host name or a numeric address.
197 @item @code{hostnames} @code{[@code{yes} | @code{no}]}
200 is specified, host names are printed in
201 information displays.
204 is specified, numeric
205 addresses are printed instead.
209 modified using the command line
212 @item @code{keyid} @kbd{keyid}
213 This command allows the specification of a key number to be
214 used to authenticate configuration requests.
218 key number the server has been configured to use for this
220 @item @code{keytype} @code{[@code{md5} | @code{OpenSSLDigestType}]}
221 Specify the type of key to use for authenticating requests.
226 was built with OpenSSL support,
227 any digest type supported by OpenSSL can also be provided.
228 If no argument is given, the current
231 @item @code{ntpversion} @code{[@code{1} | @code{2} | @code{3} | @code{4}]}
232 Sets the NTP version number which
236 Defaults to 3, and note that mode 6 control messages (and
237 modes, for that matter) didn't exist in NTP version 1.
239 to be no servers left which demand version 1.
240 With no argument, displays the current NTP version that will be used
241 when communicating with servers.
243 This command prompts you to type in a password (which will not
244 be echoed) which will be used to authenticate configuration
246 The password must correspond to the key configured for
247 use by the NTP server for this purpose if such requests are to be
256 Causes all output from query commands is printed as received
257 from the remote server.
258 The only formating/interpretation done on
259 the data is to transform nonascii data into a printable (but barely
260 understandable) form.
261 @item @code{timeout} @kbd{milliseconds}
262 Specify a timeout period for responses to server queries.
264 default is about 5000 milliseconds.
267 retries each query once after a timeout, the total waiting time for
268 a timeout will be twice the timeout value set.
270 Print the version of the
275 @subsubsection Control Message Commands
276 Association IDs are used to identify system, peer and clock variables.
277 System variables are assigned an association ID of zero and system name space, while each association is assigned a nonzero association ID and peer namespace.
278 Most control commands send a single mode-6 message to the server and expect a single response message.
279 The exceptions are the
281 command, which sends a series of messages,
286 commands, which iterate over a range of associations.
288 @item @code{associations}
289 Display a list of mobilized associations in the form:
291 ind assid status conf reach auth condition last_event cnt
294 @item Sy String Ta Sy Description
295 @item @code{ind} @code{Ta} @code{index} @code{on} @code{this} @code{list}
296 @item @code{assid} @code{Ta} @code{association} @code{ID}
297 @item @code{status} @code{Ta} @code{peer} @code{status} @code{word}
298 @item @code{conf} @code{Ta} @code{yes}: @code{persistent,} @code{no}: @code{ephemeral}
299 @item @code{reach} @code{Ta} @code{yes}: @code{reachable,} @code{no}: @code{unreachable}
300 @item @code{auth} @code{Ta} @code{ok}, @code{yes}, @code{bad} @code{and} @code{none}
301 @item @code{condition} @code{Ta} @code{selection} @code{status} @code{(see} @code{the} @code{select} @code{field} @code{of} @code{the} @code{peer} @code{status} @code{word)}
302 @item @code{last_event} @code{Ta} @code{event} @code{report} @code{(see} @code{the} @code{event} @code{field} @code{of} @code{the} @code{peer} @code{status} @code{word)}
303 @item @code{cnt} @code{Ta} @code{event} @code{count} @code{(see} @code{the} @code{count} @code{field} @code{of} @code{the} @code{peer} @code{status} @code{word)}
305 @item @code{authinfo}
306 Display the authentication statistics.
307 @item @code{clockvar} @kbd{assocID} @code{[@kbd{name}@code{[@code{=}@kbd{value}]}]} @code{[...]}
308 @item @code{cv} @kbd{assocID} @code{[@kbd{name}@code{[@code{=}@kbd{value}]}]} @code{[...]}
309 Display a list of clock variables for those associations supporting a reference clock.
310 @item @code{:config} @code{[...]}
311 Send the remainder of the command line, including whitespace, to the server as a run-time configuration command in the same format as a line in the configuration file. This command is experimental until further notice and clarification. Authentication is of course required.
312 @item @code{config-from-file} @kbd{filename}
313 Send the each line of
315 to the server as run-time configuration commands in the same format as a line in the configuration file. This command is experimental until further notice and clarification. Authentication is required.
317 Display statistics for each local network address. Authentication is required.
319 Display network and reference clock I/O statistics.
320 @item @code{kerninfo}
321 Display kernel loop and PPS statistics. As with other ntpq output, times are in milliseconds. The precision value displayed is in milliseconds as well, unlike the precision system variable.
322 @item @code{lassociations}
323 Perform the same function as the associations command, except display mobilized and unmobilized associations.
324 @item @code{lopeers} @code{[@code{-4} | @code{-6}]}
325 Obtain and print a list of all peers and clients showing
327 (associated with any given IP version).
328 @item @code{lpeers} @code{[@code{-4} | @code{-6}]}
329 Print a peer spreadsheet for the appropriate IP version(s).
331 (associated with any given IP version).
332 @item @code{monstats}
333 Display monitor facility statistics.
334 @item @code{mrulist} @code{[@code{limited} | @code{kod} | @code{mincount}=@kbd{count} | @code{laddr}=@kbd{localaddr} | @code{sort}=@kbd{sortorder} | @code{resany}=@kbd{hexmask} | @code{resall}=@kbd{hexmask}]}
335 Obtain and print traffic counts collected and maintained by the monitor facility.
336 With the exception of
337 @code{sort}=@kbd{sortorder},
338 the options filter the list returned by
344 options return only entries representing client addresses from which the last packet received triggered either discarding or a KoD response.
346 @code{mincount}=@kbd{count}
347 option filters entries representing less than
351 @code{laddr}=@kbd{localaddr}
352 option filters entries for packets received on any local address other than
354 @code{resany}=@kbd{hexmask}
356 @code{resall}=@kbd{hexmask}
357 filter entries containing none or less than all, respectively, of the bits in
359 which must begin with
370 or any of those preceded by a minus sign (hyphen) to reverse the sort order.
371 The output columns are:
376 Interval in s between the receipt of the most recent packet from this address and the completion of the retrieval of the MRU list by
379 Average interval in s between packets from this address.
381 Restriction flags associated with this address.
382 Most are copied unchanged from the matching
384 command, however 0x400 (kod) and 0x20 (limited) flags are cleared unless the last packet from this address triggered a rate control response.
386 Rate control indicator, either
391 for no rate control response,
392 rate limiting by discarding, or rate limiting with a KoD response, respectively.
396 Packet version number.
398 Packets received from this address.
400 Source port of last packet from this address.
401 @item @code{remote} @code{address}
402 DNS name, numeric address, or address followed by
403 claimed DNS name which could not be verified in parentheses.
405 @item @code{mreadvar} @code{assocID} @code{assocID} @code{[@kbd{variable_name}@code{[=@kbd{value}]} ...]}
406 @item @code{mrv} @code{assocID} @code{assocID} @code{[@kbd{variable_name}@code{[=@kbd{value}]} ...]}
407 Perform the same function as the
409 command, except for a range of association IDs.
410 This range is determined from the association list cached by the most recent
413 @item @code{opeers} @code{[@code{-4} | @code{-6}]}
414 Obtain and print the old-style list of all peers and clients showing
416 (associated with any given IP version),
419 @item @code{passociations}
420 Perform the same function as the
423 except that it uses previously stored data rather than making a new query.
425 Display a list of peers in the form:
427 [tally]remote refid st t when pool reach delay offset jitter
433 single-character code indicating current value of the
436 .Lk decode.html#peer "peer status word"
438 host name (or IP number) of peer.
439 The value displayed will be truncated to 15 characters unless the
441 flag is given, in which case the full value will be displayed
443 and the remaining data is displayed on the next line.
446 .Lk decode.html#kiss "'kiss code"
451 unicast or manycast client,
453 broadcast or multicast client,
455 local (reference clock),
465 sec/min/hr since last received packet
467 poll interval (log2 s)
469 reach shift register (octal)
473 offset of server relative to this host
478 Display a list of peers in the form:
480 [tally]remote refid assid st t when pool reach delay offset jitter
482 where the output is just like the
484 command except that the
486 is displayed in hex format and the association number is also displayed.
487 @item @code{pstats} @kbd{assocID}
488 Show the statistics for the peer with the given
490 @item @code{readlist} @kbd{assocID}
491 @item @code{rl} @kbd{assocID}
492 Read the system or peer variables included in the variable list.
493 @item @code{readvar} @kbd{assocID} @kbd{name}@code{[=@kbd{value}]} @code{[, ...]}
494 @item @code{rv} @kbd{assocID} @kbd{name}@code{[=@kbd{value}]} @code{[, ...]}
495 Display the specified variables.
498 is zero, the variables are from the
499 @ref{System Variables}
500 name space, otherwise they are from the
505 is required, as the same name can occur in both spaces.
508 is included, all operative variables in the name space are displayed.
510 In this case only, if the
512 is omitted, it is assumed zero.
513 Multiple names are specified with comma separators and without whitespace.
514 Note that time values are represented in milliseconds
515 and frequency values in parts-per-million (PPM).
516 Some NTP timestamps are represented in the format
518 where YYYY is the year,
519 MM the month of year,
520 DD the day of month and
521 TTTT the time of day.
523 Show the access control (restrict) list for
526 @item @code{saveconfig} @kbd{filename}
527 Write the current configuration,
528 including any runtime modifications given with
531 @code{config-from-file},
532 to the ntpd host's file
534 This command will be rejected by the server unless
535 .Lk miscopt.html#saveconfigdir "saveconfigdir"
542 format specifies to substitute the current date and time, for example,
543 @code{q]saveconfig} @code{ntp-%Y%m%d-%H%M%S.confq]}.
544 The filename used is stored in system variable
546 Authentication is required.
547 @item @code{timerstats}
548 Display interval timer counters.
549 @item @code{writelist} @kbd{assocID}
550 Write the system or peer variables included in the variable list.
551 @item @code{writevar} @kbd{assocID} @kbd{name}=@kbd{value} @code{[, ...]}
552 Write the specified variables.
555 is zero, the variables are from the
556 @ref{System Variables}
557 name space, otherwise they are from the
562 is required, as the same name can occur in both spaces.
564 Display operational summary.
565 @item @code{sysstats}
566 Print statistics counters maintained in the protocol module.
569 @subsubsection Status Words and Kiss Codes
571 The current state of the operating program is shown
572 in a set of status words
573 maintained by the system.
574 Status information is also available on a per-association basis.
575 These words are displayed in the
579 commands both in hexadecimal and in decoded short tip strings.
580 The codes, tips and short explanations are documented on the
581 .Lk decode.html "Event Messages and Status Words"
583 The page also includes a list of system and peer messages,
584 the code for the latest of which is included in the status word.
586 Information resulting from protocol machine state transitions
587 is displayed using an informal set of ASCII strings called
588 .Lk decode.html#kiss "kiss codes" .
589 The original purpose was for kiss-o'-death (KoD) packets
590 sent by the server to advise the client of an unusual condition.
591 They are now displayed, when appropriate,
592 in the reference identifier field in various billboards.
594 @subsubsection System Variables
595 The following system variables appear in the
598 Not all variables are displayed in some configurations.
603 .Lk decode.html#sys "system status word"
605 NTP software version and build time
606 @item @code{processor}
607 hardware platform and version
609 operating system and version
611 leap warning indicator (0-3)
614 @item @code{precision}
616 @item @code{rootdelay}
617 total roundtrip delay to the primary reference clock
618 @item @code{rootdisp}
619 total dispersion to the primary reference clock
621 system peer association ID
623 time constant and poll exponent (log2 s) (3-17)
625 minimum time constant (log2 s) (3-10)
630 .Lk decode.html#kiss "kiss code"
634 combined offset of server relative to this host
635 @item @code{sys_jitter}
636 combined system jitter
637 @item @code{frequency}
638 frequency offset (PPM) relative to hardware clock
639 @item @code{clk_wander}
640 clock frequency wander (PPM)
641 @item @code{clk_jitter}
646 NTP seconds when the next leap second is/was inserted
648 NTP seconds when the NIST leapseconds file expires
650 The jitter and wander statistics are exponentially-weighted RMS averages.
651 The system jitter is defined in the NTPv4 specification;
652 the clock jitter statistic is computed by the clock discipline module.
654 When the NTPv4 daemon is compiled with the OpenSSL software library,
655 additional system variables are displayed,
656 including some or all of the following,
657 depending on the particular Autokey dance:
663 Autokey host name for this host
665 Autokey group name for this host
667 host flags (see Autokey specification)
669 OpenSSL message digest algorithm
670 @item @code{signature}
671 OpenSSL digest/signature scheme
673 NTP seconds at last signature update
675 certificate subject, issuer and certificate flags
677 NTP seconds when the certificate expires
679 @subsubsection Peer Variables
680 The following peer variables appear in the
682 billboard for each association.
683 Not all variables are displayed in some configurations.
691 .Lk decode.html#peer "peer status word"
693 source (remote) IP address
697 destination (local) IP address
699 destination (local) port
704 @item @code{precision}
706 @item @code{rootdelay}
707 total roundtrip delay to the primary reference clock
708 @item @code{rootdisp}
709 total root dispersion to the primary reference clock
712 .Lk decode.html#kiss "kiss code"
716 reach register (octal)
724 host poll exponent (log2 s) (3-17)
726 peer poll exponent (log2 s) (3-17)
729 .Lk rate.html "Rate Management and the Kiss-o'-Death Packet" )
731 .Lk decode.html#flash "flash status word"
736 @item @code{dispersion}
741 Autokey group name for this association
743 unicast/broadcast bias
745 interleave delay (see
746 .Lk xleave.html "NTP Interleaved Modes" )
750 variable is calculated when the first broadcast packet is received
751 after the calibration volley.
752 It represents the offset of the broadcast subgraph relative to the unicast subgraph.
755 variable appears only for the interleaved symmetric and interleaved modes.
756 It represents the internal queuing, buffering and transmission delays
757 for the preceding packet.
759 When the NTPv4 daemon is compiled with the OpenSSL software library,
760 additional peer variables are displayed, including the following:
765 peer flags (see Autokey specification)
769 peer flags (see Autokey specification)
770 @item @code{signature}
771 OpenSSL digest/signature scheme
772 @item @code{initsequence}
776 @item @code{timestamp}
777 Autokey signature timestamp
780 @subsubsection Clock Variables
781 The following clock variables appear in the
783 billboard for each association with a reference clock.
784 Not all variables are displayed in some configurations.
791 .Lk decode.html#clock "clock status word"
794 @item @code{timecode}
795 ASCII time code string (specific to device)
800 @item @code{badformat}
804 @item @code{fudgetime1}
806 @item @code{fudgetime2}
816 This section was generated by @strong{AutoGen},
817 using the @code{agtexi-cmd} template and the option descriptions for the @code{ntpq} program.
818 This software is released under the NTP license, <http://ntp.org/license>.
821 * ntpq usage:: ntpq help/usage (@option{--help})
822 * ntpq ipv4:: ipv4 option (-4)
823 * ntpq ipv6:: ipv6 option (-6)
824 * ntpq command:: command option (-c)
825 * ntpq interactive:: interactive option (-i)
826 * ntpq numeric:: numeric option (-n)
827 * ntpq old-rv:: old-rv option
828 * ntpq peers:: peers option (-p)
829 * ntpq refid:: refid option (-r)
830 * ntpq wide:: wide option (-w)
831 * ntpq config:: presetting/configuring ntpq
832 * ntpq exit status:: exit status
836 @subsection ntpq help/usage (@option{--help})
839 This is the automatically generated usage text for ntpq.
841 The text printed is the same whether selected with the @code{help} option
842 (@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print
843 the usage text by passing it through a pager program.
844 @code{more-help} is disabled on platforms without a working
845 @code{fork(2)} function. The @code{PAGER} environment variable is
846 used to select the program, defaulting to @file{more}. Both will exit
847 with a status code of 0.
851 ntpq - standard NTP query program - Ver. 4.2.8p8
852 Usage: ntpq [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... [ host ...]
853 Flg Arg Option-Name Description
854 -4 no ipv4 Force IPv4 DNS name resolution
855 - prohibits the option 'ipv6'
856 -6 no ipv6 Force IPv6 DNS name resolution
857 - prohibits the option 'ipv4'
858 -c Str command run a command and exit
859 - may appear multiple times
860 -d no debug-level Increase debug verbosity level
861 - may appear multiple times
862 -D Num set-debug-level Set the debug verbosity level
863 - may appear multiple times
864 -i no interactive Force ntpq to operate in interactive mode
865 - prohibits these options:
868 -n no numeric numeric host addresses
869 no old-rv Always output status line with readvar
870 -p no peers Print a list of the peers
871 - prohibits the option 'interactive'
872 -r KWd refid Set default display type for S2+ refids
873 -w no wide Display the full 'remote' value
874 opt version output version information and exit
875 -? no help display extended usage information and exit
876 -! no more-help extended usage information passed thru pager
877 -> opt save-opts save the option state to a config file
878 -< Str load-opts load options from a config file
879 - disabled as '--no-load-opts'
880 - may appear multiple times
882 Options are specified by doubled hyphens and their name or by a single
883 hyphen and the flag character.
885 The following option preset mechanisms are supported:
886 - reading file $HOME/.ntprc
887 - reading file ./.ntprc
888 - examining environment variables named NTPQ_*
890 The valid "refid" option keywords are:
892 or an integer from 0 through 1
894 Please send bug reports to: <http://bugs.ntp.org, bugs@@ntp.org>
899 @subsection ipv4 option (-4)
902 This is the ``force ipv4 dns name resolution'' option.
905 This option has some usage constraints. It:
908 must not appear in combination with any of the following options:
912 Force DNS resolution of following host names on the command line
913 to the IPv4 namespace.
915 @subsection ipv6 option (-6)
918 This is the ``force ipv6 dns name resolution'' option.
921 This option has some usage constraints. It:
924 must not appear in combination with any of the following options:
928 Force DNS resolution of following host names on the command line
929 to the IPv6 namespace.
931 @subsection command option (-c)
934 This is the ``run a command and exit'' option.
935 This option takes a string argument @file{cmd}.
938 This option has some usage constraints. It:
941 may appear an unlimited number of times.
944 The following argument is interpreted as an interactive format command
945 and is added to the list of commands to be executed on the specified
947 @node ntpq interactive
948 @subsection interactive option (-i)
949 @cindex ntpq-interactive
951 This is the ``force ntpq to operate in interactive mode'' option.
954 This option has some usage constraints. It:
957 must not appear in combination with any of the following options:
961 Force @code{ntpq} to operate in interactive mode.
962 Prompts will be written to the standard output and
963 commands read from the standard input.
965 @subsection numeric option (-n)
968 This is the ``numeric host addresses'' option.
969 Output all host addresses in dotted-quad numeric format rather than
970 converting to the canonical host names.
972 @subsection old-rv option
975 This is the ``always output status line with readvar'' option.
976 By default, @code{ntpq} now suppresses the @code{associd=...}
977 line that precedes the output of @code{readvar}
978 (alias @code{rv}) when a single variable is requested, such as
979 @code{ntpq -c "rv 0 offset"}.
980 This option causes @code{ntpq} to include both lines of output
981 for a single-variable @code{readvar}.
982 Using an environment variable to
983 preset this option in a script will enable both older and
984 newer @code{ntpq} to behave identically in this regard.
986 @subsection peers option (-p)
989 This is the ``print a list of the peers'' option.
992 This option has some usage constraints. It:
995 must not appear in combination with any of the following options:
999 Print a list of the peers known to the server as well as a summary
1000 of their state. This is equivalent to the 'peers' interactive command.
1002 @subsection refid option (-r)
1005 This is the ``set default display type for s2+ refids'' option.
1006 This option takes a keyword argument.
1009 This option has some usage constraints. It:
1012 This option takes a keyword as its argument.
1013 The argument sets an enumeration value that can be tested by comparing the option value macro (OPT_VALUE_REFID).
1014 The available keywords are:
1019 or their numeric equivalent.@end itemize
1021 Set the default display format for S2+ refids.
1023 @subsection wide option (-w)
1026 This is the ``display the full 'remote' value'' option.
1027 Display the full value of the 'remote' value. If this requires
1028 more than 15 characters, display the full value, emit a newline,
1029 and continue the data display properly indented on the next line.
1033 @subsection presetting/configuring ntpq
1035 Any option that is not marked as @i{not presettable} may be preset by
1036 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
1037 the options listed above in upper case and segmented with underscores.
1038 The @code{NTPQ} variable will be tokenized and parsed like
1039 the command line. The remaining variables are tested for existence and their
1040 values are treated like option arguments.
1044 @code{libopts} will search in 2 places for configuration files:
1051 The environment variables @code{HOME}, and @code{PWD}
1052 are expanded and replaced when @file{ntpq} runs.
1053 For any of these that are plain files, they are simply processed.
1054 For any that are directories, then a file named @file{.ntprc} is searched for
1055 within that directory and processed.
1057 Configuration files may be in a wide variety of formats.
1058 The basic format is an option name followed by a value (argument) on the
1059 same line. Values may be separated from the option name with a colon,
1060 equal sign or simply white space. Values may be continued across multiple
1061 lines by escaping the newline with a backslash.
1063 Multiple programs may also share the same initialization file.
1064 Common options are collected at the top, followed by program specific
1065 segments. The segments are separated by lines like:
1075 Do not mix these styles within one configuration file.
1077 Compound values and carefully constructed string values may also be
1078 specified using XML syntax:
1081 <sub-opt>...<...>...</sub-opt>
1085 yielding an @code{option-name.sub-opt} string value of
1089 @code{AutoOpts} does not track suboptions. You simply note that it is a
1090 hierarchicly valued option. @code{AutoOpts} does provide a means for searching
1091 the associated name/value pair list (see: optionFindValue).
1093 The command line options relating to configuration and/or usage help are:
1095 @subsubheading version (-)
1097 Print the program version to standard out, optionally with licensing
1098 information, then exit 0. The optional argument specifies how much licensing
1099 detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument.
1100 Only the first letter of the argument is examined:
1104 Only print the version. This is the default.
1106 Name the copyright usage licensing terms.
1108 Print the full copyright usage licensing terms.
1111 @node ntpq exit status
1112 @subsection ntpq exit status
1114 One of the following exit values will be returned:
1116 @item 0 (EXIT_SUCCESS)
1117 Successful program execution.
1118 @item 1 (EXIT_FAILURE)
1119 The operation failed or the command syntax was not valid.
1120 @item 66 (EX_NOINPUT)
1121 A specified configuration file could not be loaded.
1122 @item 70 (EX_SOFTWARE)
1123 libopts had an internal operational error. Please report
1124 it to autogen-users@@lists.sourceforge.net. Thank you.