From: Harlan Stenn Date: Wed, 15 Jun 2011 08:10:12 +0000 (-0400) Subject: Update ntp-wait autogen docs X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7e5c8858a63cfbe49e45e1ce840b6b33fa0e01b9;p=thirdparty%2Fntp.git Update ntp-wait autogen docs bk: 4df868e4jQElPjINgkposNF114yDmA --- diff --git a/ChangeLog b/ChangeLog index 4561c56992..d52581533b 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,4 @@ +* Update ntp-wait autogen docs. * Update the ntpd autogen docs. * Update the ntpsnmpd autogen docs. * Use autogen to produce ntp-keygen docs. diff --git a/scripts/Makefile.am b/scripts/Makefile.am index 017ea02191..095061a10d 100644 --- a/scripts/Makefile.am +++ b/scripts/Makefile.am @@ -1,5 +1,17 @@ NULL= +man_MANS= $(srcdir)/ntp-wait.1 +run_ag= cd $(srcdir) && env PATH="$(abs_builddir):$(PATH)" \ + autogen -L ../sntp/include -L ../sntp/ag-tpl --writable +std_def_list = \ + $(top_srcdir)/sntp/include/debug-opt.def \ + $(top_srcdir)/sntp/include/autogen-version.def \ + $(top_srcdir)/sntp/include/copyright.def \ + $(top_srcdir)/sntp/include/homerc.def \ + $(top_srcdir)/sntp/include/ntp.lic \ + $(top_srcdir)/sntp/include/version.def \ + $(NULL) + if NTP_BINSUBDIR_IS_BIN bin_SCRIPTS = ntp-wait ntptrace else @@ -18,6 +30,12 @@ noinst_SCRIPTS = \ summary \ $(NULL) +noinst_DATA= \ + $(srcdir)/ntp-wait.html \ + $(srcdir)/ntp-wait-opts.texi \ + $(srcdir)/ntp-wait-opts.menu \ + $(NULL) + EXTRA_DIST = \ check--help \ checkChangeLog \ @@ -31,9 +49,31 @@ EXTRA_DIST = \ ntp-groper \ ntp-restart \ ntp-status \ + ntp-wait.1 \ + ntp-wait.html \ + ntp-wait.texi \ + ntp-wait-opts.def \ + ntp-wait-opts.menu \ + ntp-wait-opts.texi \ rc1 \ rc2 \ stats \ UpdatePoint \ VersionName \ $(NULL) + +# For man pages, use agman-cmd.tpl +# For mdoc pages, use agmdoc-cmd.tpl +$(srcdir)/ntp-wait.1: $(srcdir)/ntp-wait-opts.def $(std_def_list) + $(run_ag) -DMAN_SECTION=1 -Tagmdoc-cmd.tpl ntp-wait-opts.def + +$(srcdir)/ntp-wait-opts.menu: $(srcdir)/ntp-wait-opts.texi + @: do-nothing action to avoid default SCCS get, .menu built with .texi + +$(srcdir)/ntp-wait-opts.texi: $(srcdir)/ntp-wait-opts.def $(std_def_list) + $(run_ag) -Taginfo.tpl -DLEVEL=section ntp-wait-opts.def + -$(top_srcdir)/../scripts/check--help $@ + +$(srcdir)/ntp-wait.html: $(srcdir)/ntp-wait-opts.menu $(srcdir)/ntp-wait-opts.texi $(srcdir)/ntp-wait.texi $(top_srcdir)/sntp/include/version.texi + cd $(srcdir) && ( makeinfo --force --html --no-split -o ntp-wait.html ntp-wait.texi || true ) + diff --git a/scripts/ntp-wait-opts.def b/scripts/ntp-wait-opts.def new file mode 100644 index 0000000000..d5b7be1608 --- /dev/null +++ b/scripts/ntp-wait-opts.def @@ -0,0 +1,106 @@ +/* -*- Mode: Text -*- */ + +autogen definitions options; + +#include copyright.def +// #include homerc.def +#include autogen-version.def + +prog-name = "ntp-wait"; +prog-title = "Wait for ntpd to stabilize the system clock"; +package = ntp; + +test-main; + +// #include version.def + +flag = { + value = n; + arg-type = number; + arg-name = num-tries; + descrip = "Number of times to check ntpd"; + doc = <<- _EndOfDoc_ + The maximum number of times we will check ntpd to see if it + has been able to synchronize and stabilize the system clock. + + The default is 100 times. + _EndOfDoc_; +}; + +flag = { + value = s; + arg-type = number; + arg-name = secs-between-tries; + descrip = "How long to sleep between tries"; + doc = <<- _EndOfDoc_ + We will sleep for secs-between-tries after each query of ntpd + that returns "the time is not yet stable". + + The default is 6 seconds. + _EndOfDoc_; +}; + +flag = { + value = v; + descrip = "Be verbose"; + doc = <<- _EndOfDoc_ + By default, ntp-wait is silent. With this option, ntp-wait + will provide status information. + _EndOfDoc_; +}; + +/* explain: Additional information whenever the usage routine is invoked */ +explain = <<- _END_EXPLAIN + _END_EXPLAIN; + +doc-section = { + ds-type = 'DESCRIPTION'; + ds-format = 'mdoc'; + ds-text = <<- _END_PROG_MDOC_DESCRIP +.Nm will send at most +.Ar num-tries +queries to +.Xr ntpd 8 +(sleeping for +.Ar secs-between-tries +after each status return that says +.Xr ntpd 8 +has not yet produced a synchronized and stable system clock). +.Pp +.Nm +will do this quietly, unless the +.Fl v +flag is provided. + _END_PROG_MDOC_DESCRIP; +}; + +/* +prog-info-descrip = <<- _END_PROG_INFO_DESCRIP + _END_PROG_INFO_DESCRIP; +*/ + +/* +doc-section = { + ds-type = 'USAGE'; + ds-format = 'mdoc'; + ds-text = <<- _END_MDOC_USAGE + _END_MDOC_USAGE; +}; +*/ + +doc-section = { + ds-type = 'AUTHORS'; + ds-format = 'mdoc'; + ds-text = <<- _END_MDOC_NOTES +.An "Harlan Stenn" + _END_MDOC_NOTES; +}; + +/* +doc-section = { + ds-type = 'BUGS'; + ds-format = 'mdoc'; + ds-text = <<- _END_MDOC_BUGS + _END_MDOC_BUGS; +}; +*/ diff --git a/scripts/ntp-wait-opts.menu b/scripts/ntp-wait-opts.menu new file mode 100644 index 0000000000..bb51936efa --- /dev/null +++ b/scripts/ntp-wait-opts.menu @@ -0,0 +1 @@ +* ntp-wait Invocation:: Invoking ntp-wait diff --git a/scripts/ntp-wait-opts.texi b/scripts/ntp-wait-opts.texi new file mode 100644 index 0000000000..bf1e5d8f92 --- /dev/null +++ b/scripts/ntp-wait-opts.texi @@ -0,0 +1,58 @@ +@node ntp-wait Invocation +@section Invoking ntp-wait +@pindex ntp-wait +@cindex Wait for ntpd to stabilize the system clock +@ignore +# +# EDIT THIS FILE WITH CAUTION (ntp-wait-opts.texi) +# +# It has been AutoGen-ed June 14, 2011 at 09:07:45 AM by AutoGen 5.11.10pre10 +# From the definitions ntp-wait-opts.def +# and the template file aginfo.tpl +@end ignore + + + +This section was generated by @strong{AutoGen}, +the aginfo template and the option descriptions for the @command{ntp-wait} program. It documents the @command{ntp-wait} usage text and option meanings. + +This software is released under a specialized copyright license. + +@menu +* ntp-wait usage:: ntp-wait usage help (-?) +* ntp-wait :: option (-n) +* ntp-wait :: option (-s) +* ntp-wait :: option (-v) +@end menu + +@node ntp-wait usage +@subsection ntp-wait usage help (-?) +@cindex ntp-wait usage + +This is the automatically generated usage text for ntp-wait: + +@exampleindent 0 +@example +/home/stenn/ntp-dev/A.psp-fb2/scripts/ntp-wait version [unknown] calling Getopt::Std::getopts (version 1.06 [paranoid]), +running under Perl version 5.8.9. + +Usage: ntp-wait [-OPTIONS [-MORE_OPTIONS]] [--] [PROGRAM_ARG1 ...] + +The following single-character options are accepted: + With arguments: -n -s + Boolean (without arguments): -v + +Options may be merged together. -- stops processing of options. +Space is not required between options and their arguments. + [Now continuing due to backward compatibility and excessive paranoia. + See ``perldoc Getopt::Std'' about $Getopt::Std::STANDARD_HELP_VERSION.] +@end example +@exampleindent 4 + +@node ntp-wait +@subsection option (-v) +@cindex ntp-wait- + +This is the ``be verbose'' option. +By default, ntp-wait is silent. With this option, ntp-wait +will provide status information. diff --git a/scripts/ntp-wait.1 b/scripts/ntp-wait.1 new file mode 100644 index 0000000000..1f0d5e485a --- /dev/null +++ b/scripts/ntp-wait.1 @@ -0,0 +1,92 @@ +.Dd June 14 2011 +.Dt NTP_WAIT 1 User Commands +.Os FreeBSD 6.4-STABLE +.\" EDIT THIS FILE WITH CAUTION (ntp-wait-opts.mdoc) +.\" +.\" It has been AutoGen-ed June 14, 2011 at 09:07:43 AM by AutoGen 5.11.10pre10 +.\" From the definitions ntp-wait-opts.def +.\" and the template file agmdoc-cmd.tpl +.Sh NAME +.Nm ntp-wait +.Nd Wait for ntpd to stabilize the system clock +.Sh SYNOPSIS +.Nm +.\" Mixture of short (flag) options and long options +.Op Fl flags +.Op Fl flag Ar value +.Op Fl \-option-name Ar value +.Pp +All arguments must be options. +.Pp +.Sh DESCRIPTION +.Nm will send at most +.Ar num-tries +queries to +.Xr ntpd 8 +(sleeping for +.Ar secs-between-tries +after each status return that says +.Xr ntpd 8 +has not yet produced a synchronized and stable system clock). +.Pp +.Nm +will do this quietly, unless the +.Fl v +flag is provided. +.Sh "OPTIONS" +.Bl -tag +.It \-n " \fInum\-tries\fP, " \-\- "=" \fInum\-tries\fP +Number of times to check ntpd. +This option takes an integer number as its argument. +.sp +The maximum number of times we will check ntpd to see if it +has been able to synchronize and stabilize the system clock. +The default is 100 times. +.It \-s " \fIsecs\-between\-tries\fP, " \-\- "=" \fIsecs\-between\-tries\fP +How long to sleep between tries. +This option takes an integer number as its argument. +.sp +We will sleep for secs-between-tries after each query of ntpd +that returns "the time is not yet stable". +The default is 6 seconds. +.It \-v ", " -\- +Be verbose. +.sp +By default, ntp-wait is silent. With this option, ntp-wait +will provide status information. +.It \-? , " \-\-help" +Display usage information and exit. +.It \-! , " \-\-more-help" +Pass the extended usage information through a pager. +.It \- " [{\fIv|c|n\fP}]," " \-\-version" "[=\fI{v|c|n}\fP]" +Output version of program and exit. The default mode is `v', a simple +version. The `c' mode will print copyright information and `n' will +print the full copyright notice. +.El +.Sh "OPTION PRESETS" +Any option that is not marked as \fInot presettable\fP may be preset +by loading values from environment variables named: +.nf + \fBNTP_WAIT_\fP or \fBNTP_WAIT\fP +.fi +.ad +.Sh "ENVIRONMENT" +See \fBOPTION PRESETS\fP for configuration environment variables. +.Sh "EXIT STATUS" +One of the following exit values will be returned: +.Bl -tag +.It 0 +Successful program execution. +.It 1 +The operation failed or the command syntax was not valid. +.El +.Sh AUTHORS +.An "Harlan Stenn" +.Sh "COPYRIGHT" +Copyright (C) 1970-2011 The University of Delaware, David L. Mills, and/or others all rights reserved. +This program is released under the terms of the NTP license, . +.Sh "BUGS" +Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org +.Sh "NOTES" +This manual page was \fIAutoGen\fP-erated from the \fBntp-wait\fP +option definitions. diff --git a/scripts/ntp-wait.html b/scripts/ntp-wait.html new file mode 100644 index 0000000000..97109b60f5 --- /dev/null +++ b/scripts/ntp-wait.html @@ -0,0 +1,174 @@ + + +Ntp-wait User's Manual + + + + + + + + + +

Ntp-wait User's Manual

+
+

+ +Next: , +Previous: (dir), +Up: (dir) + +
+ +

Simple Network Time Protocol User Manual

+ +

This document describes the use of the NTP Project's ntp-wait program, +that can be used to query a Network Time Protocol (NTP) server and +display the time offset of the system clock relative to the server +clock. Run as root, it can correct the system clock to this offset as +well. It can be run as an interactive command or from a cron job. + +

This document applies to version {No value for `VERSION'} of ntp-wait. + +

The program implements the SNTP protocol as defined by RFC 5905, the NTPv4 +IETF specification. + +

+

Short Contents

+ +
+ + + +
+

+ + + + +
+ + +

Description

+ +

By default, ntp-wait writes the local data and time (i.e., not UTC) to the +standard output in the format: + +

     1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 secs
+
+

where +YYYY-MM-DD HH:MM:SS.SUBSEC is the local date and time, +(+0800) is the local timezone adjustment (so we would add 8 hours and 0 minutes to convert the reported local time to UTC), +and +the +4.567 +/- 0.089 secs indicates the time offset and +error bound of the system clock relative to the server clock. + +

+

+ + + + +
+ +

Invoking ntp-wait

+ +

+ +

This section was generated by AutoGen, +the aginfo template and the option descriptions for the ntp-wait program. It documents the ntp-wait usage text and option meanings. + +

This software is released under a specialized copyright license. + +

+ +
+

+ + +Next: , +Up: ntp-wait Invocation + +
+ +

ntp-wait usage help (-?)

+ +

+This is the automatically generated usage text for ntp-wait: + +

/home/stenn/ntp-dev/A.psp-fb2/scripts/ntp-wait version [unknown] calling Getopt::Std::getopts (version 1.06 [paranoid]),
+running under Perl version 5.8.9.
+
+Usage: ntp-wait [-OPTIONS [-MORE_OPTIONS]] [--] [PROGRAM_ARG1 ...]
+
+The following single-character options are accepted:
+        With arguments: -n -s
+        Boolean (without arguments): -v
+
+Options may be merged together.  -- stops processing of options.
+Space is not required between options and their arguments.
+  [Now continuing due to backward compatibility and excessive paranoia.
+   See ``perldoc Getopt::Std'' about $Getopt::Std::STANDARD_HELP_VERSION.]
+
+
+

+ + +Previous: ntp-wait, +Up: ntp-wait Invocation + +
+ +

option (-v)

+ +

+This is the “be verbose” option. +By default, ntp-wait is silent. With this option, ntp-wait +will provide status information. + +

+

+ + + +
+ + +

Usage

+ +

The simplest use of this program is as an unprivileged command to +check the current time, offset, and error in the local clock. +For example: + +

    ntp-wait ntpserver.somewhere
+
+

With suitable privilege, it can be run as a command or in a +crom job to reset the local clock from a reliable server, like +the ntpdate and rdate commands. +For example: + +

    ntp-wait -a ntpserver.somewhere
+
+ + diff --git a/scripts/ntp-wait.texi b/scripts/ntp-wait.texi new file mode 100644 index 0000000000..a8526bf19f --- /dev/null +++ b/scripts/ntp-wait.texi @@ -0,0 +1,91 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename ntp-wait.info +@settitle Ntp-wait User's Manual +@include include/version.texi +@paragraphindent 2 +@c %**end of header + +@ifinfo +This file documents the use ntp-wait, +a program from +the NTP Project +that is used to wait until @code{ntpd} has been able to +synchronize and stabilize the time on the current host. +@end ifinfo + +@direntry +* ntp-wait: (ntp-wait). Wait for ntpd to synchronize and stabilize the system clock. +@end direntry + +@titlepage +@title ntp-wait User's Manual +@subtitle ntp-wait, version @value{VERSION}, @value{UPDATED} +@c @author Max @email{foo@ntp.org} +@end titlepage + +@c @page +@c @vskip 0pt plus 1filll + +@node Top, ntp-wait Description, (dir), (dir) +@top Simple Network Time Protocol User Manual + +This document describes the use of the NTP Project's @code{ntp-wait} program, +that can be used to query a Network Time Protocol (NTP) server and +display the time offset of the system clock relative to the server +clock. Run as root, it can correct the system clock to this offset as +well. It can be run as an interactive command or from a cron job. + +This document applies to version @value{VERSION} of @code{ntp-wait}. + +The program implements the SNTP protocol as defined by RFC 5905, the NTPv4 +IETF specification. + +@shortcontents + +@menu +* ntp-wait Description:: Description +* ntp-wait Invocation:: Invoking ntp-wait +* Usage:: Usage +@end menu + +@node ntp-wait Description +@comment node-name, next, previous, up +@section Description + +By default, @code{ntp-wait} writes the local data and time (i.e., not UTC) to the +standard output in the format: + +@example +1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 secs +@end example + +where +YYYY-MM-DD HH:MM:SS.SUBSEC is the local date and time, +(+0800) is the local timezone adjustment (so we would add 8 hours and 0 minutes to convert the reported local time to UTC), +and +the +4.567 +/- 0.089 secs indicates the time offset and +error bound of the system clock relative to the server clock. + +@include ntp-wait-opts.texi + +@node Usage +@comment node-name, next, previous, up +@section Usage + +The simplest use of this program is as an unprivileged command to +check the current time, offset, and error in the local clock. +For example: + +@example +ntp-wait ntpserver.somewhere +@end example + +With suitable privilege, it can be run as a command or in a +@code{crom} job to reset the local clock from a reliable server, like +the @code{ntpdate} and @code{rdate} commands. +For example: + +@example +ntp-wait -a ntpserver.somewhere +@end example