contrib/ntp/ntpdc/invoke-ntpdc.texi

   1 @node ntpdc Invocation
   2 @section Invoking ntpdc
   3 @pindex ntpdc
   4 @cindex vendor-specific NTPD control program
   5 @ignore
   6 #
   7 # EDIT THIS FILE WITH CAUTION  (invoke-ntpdc.texi)
   8 #
   9 # It has been AutoGen-ed  April 26, 2016 at 08:29:05 PM by AutoGen 5.18.5
  10 # From the definitions    ntpdc-opts.def
  11 # and the template file   agtexi-cmd.tpl
  12 @end ignore
  13
  14
  15
  16 @code{ntpdc}
  17 is deprecated.
  18 Please use
  19 @code{ntpq(1ntpqmdoc)} instead - it can do everything
  20 @code{ntpdc}
  21 used to do, and it does so using a much more sane interface.
  22
  23 @code{ntpdc}
  24 is a utility program used to query
  25 @code{ntpd(1ntpdmdoc)}
  26 about its
  27 current state and to request changes in that state.
  28 It uses NTP mode 7 control message formats described in the source code.
  29 The program may
  30 be run either in interactive mode or controlled using command line
  31 arguments.
  32 Extensive state and statistics information is available
  33 through the
  34 @code{ntpdc}
  35 interface.
  36 In addition, nearly all the
  37 configuration options which can be specified at startup using
  38 ntpd's configuration file may also be specified at run time using
  39 @code{ntpdc}
  40
  41 This section was generated by @strong{AutoGen},
  42 using the @code{agtexi-cmd} template and the option descriptions for the @code{ntpdc} program.
  43 This software is released under the NTP license, <http://ntp.org/license>.
  44
  45 @menu
  46 * ntpdc usage::                  ntpdc help/usage (@option{--help})
  47 * ntpdc ipv4::                   ipv4 option (-4)
  48 * ntpdc ipv6::                   ipv6 option (-6)
  49 * ntpdc command::                command option (-c)
  50 * ntpdc interactive::            interactive option (-i)
  51 * ntpdc listpeers::              listpeers option (-l)
  52 * ntpdc numeric::                numeric option (-n)
  53 * ntpdc peers::                  peers option (-p)
  54 * ntpdc showpeers::              showpeers option (-s)
  55 * ntpdc config::                 presetting/configuring ntpdc
  56 * ntpdc exit status::            exit status
  57 * ntpdc Usage::                  Usage
  58 * ntpdc See Also::               See Also
  59 * ntpdc Authors::                Authors
  60 * ntpdc Bugs::                   Bugs
  61 @end menu
  62
  63 @node ntpdc usage
  64 @subsection ntpdc help/usage (@option{--help})
  65 @cindex ntpdc help
  66
  67 This is the automatically generated usage text for ntpdc.
  68
  69 The text printed is the same whether selected with the @code{help} option
  70 (@option{--help}) or the @code{more-help} option (@option{--more-help}).  @code{more-help} will print
  71 the usage text by passing it through a pager program.
  72 @code{more-help} is disabled on platforms without a working
  73 @code{fork(2)} function.  The @code{PAGER} environment variable is
  74 used to select the program, defaulting to @file{more}.  Both will exit
  75 with a status code of 0.
  76
  77 @exampleindent 0
  78 @example
  79 ntpdc - vendor-specific NTPD control program - Ver. 4.2.8p7
  80 Usage:  ntpdc [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... [ host ...]
  81   Flg Arg Option-Name    Description
  82    -4 no  ipv4           Force IPv4 DNS name resolution
  83                                 - prohibits the option 'ipv6'
  84    -6 no  ipv6           Force IPv6 DNS name resolution
  85                                 - prohibits the option 'ipv4'
  86    -c Str command        run a command and exit
  87                                 - may appear multiple times
  88    -d no  debug-level    Increase debug verbosity level
  89                                 - may appear multiple times
  90    -D Num set-debug-level Set the debug verbosity level
  91                                 - may appear multiple times
  92    -i no  interactive    Force ntpq to operate in interactive mode
  93                                 - prohibits these options:
  94                                 command
  95                                 listpeers
  96                                 peers
  97                                 showpeers
  98    -l no  listpeers      Print a list of the peers
  99                                 - prohibits the option 'command'
 100    -n no  numeric        numeric host addresses
 101    -p no  peers          Print a list of the peers
 102                                 - prohibits the option 'command'
 103    -s no  showpeers      Show a list of the peers
 104                                 - prohibits the option 'command'
 105       opt version        output version information and exit
 106    -? no  help           display extended usage information and exit
 107    -! no  more-help      extended usage information passed thru pager
 108    -> opt save-opts      save the option state to a config file
 109    -< Str load-opts      load options from a config file
 110                                 - disabled as '--no-load-opts'
 111                                 - may appear multiple times
 112
 113 Options are specified by doubled hyphens and their name or by a single
 114 hyphen and the flag character.
 115
 116
 117 The following option preset mechanisms are supported:
 118  - reading file $HOME/.ntprc
 119  - reading file ./.ntprc
 120  - examining environment variables named NTPDC_*
 121
 122 Please send bug reports to:  <http://bugs.ntp.org, bugs@@ntp.org>
 123 @end example
 124 @exampleindent 4
 125
 126 @node ntpdc ipv4
 127 @subsection ipv4 option (-4)
 128 @cindex ntpdc-ipv4
 129
 130 This is the ``force ipv4 dns name resolution'' option.
 131
 132 @noindent
 133 This option has some usage constraints.  It:
 134 @itemize @bullet
 135 @item
 136 must not appear in combination with any of the following options:
 137 ipv6.
 138 @end itemize
 139
 140 Force DNS resolution of following host names on the command line
 141 to the IPv4 namespace.
 142 @node ntpdc ipv6
 143 @subsection ipv6 option (-6)
 144 @cindex ntpdc-ipv6
 145
 146 This is the ``force ipv6 dns name resolution'' option.
 147
 148 @noindent
 149 This option has some usage constraints.  It:
 150 @itemize @bullet
 151 @item
 152 must not appear in combination with any of the following options:
 153 ipv4.
 154 @end itemize
 155
 156 Force DNS resolution of following host names on the command line
 157 to the IPv6 namespace.
 158 @node ntpdc command
 159 @subsection command option (-c)
 160 @cindex ntpdc-command
 161
 162 This is the ``run a command and exit'' option.
 163 This option takes a string argument @file{cmd}.
 164
 165 @noindent
 166 This option has some usage constraints.  It:
 167 @itemize @bullet
 168 @item
 169 may appear an unlimited number of times.
 170 @end itemize
 171
 172 The following argument is interpreted as an interactive format command
 173 and is added to the list of commands to be executed on the specified
 174 host(s).
 175 @node ntpdc interactive
 176 @subsection interactive option (-i)
 177 @cindex ntpdc-interactive
 178
 179 This is the ``force ntpq to operate in interactive mode'' option.
 180
 181 @noindent
 182 This option has some usage constraints.  It:
 183 @itemize @bullet
 184 @item
 185 must not appear in combination with any of the following options:
 186 command, listpeers, peers, showpeers.
 187 @end itemize
 188
 189 Force ntpq to operate in interactive mode.  Prompts will be written
 190 to the standard output and commands read from the standard input.
 191 @node ntpdc listpeers
 192 @subsection listpeers option (-l)
 193 @cindex ntpdc-listpeers
 194
 195 This is the ``print a list of the peers'' option.
 196
 197 @noindent
 198 This option has some usage constraints.  It:
 199 @itemize @bullet
 200 @item
 201 must not appear in combination with any of the following options:
 202 command.
 203 @end itemize
 204
 205 Print a list of the peers known to the server as well as a summary of
 206 their state. This is equivalent to the 'listpeers' interactive command.
 207 @node ntpdc numeric
 208 @subsection numeric option (-n)
 209 @cindex ntpdc-numeric
 210
 211 This is the ``numeric host addresses'' option.
 212 Output all host addresses in dotted-quad numeric format rather than
 213 converting to the canonical host names.
 214 @node ntpdc peers
 215 @subsection peers option (-p)
 216 @cindex ntpdc-peers
 217
 218 This is the ``print a list of the peers'' option.
 219
 220 @noindent
 221 This option has some usage constraints.  It:
 222 @itemize @bullet
 223 @item
 224 must not appear in combination with any of the following options:
 225 command.
 226 @end itemize
 227
 228 Print a list of the peers known to the server as well as a summary
 229 of their state. This is equivalent to the 'peers' interactive command.
 230 @node ntpdc showpeers
 231 @subsection showpeers option (-s)
 232 @cindex ntpdc-showpeers
 233
 234 This is the ``show a list of the peers'' option.
 235
 236 @noindent
 237 This option has some usage constraints.  It:
 238 @itemize @bullet
 239 @item
 240 must not appear in combination with any of the following options:
 241 command.
 242 @end itemize
 243
 244 Print a list of the peers known to the server as well as a summary
 245 of their state. This is equivalent to the 'dmpeers' interactive command.
 246
 247
 248 @node ntpdc config
 249 @subsection presetting/configuring ntpdc
 250
 251 Any option that is not marked as @i{not presettable} may be preset by
 252 loading values from configuration ("rc" or "ini") files, and values from environment variables named @code{NTPDC} and @code{NTPDC_<OPTION_NAME>}.  @code{<OPTION_NAME>} must be one of
 253 the options listed above in upper case and segmented with underscores.
 254 The @code{NTPDC} variable will be tokenized and parsed like
 255 the command line.  The remaining variables are tested for existence and their
 256 values are treated like option arguments.
 257
 258
 259 @noindent
 260 @code{libopts} will search in 2 places for configuration files:
 261 @itemize @bullet
 262 @item
 263 $HOME
 264 @item
 265 $PWD
 266 @end itemize
 267 The environment variables @code{HOME}, and @code{PWD}
 268 are expanded and replaced when @file{ntpdc} runs.
 269 For any of these that are plain files, they are simply processed.
 270 For any that are directories, then a file named @file{.ntprc} is searched for
 271 within that directory and processed.
 272
 273 Configuration files may be in a wide variety of formats.
 274 The basic format is an option name followed by a value (argument) on the
 275 same line.  Values may be separated from the option name with a colon,
 276 equal sign or simply white space.  Values may be continued across multiple
 277 lines by escaping the newline with a backslash.
 278
 279 Multiple programs may also share the same initialization file.
 280 Common options are collected at the top, followed by program specific
 281 segments.  The segments are separated by lines like:
 282 @example
 283 [NTPDC]
 284 @end example
 285 @noindent
 286 or by
 287 @example
 288 <?program ntpdc>
 289 @end example
 290 @noindent
 291 Do not mix these styles within one configuration file.
 292
 293 Compound values and carefully constructed string values may also be
 294 specified using XML syntax:
 295 @example
 296 <option-name>
 297    <sub-opt>...&lt;...&gt;...</sub-opt>
 298 </option-name>
 299 @end example
 300 @noindent
 301 yielding an @code{option-name.sub-opt} string value of
 302 @example
 303 "...<...>..."
 304 @end example
 305 @code{AutoOpts} does not track suboptions.  You simply note that it is a
 306 hierarchicly valued option.  @code{AutoOpts} does provide a means for searching
 307 the associated name/value pair list (see: optionFindValue).
 308
 309 The command line options relating to configuration and/or usage help are:
 310
 311 @subsubheading version (-)
 312
 313 Print the program version to standard out, optionally with licensing
 314 information, then exit 0.  The optional argument specifies how much licensing
 315 detail to provide.  The default is to print just the version.  The licensing infomation may be selected with an option argument.
 316 Only the first letter of the argument is examined:
 317
 318 @table @samp
 319 @item version
 320 Only print the version.  This is the default.
 321 @item copyright
 322 Name the copyright usage licensing terms.
 323 @item verbose
 324 Print the full copyright usage licensing terms.
 325 @end table
 326
 327 @node ntpdc exit status
 328 @subsection ntpdc exit status
 329
 330 One of the following exit values will be returned:
 331 @table @samp
 332 @item 0 (EXIT_SUCCESS)
 333 Successful program execution.
 334 @item 1 (EXIT_FAILURE)
 335 The operation failed or the command syntax was not valid.
 336 @item 66 (EX_NOINPUT)
 337 A specified configuration file could not be loaded.
 338 @item 70 (EX_SOFTWARE)
 339 libopts had an internal operational error.  Please report
 340 it to autogen-users@@lists.sourceforge.net.  Thank you.
 341 @end table
 342 @node ntpdc Usage
 343 @subsection ntpdc Usage
 344 @node ntpdc See Also
 345 @subsection ntpdc See Also
 346 @node ntpdc Authors
 347 @subsection ntpdc Authors
 348 @node ntpdc Bugs
 349 @subsection ntpdc Bugs