.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "BATCHER 8" .TH BATCHER 8 2024-04-01 "INN 2.7.2" "InterNetNews Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME batcher \- Article batching for InterNetNews .SH SYNOPSIS .IX Header "SYNOPSIS" \&\fBbatcher\fR [\fB\-rv\fR] [\fB\-a\fR \fIarticles\fR] [\fB\-A\fR \fItotal-articles\fR] [\fB\-b\fR \fIsize\fR] [\fB\-B\fR \fItotal-size\fR] [\fB\-i\fR \fIstring\fR] [\fB\-N\fR \fIbatches\fR] [\fB\-p\fR \fIprocess\fR] [\fB\-s\fR \fIseparator\fR] \&\fIhost\fR [\fIinput\fR] .SH DESCRIPTION .IX Header "DESCRIPTION" \&\fBbatcher\fR reads a list of files and prepares news batches for the specified host. It is generally used to prepare UUCP feeds, but the resulting batches can be used by any application that uses rnews(1) to inject the articles. It is normally invoked by a script run out of cron that uses \fBshlock\fR to lock the host, followed by \fBctlinnd\fR to flush the batch file. See send\-uucp(8) for a front-end for \fBbatcher\fR. .PP \&\fBbatcher\fR reads the file \fIinput\fR, or standard input if no file is given. If \fIinput\fR is a relative file name, it is assumed to be in \&\fIpathoutgoing\fR as set in \fIinn.conf\fR. Blank lines and lines starting with a number sign (\f(CW\*(C`#\*(C'\fR) are ignored. All other lines in the input should consist of one or two fields separated by a single space. The first field is the storage API token of an article. The second field, if present, specifies the size of the article in bytes. .PP By default, batches are written to standard output (which isn't very useful if more than one batch is output), but see the \fB\-p\fR option. .SH OPTIONS .IX Header "OPTIONS" .IP "\fB\-a\fR \fIarticles\fR" 4 .IX Item "-a articles" This flag limits the number of articles included in each batch. The default is no limit. A new batch will be started when either the total bytes or the number of articles written exceeds the specified limits. .IP "\fB\-A\fR \fItotal-articles\fR" 4 .IX Item "-A total-articles" Limits the total number of articles written for all batches. As soon as the total number of articles written to batches reaches or exceeds \&\fItotal-articles\fR, all additional articles in the input will be deferred. The default is no limit. .IP "\fB\-b\fR \fIsize\fR" 4 .IX Item "-b size" This flag sets the size limit for each batch; as soon as at least this much data has been written out, a new batch will be started. The default size is 60\ KB. Using \f(CW\*(C`\-b 0\*(C'\fR will allow unlimited batch sizes. .IP "\fB\-B\fR \fItotal-size\fR" 4 .IX Item "-B total-size" Limits the total number of bytes written for all batches. As soon as the total bytes written to batches reaches or exceeds \fItotal-size\fR, all additional articles in the input will be deferred. The default is no limit. .IP "\fB\-i\fR \fIstring\fR" 4 .IX Item "-i string" A batch starts with an identifying line to specify the unpacking method to be used on the receiving end. When this flag is used, \fIstring\fR, followed by a newline, will be output at the start of each batch. The default is to have no initial string (under the assumption that either the processor specified with the \fB\-p\fR flag or some other later process will add the appropriate line). .IP "\fB\-N\fR \fIbatches\fR" 4 .IX Item "-N batches" Limits the total number of batches written. As soon as the number of batches written reaches or exceeds \fIbatches\fR, all additional articles in the input will be deferred. The default is no limit. .IP "\fB\-p\fR \fIprocess\fR" 4 .IX Item "-p process" By default, batches are written to standard output, which is not useful when more than one output batch is created. If this option is given, each batch will instead be fed via a pipe to the shell command \fIprocess\fR. The \&\fIprocess\fR argument must be an sprintf(3) format string, which may have a single \f(CW\*(C`%s\*(C'\fR parameter that will be replaced with the host name. .Sp A common value is: .Sp .Vb 1 \& ( echo \*(Aq#! gunbatch\*(Aq ; exec gzip \-c ) | uux \- \-r \-z %s!rnews .Ve .Sp which generates gzip-compressed batches and feeds them to \fBuux\fR. .IP \fB\-r\fR 4 .IX Item "-r" By default, \fBbatcher\fR reports errors to \fIpathlog\fR/errlog. To suppress this redirection and report errors to standard error, use the \fB\-r\fR flag. .IP "\fB\-s\fR \fIseparator\fR" 4 .IX Item "-s separator" Each article in a batch starts with a separator line that indicates the size of the article. \fIseparator\fR must be an sprintf(3) string, which may have a single \f(CW\*(C`%ld\*(C'\fR in the string that will be replaced with the size of the article. If the separator is not empty, a newline will also be appended to it when it is added to the beginning of each article. .Sp The default separator is: .Sp .Vb 1 \& #! rnews %ld .Ve .Sp and this should rarely be changed. .IP \fB\-v\fR 4 .IX Item "-v" Upon exit, \fBbatcher\fR reports statistics via syslog. With this flag, the statistics will also be printed to standard output. .SH "EXIT STATUS" .IX Header "EXIT STATUS" If the input is exhausted and all batches are created successfully, \&\fBbatcher\fR will exit with a zero status. .PP If any of the limits specified with \fB\-A\fR, \fB\-B\fR, or \fB\-N\fR flags are reached, or if there is an error in writing a batch, \fBbatcher\fR will try to spool the remaining input by copying it to a file as follows: .IP \(bu 2 If there was no input filename, the remaining input will be copied to \&\fIpathoutgoing\fR/\fIhost\fR. .IP \(bu 2 If an input filename was given, the remaining input will be copied to a temporary file named by appending \f(CW\*(C`.bch\*(C'\fR to the end of \fIinput\fR (and qualified by adding \fIpathoutgoing\fR if \fIinput\fR was not a fully qualified path). If this happens successfully, \fBbatcher\fR will then try to rename this temporary file to \fIinput\fR (thus replacing \fIinput\fR with a copy of itself with all of lines for the successfully batched articles removed). .PP Upon receipt of an interrupt or termination signal, \fBbatcher\fR will finish batching the current article, close the batch, and then rewrite the batch file as described above. .SH HISTORY .IX Header "HISTORY" Written by Rich $alz for InterNetNews. Rewritten by Russ Allbery in POD. .SH "SEE ALSO" .IX Header "SEE ALSO" ctlinnd(8), inn.conf(5), newsfeeds(5), rnews(1), send\-uucp(8), shlock(1).