doc/man/batcher.8

   1 .\" $Revision: 6491 $
   2 .TH BATCHER 8
   3 .SH NAME
   4 batcher \- article-batching backend for InterNetNews
   5 .SH SYNOPSIS
   6 .B batcher
   7 [
   8 .BI \-a " arts"
   9 ]
  10 [
  11 .BI \-A " total_arts"
  12 ]
  13 [
  14 .BI \-b " size"
  15 ]
  16 [
  17 .BI \-B " total_size"
  18 ]
  19 [
  20 .BI \-i " string"
  21 ]
  22 [
  23 .BI \-N " num_batches"
  24 ]
  25 [
  26 .BI \-p " process"
  27 ]
  28 [
  29 .B \-r
  30 ]
  31 [
  32 .BI \-s " separator"
  33 ]
  34 [
  35 .BI \-S " alt_spool"
  36 ]
  37 [
  38 .B \-v
  39 ]
  40 .I host
  41 [
  42 .I input
  43 ]
  44 .SH DESCRIPTION
  45 .I Batcher
  46 reads uses a list of files to prepare news batches for the specified
  47 .IR host .
  48 It is normally invoked by a script run out of
  49 .IR cron (8)
  50 that uses
  51 .IR shlock (1)
  52 to lock the host name, followed by a
  53 .IR ctlinnd (8)
  54 command to flush the batchfile.
  55 .PP
  56 .I Batcher
  57 reads the named
  58 .I input
  59 file, or standard input if no file is given.
  60 Relative pathnames are interpreted from the
  61 .I <pathoutgoing in inn.conf>
  62 directory.
  63 The input is taken as a sequence of lines;
  64 blank lines and lines starting with a number sign (``#'') are ignored.
  65 All other lines should consist of one or two fields separated by a single space.
  66 The first field is either the storage token of an article or the
  67 name of a file holding an article; if it is not an an absolute
  68 pathname or storage token, it is taken relative to
  69 .IR <patharticles\ in\ inn.conf> .
  70 The second field, if present, specifies the size of the article in bytes.
  71 .SH OPTIONS
  72 .TP
  73 .B \-S alt_spool
  74 The ``\-S'' flag may be used to specify an alternate spool directory to
  75 use if the article is not found; this would perhaps be an NFS-mounted
  76 spool directory of a master server with longer expiration times.
  77 .TP
  78 .B \-r
  79 By default, the program reports errors to
  80 .IR <pathlog\ in\ inn.conf>/errlog .
  81 To suppress this redirection and report errors to standard error,
  82 use the ``\-r'' flag.
  83 .TP
  84 .B \-v
  85 Upon exit,
  86 .I batcher
  87 reports statistics via
  88 .IR syslog (3).
  89 If the ``\-v'' flag is used, they will also be printed on the standard
  90 output.
  91 .TP
  92 .B \-b size
  93 .I Batcher
  94 collects the text of the named articles into batches.
  95 To limit the size of each batch, use the ``\-b'' flag.
  96 The default size is 60 kilobytes.
  97 Using ``\-b\ 0'' allows unlimited batch sizes.
  98 .TP
  99 .B \-a arts
 100 To limit the number of articles in each batch, use the ``\-a'' flag.
 101 The default is no limit.
 102 A new batch will be started when either the byte count or number of
 103 articles written exceeds the specified limits.
 104 .TP
 105 .B \-B total_size
 106 To limit the total number of bytes written for all batches, use the ``\-B''
 107 flag.
 108 .TP
 109 .B \-A total_arts
 110 To limit the total number of articles that can be batched use the ``\-A''
 111 flag.
 112 .TP
 113 .B \-N num_batches
 114 To limit the total number of batches that should be created use the ``\-N''
 115 flag.
 116 .IP
 117 In all three of the above cases, the default is zero, that is, no limit.
 118 .TP
 119 .B \-i string
 120 A batch starts with an identifying line to specify the unpacking method
 121 to be used on the receiving end.
 122 When the ``\-i'' flag is used, the initial string,
 123 .IR string ,
 124 followed by a newline, will be output at the start of every batch.
 125 The default is to have no initial string.
 126 .TP
 127 .B \-s separator
 128 Each article starts with a separator line to indicate the size of the article.
 129 To specify the separator use the ``\-s'' flag.
 130 This is a
 131 .IR sprintf (3)
 132 format string which can have a single ``%ld'' parameter which will be given
 133 the size of the article.
 134 If the separator is not empty, then the string and a newline will be output
 135 before every article.
 136 The default separator is ``#!\ rnews\ %ld''.
 137 .TP
 138 .B \-p process
 139 By default, batches are written to standard output, which
 140 is not useful when more than one output batch is created.
 141 Use the ``\-p'' flag to specify the shell command that should be
 142 created (via
 143 .IR popen (3))
 144 whenever a new batch is started.
 145 The process is a
 146 .IR sprintf (3)
 147 format string which can have a single ``%s'' parameter which will be given
 148 the host name.
 149 A common value is:
 150 .PP
 151 .RS
 152 .nf
 153 ( echo '#! cunbatch' ; exec compress ) | uux \- \-r \-z %s!rnews
 154 .fi
 155 .RE
 156 .SH EXIT STATUS
 157 .PP
 158 If the input is exhausted,
 159 .I batcher
 160 will exit with a zero status.
 161 If any of the limits specified with the ``\-B'', ``\-A'', or ``\-N'' flags
 162 is reached, or if there is an error writing the batch, then
 163 .I batcher
 164 will try to spool the remaining input, copying it to a file.
 165 If there was no input filename, standard input will be copied to
 166 .I <pathoutgoing in inn.conf>/host
 167 and the program will exit.
 168 If an input filename was given, the input will be copied to
 169 a temporary file named
 170 .IR input .bch
 171 (if
 172 .I input
 173 is an absolute pathname)
 174 or
 175 .I <pathoutgoing in inn.conf>/input.bch
 176 (if the filename does not begin with a slash).
 177 Once the input is copied,
 178 .I batcher
 179 will try to rename this temporary file to be the name of the input file,
 180 and then exit.
 181 .PP
 182 Upon receipt of an interrupt or termination signal,
 183 .I batcher
 184 will finish sending the current article, close the batch, and then
 185 rewrite the batchfile according as described in the previous paragraph.
 186 .SH HISTORY
 187 Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.
 188 .de R$
 189 This is revision \\$3, dated \\$4.
 190 ..
 191 .R$ $Id: batcher.8 6491 2003-10-18 05:56:37Z rra $
 192 .SH "SEE ALSO"
 193 ctlinnd(8),
 194 inn.conf(5),
 195 newsfeeds(5),
 196 shlock(1).