/* -*- Mode: Text -*- */

autogen definitions options;

#include copyright.def
#include homerc.def
#include autogen-version.def

prog-name      = "ntpq";
prog-title     = "standard NTP query program";
argument       = '[ host ...]';

test-main;

flag = {
    name      = ipv4;
    value     = 4;
    equivalence = ipv4;
    descrip   = "Force IPv4 DNS name resolution";
    doc = <<-  _EndOfDoc_
	Force DNS resolution of following host names on the command line
	to the IPv4 namespace.
	_EndOfDoc_;
};

flag = {
    name      = ipv6;
    value     = 6;
    equivalence = ipv4;
    descrip   = "Force IPv6 DNS name resolution";
    doc = <<-  _EndOfDoc_
	Force DNS resolution of following host names on the command line
	to the IPv6 namespace.
	_EndOfDoc_;
};

flag = {
    name      = command;
    value     = c;
    arg-type  = string;
    descrip   = "run a command and exit";
    max       = NOLIMIT;
    arg-name  = cmd;
    stack-arg;
    doc = <<-  _EndOfDoc_
	The following argument is interpreted as an interactive format command
	and is added to the list of commands to be executed on the specified
	host(s).
	_EndOfDoc_;
};

#include debug-opt.def

flag = {
    name      = peers;
    value     = p;
    descrip   = "Print a list of the peers";
    flags-cant = interactive;
    doc = <<-  _EndOfDoc_
	Print a list of the peers known to the server as well as a summary
	of their state. This is equivalent to the 'peers' interactive command.
	_EndOfDoc_;
};

flag = {
    name      = interactive;
    value     = i;
    flags-cant = command, peers;
    descrip   = "Force ntpq to operate in interactive mode";
    doc = <<-  _EndOfDoc_
	Force ntpq to operate in interactive mode.  Prompts will be written
	to the standard output and commands read from the standard input.
	_EndOfDoc_;
};

flag = {
    name      = numeric;
    value     = n;
    descrip   = "numeric host addresses";
    doc = <<-  _EndOfDoc_
	Output all host addresses in dotted-quad numeric format rather than
	converting to the canonical host names. 
	_EndOfDoc_;
};

detail = <<-  _END_DETAIL
	The
	[= prog-name =]
	utility program is used to query NTP servers which
	implement the standard NTP mode 6 control message formats defined
	in Appendix B of the NTPv3 specification RFC1305, requesting
	information about current state and/or changes in that state.
	The same formats are used in NTPv4, although some of the
	variables have changed and new ones added.
	_END_DETAIL;

prog-man-descrip = <<-  _END_PROG_MAN_DESCRIP
	The
	[= prog-name =]
	utility program is used to query NTP servers which
	implement the standard NTP mode 6 control message formats defined
	in Appendix B of the NTPv3 specification RFC1305, requesting
	information about current state and/or changes in that state.
	The same formats are used in NTPv4, although some of the
	variables have changed and new ones added. The description on this
	page is for the NTPv4 variables.
	The program may be run either in interactive mode or controlled using
	command line arguments.
	Requests to read and write arbitrary
	variables can be assembled, with raw and pretty-printed output
	options being available.
	The
	[= prog-name =]
	utility can also obtain and print a
	list of peers in a common format by sending multiple queries to the
	server.

	If one or more request options is included on the command line
	when
	[= prog-name =]
	is executed, each of the requests will be sent
	to the NTP servers running on each of the hosts given as command
	line arguments, or on localhost by default.
	If no request options
	are given,
	[= prog-name =]
	will attempt to read commands from the
	standard input and execute these on the NTP server running on the
	first host given on the command line, again defaulting to localhost
	when no other host is specified.
	The
	[= prog-name =]
	utility will prompt for
	commands if the standard input is a terminal device.

	The
	[= prog-name =]
	utility uses NTP mode 6 packets to communicate with the
	NTP server, and hence can be used to query any compatible server on
	the network which permits it.
	Note that since NTP is a UDP protocol
	this communication will be somewhat unreliable, especially over
	large distances in terms of network topology.
	The
	[= prog-name =]
	utility makes
	one attempt to retransmit requests, and will time requests out if
	the remote host is not heard from within a suitable timeout
	time.

	Specifying a
	command line option other than
	.Fl i
	or
	.Fl n
	will
	cause the specified query (queries) to be sent to the indicated
	host(s) immediately.
	Otherwise,
	[= prog-name =]  
	will attempt to read
	interactive format commands from the standard input.
	.Ss "Internal Commands"
	Interactive format commands consist of a keyword followed by zero
	to four arguments.
	Only enough characters of the full keyword to
	uniquely identify the command need be typed.

	A
	number of interactive format commands are executed entirely within
	the
	[= prog-name =]
	utility itself and do not result in NTP mode 6
	requests being sent to a server.
	These are described following.
	@table @code
	@item ? [command_keyword]
	@itemx help [command_keyword]
	A
	.Ql \&?
	by itself will print a list of all the command
	keywords known to this incarnation of
	[= prog-name =] .
	A
	.Ql \&?
	followed by a command keyword will print function and usage
	information about the command.
	This command is probably a better
	source of information about
	[= prog-name =]
	than this manual
	page.
	@item addvars
	.Ar variable_name [=value] ...
	.Xc
	@item rmvars variable_name ...
	@item clearvars
	The data carried by NTP mode 6 messages consists of a list of
	items of the form
	.Ql variable_name=value ,
	where the
	.Ql =value
	is ignored, and can be omitted,
	in requests to the server to read variables.
	The
	[= prog-name =]
	utility maintains an internal list in which data to be included in control
	messages can be assembled, and sent using the
	.Ic readlist
	and
	.Ic writelist
	commands described below.
	The
	.Ic addvars
	command allows variables and their optional values to be added to
	the list.
	If more than one variable is to be added, the list should
	be comma-separated and not contain white space.
	The
	.Ic rmvars
	command can be used to remove individual variables from the list,
	while the
	.Ic clearlist
	command removes all variables from the
	list.
	@item authenticate [ yes | no ]
	Normally
	[= prog-name =]
	does not authenticate requests unless
	they are write requests.
	The command
	.Ql authenticate yes
	causes
	[= prog-name =]
	to send authentication with all requests it
	makes.
	Authenticated requests causes some servers to handle
	requests slightly differently, and can occasionally melt the CPU in
	fuzzballs if you turn authentication on before doing a
	.Ic peer
	display.
	The command
	.Ql authenticate
	causes
	[= prog-name =]
	to display whether or not
	[= prog-name =]
	is currently autheinticating requests.
	@item cooked
	Causes output from query commands to be "cooked", so that
	variables which are recognized by
	[= prog-name =]
	will have their
	values reformatted for human consumption.
	Variables which
	[= prog-name =]
	thinks should have a decodable value but didn't are
	marked with a trailing
	.Ql \&? .
	.@item debug [
	.Cm more |
	.Cm less |
	.Cm off
	]
	.Xc
	With no argument, displays the current debug level.
	Otherwise, the debug level is changed to the indicated level.
	@item delay milliseconds
	Specify a time interval to be added to timestamps included in
	requests which require authentication.
	This is used to enable
	(unreliable) server reconfiguration over long delay network paths
	or between machines whose clocks are unsynchronized.
	Actually the
	server does not now require timestamps in authenticated requests,
	so this command may be obsolete.
	@item host hostname
	Set the host to which future queries will be sent.
	Hostname may
	be either a host name or a numeric address.
	@item hostnames Cm yes | Cm no
	If
	.Cm yes
	is specified, host names are printed in
	information displays.
	If
	.Cm no
	is specified, numeric
	addresses are printed instead.
	The default is
	.Cm yes ,
	unless
	modified using the command line
	.Fl n
	switch.
	@item keyid keyid
	This command allows the specification of a key number to be
	used to authenticate configuration requests.
	This must correspond
	to a key number the server has been configured to use for this
	purpose.
	@item ntpversion [
	.Cm 1 |
	.Cm 2 |
	.Cm 3 |
	.Cm 4
	]
	.Xc
	Sets the NTP version number which
	[= prog-name =]
	claims in
	packets.
	Defaults to 3, Note that mode 6 control messages (and
	modes, for that matter) didn't exist in NTP version 1.
	There appear
	to be no servers left which demand version 1.
	With no argument, displays the current NTP version that will be used
	when communicating with servers.
	@item quit
	Exit
	[= prog-name =] .
	@item passwd
	This command prompts you to type in a password (which will not
	be echoed) which will be used to authenticate configuration
	requests.
	The password must correspond to the key configured for
	use by the NTP server for this purpose if such requests are to be
	successful.
	@item raw
	Causes all output from query commands is printed as received
	from the remote server.
	The only formating/interpretation done on
	the data is to transform nonascii data into a printable (but barely
	understandable) form.
	@item timeout Ar milliseconds
	Specify a timeout period for responses to server queries.
	The
	default is about 5000 milliseconds.
	Note that since
	[= prog-name =]
	retries each query once after a timeout, the total waiting time for
	a timeout will be twice the timeout value set.
	@end table

	_END_PROG_MAN_DESCRIP;