contrib/ntp/scripts/update-leap/invoke-update-leap.texi

   1 @node update-leap Invocation
   2 @section Invoking update-leap
   3 @pindex update-leap
   4 @cindex leap-seconds file manager/updater
   5 @ignore
   6 #
   7 # EDIT THIS FILE WITH CAUTION  (invoke-update-leap.texi)
   8 #
   9 # It has been AutoGen-ed  April  7, 2015 at 04:21:44 AM by AutoGen 5.18.5pre4
  10 # From the definitions    update-leap-opts.def
  11 # and the template file   agtexi-cmd.tpl
  12 @end ignore
  13
  14
  15
  16 @code{update-leap}
  17 will validate the file currently on the local system
  18 and if necessary, updates leap-second definition file.
  19
  20 Ordinarily, the file is found using the "leapfile" directive in
  21 @code{ntp.conf(5)}.
  22 However, an alternate location can be specified on the command line.
  23
  24 If the file does not exist, is not valid, has expired, or is expiring soon,
  25 a new copy will be downloaded.  If the new copy validates, it is installed and
  26 NTP is (optionally) restarted.
  27
  28 If the current file is acceptable, no download or restart occurs.
  29
  30 -c can also be used to invoke another script to perform administrative
  31 functions, e.g. to copy the file to other local systems.
  32 .PP
  33 This can be run as a cron job.  As the file is rarely updated, and leap
  34 seconds are announced at least one month in advance (usually longer), it
  35 need not be run more frequently than about once every three weeks.
  36 .PP
  37 For cron-friendly behavior, define CRONJOB=1 in the crontab.
  38 .PP
  39 This script depends on$REQUIREDCMDS
  40
  41 This section was generated by @strong{AutoGen},
  42 using the @code{agtexi-cmd} template and the option descriptions for the @code{update-leap} program.
  43
  44 @menu
  45 * update-leap usage::                  update-leap help/usage (@option{--help})
  46 * update-leap source-url::             source-url option (-s)
  47 * update-leap ipv4::                   ipv4 option (-4)
  48 * update-leap destination::            destination option (-d)
  49 * update-leap expiration::             expiration option (-e)
  50 * update-leap ntp-conf-file::          ntp-conf-file option (-f)
  51 * update-leap force-update::           force-update option (-F)
  52 * update-leap exit status::            exit status
  53 * update-leap Usage::                  Usage
  54 * update-leap Authors::                Authors
  55 @end menu
  56
  57 @node update-leap usage
  58 @subsection update-leap help/usage (@option{--help})
  59 @cindex update-leap help
  60
  61 This is the automatically generated usage text for update-leap.
  62
  63 The text printed is the same whether selected with the @code{help} option
  64 (@option{--help}) or the @code{more-help} option (@option{--more-help}).  @code{more-help} will print
  65 the usage text by passing it through a pager program.
  66 @code{more-help} is disabled on platforms without a working
  67 @code{fork(2)} function.  The @code{PAGER} environment variable is
  68 used to select the program, defaulting to @file{more}.  Both will exit
  69 with a status code of 0.
  70
  71 @exampleindent 0
  72 @example
  73 /bin/bash: line 136: ./update-leap: Permission denied
  74 @end example
  75 @exampleindent 4
  76
  77 @node update-leap source-url
  78 @subsection source-url option (-s)
  79 @cindex update-leap-source-url
  80
  81 This is the ``the url of the master copy of the leapseconds file'' option.
  82 This option takes a string argument.
  83 Specify the URL of the master copy to download
  84 $LEAPSRC
  85 @node update-leap ipv4
  86 @subsection ipv4 option (-4)
  87 @cindex update-leap-ipv4
  88
  89 This is the ``use only ipv4 addresses for dns name resolution'' option.
  90
  91 @noindent
  92 This option has some usage constraints.  It:
  93 @itemize @bullet
  94 @item
  95 must not appear in combination with any of the following options:
  96 ipv6.
  97 @end itemize
  98
  99         Force DNS resolution of following host names on the command line
 100         to the IPv4 namespace.
 101         _EndOfDoc_;
 102 };
 103
 104 flag = {
 105     name      = ipv6;
 106     flags-cant = ipv4, prefer;
 107     value     = 6;
 108     descrip   = "Use only IPv6 addresses for DNS name resolution";
 109     doc = <<-  _EndOfDoc_
 110         Force DNS resolution of following host names on the command line
 111         to the IPv6 namespace.
 112         _EndOfDoc_;
 113 };
 114
 115 flag = {
 116     name        = prefer;
 117     flags-cant  = ipv4, ipv6;
 118     value       = p;
 119     arg-type    = keyword;
 120     keyword     = 4, 6;
 121     descrip     = 'Prefer IPv4 or IPv6 (as specified) addresses, but use either';
 122     doc         = <<-  _EndOfDoc_
 123 Prefer IPv4 or IPv6 (as specified) addresses, but use either.
 124 @node update-leap destination
 125 @subsection destination option (-d)
 126 @cindex update-leap-destination
 127
 128 This is the ``filename on the local system'' option.
 129 This option takes a string argument @file{float}.
 130 The name to use to store the leapfile on the local system.
 131 $LEAPFILE
 132 @node update-leap expiration
 133 @subsection expiration option (-e)
 134 @cindex update-leap-expiration
 135
 136 This is the ``refresh the leapfile this long before it expires'' option.
 137 This option takes a string argument.
 138 Specify how long before expiration the file is to be refreshed
 139 Units are required, e.g. "-e 60 days"  Note that larger values
 140 imply more frequent refreshes.
 141 "$PREFETCH"
 142 @node update-leap ntp-conf-file
 143 @subsection ntp-conf-file option (-f)
 144 @cindex update-leap-ntp-conf-file
 145
 146 This is the ``location of the ntp.conf file'' option.
 147 This option takes a string argument.
 148 Specify location of ntp.conf (used to make sure leapfile directive is
 149 present and to default  leapfile)
 150 /etc/ntp.conf
 151 @node update-leap force-update
 152 @subsection force-update option (-F)
 153 @cindex update-leap-force-update
 154
 155 This is the ``force update of the leapfile'' option.
 156 Force update even if current file is OK and not close to expiring.
 157 @node update-leap exit status
 158 @subsection update-leap exit status
 159
 160 One of the following exit values will be returned:
 161 @table @samp
 162 @item 0 (EXIT_SUCCESS)
 163 Successful program execution.
 164 @item 1 (EXIT_FAILURE)
 165 The operation failed or the command syntax was not valid.
 166 @end table
 167 @node update-leap Usage
 168 @subsection update-leap Usage
 169 @node update-leap Authors
 170 @subsection update-leap Authors