.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "BUFFCHAN 8"
.TH BUFFCHAN 8 "2015-09-12" "INN 2.6.1" "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"
buffchan \- Buffered file\-writing backend for INN
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBbuffchan\fR [\fB\-bru\fR] [\fB\-c\fR \fIlines\fR] [\fB\-C\fR \fIseconds\fR] [\fB\-d\fR
\&\fIdirectory\fR] [\fB\-f\fR \fInum-fields\fR] [\fB\-l\fR \fIlines\fR] [\fB\-L\fR \fIseconds\fR]
[\fB\-m\fR \fImap\fR] [\fB\-p\fR \fIpid-file\fR] [\fB\-s\fR \fIformat\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBbuffchan\fR reads lines from standard input and copies the initial fields
in each line to the files named by the remaining fields on the line.
\&\fBbuffchan\fR is intended to be called by \fBinnd\fR as an exploder feed.
.PP
The input is interpreted as a sequence of lines.  Each line contains a
fixed number of initial fields, followed by a variable number of filename
fields.  All fields in a line are separated by whitespace and do not
contain any whitespace.  The default number of initial fields is one.
.PP
For each line of input, \fBbuffchan\fR writes the initial fields, separated
by a space and followed by a newline, to each of the files named in the
filename fields.  The output files are kept open and are only flushed or
closed based on the schedule given by the \fB\-c\fR, \fB\-C\fR, \fB\-l\fR, and \fB\-L\fR
options.
.PP
As an exploder feed (see \fInewsfeeds\fR\|(5) for an explanation), \fBbuffchan\fR
interprets lines beginning with an exclamation point as commands.  Besides
\&\f(CW\*(C`!begin\*(C'\fR (which only marks the start of the feed), there are three
supported commands:
.IP "!flush [\fIsite\fR]" 4
.IX Item "!flush [site]"
The flush command closes and reopens all open files.  An optional site can
be specified, in which case \fBbuffchan\fR flushes only that file.  This
command is analogous to the \f(CW\*(C`ctlinnd flush\*(C'\fR command.  This command can be
sent via \fBinnd\fR using \f(CW\*(C`ctlinnd send \f(CIbuffchan\-site\f(CW \*(Aqflush \f(CIsite\f(CW\*(Aq\*(C'\fR.
.Sp
Applications can tell that flush has completed by renaming the file before
issuing the command.  When the original file name has reappeared, the
flush is complete.  If \fIfchmod\fR\|(3) is available, \fBbuffchan\fR also changes
the file to read-only while it's actively writing to it and changes it
back to read/write once it has been closed.  It will change the mode back
to read-only only if it reopens the same file.
.IP "!drop [\fIsite\fR]" 4
.IX Item "!drop [site]"
The drop command is similar to the flush command, except that no files are
reopened.  If given an argument, only the specified site is dropped;
otherwise, all sites are dropped.  (Note that a site will be restarted if
the input stream mentions the site again.)
.Sp
When a \f(CW\*(C`ctlinnd drop site\*(C'\fR command is sent, \fBinnd\fR will automatically
forward the command to \fBbuffchan\fR if the site is listed as a funnel
feeding into the \fBbuffchan\fR exploder.  To drop all sites, use \f(CW\*(C`ctlinnd
send \f(CIbuffchan\-site\f(CW drop\*(C'\fR.
.IP "!readmap" 4
.IX Item "!readmap"
The map file specified with the \fB\-m\fR option, if given, will be reloaded.
.PP
Once \fBbuffchan\fR opens a file, it keeps it open (in the absence of a drop
command).  The input must therefore never specify more files than the
maximum number of files a process may open.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-b\fR" 4
.IX Item "-b"
Force the output to be buffered.  (This is generally the default, but it
may depend on the operating system.)  If \fB\-b\fR is given, a buffer size of
\&\s-1BUFSIZ \s0(a constant of the system standard I/O library) is used.
.IP "\fB\-c\fR \fIlines\fR" 4
.IX Item "-c lines"
If the \fB\-c\fR flag is given, \fBbuffchan\fR will close and reopen a file after
every \fIlines\fR lines are written to the file.
.IP "\fB\-C\fR \fIseconds\fR" 4
.IX Item "-C seconds"
If the \fB\-C\fR flag is given, \fBbuffchan\fR will close and reopen a file if it
has been open for more than \fIseconds\fR seconds.
.IP "\fB\-d\fR \fIdirectory\fR" 4
.IX Item "-d directory"
This flag may be used to specify a directory the program should change to
before starting.  If this flag is used, the default for the \fB\-s\fR flag
(see below) is changed to be a simple \f(CW%s\fR (in other words, output files
are considered to be relative to \fIdirectory\fR).
.IP "\fB\-f\fR \fInum-fields\fR" 4
.IX Item "-f num-fields"
By default, each line is expected to contain one fixed field followed by
some number of filename fields.  If this flag is given, \fInum-fields\fR will
be used as the number of initial fixed fields.
.IP "\fB\-l\fR \fIlines\fR" 4
.IX Item "-l lines"
If the \fB\-l\fR flag is given, \fBbuffchan\fR will flush the output after every
\&\fIlines\fR lines are written to a file.
.IP "\fB\-L\fR \fIseconds\fR" 4
.IX Item "-L seconds"
If the \fB\-L\fR flag is given, \fBbuffchan\fR will flush each output file every
\&\fIseconds\fR seconds.
.IP "\fB\-m\fR \fImap\fR" 4
.IX Item "-m map"
Map files translate the names in the filename fields on each line into
filenames that should be used instead.  It's used primarily when short
names are used in \fInewsfeeds\fR, but the output files should use the full
domain names of remote peers.
.Sp
In the map file, blank lines and lines starting with a number sign (\f(CW\*(C`#\*(C'\fR)
are ignored.  All other lines should have two host names separated by a
colon.  The first field is the name that may appear in the input stream;
the second field names the file to be used when the name in the first
field appears.  For example:
.Sp
.Vb 4
\&    # This is a comment
\&    uunet:news.uu.net
\&    foo:foo.com
\&    munnari:munnari.oz.au
.Ve
.IP "\fB\-p\fR \fIpid-file\fR" 4
.IX Item "-p pid-file"
If the \fB\-p\fR option is given, \fBbuffchan\fR will write a line containing its
process \s-1ID \s0(in text) to the specified file when it starts.
.IP "\fB\-r\fR" 4
.IX Item "-r"
By default, \fBbuffchan\fR sends its error messages to \fIpathlog\fR/errlog.  To
suppress this redirection and send error messages to standard error, use
the \fB\-r\fR flag.
.IP "\fB\-s\fR" 4
.IX Item "-s"
The \fB\-s\fR flag may be used to specify a format that maps a filename from
the filename fields at the end of each line to an actual filename.  This
is a \fIsprintf\fR\|(3) format string that should contain a single instance of
\&\f(CW%s\fR, which will be replaced with the value of the filename field
(possibly after mapping with the map file from \fB\-m\fR).  The default value
is \fIpathoutgoing\fR/\f(CW%s\fR.
.IP "\fB\-u\fR" 4
.IX Item "-u"
If the \fB\-u\fR flag is used, the output will be unbuffered.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
If \fBbuffchan\fR is invoked with \f(CW\*(C`\-f 2\*(C'\fR and given the following input:
.PP
.Vb 3
\&    news/software/b/132 <1643@munnari.oz.au> foo uunet
\&    news/software/b/133 <102060@litchi.foo.com> uunet munnari
\&    comp/sources/unix/2002 <999@news.foo.com> foo uunet munnari
.Ve
.PP
Then the file \fIfoo\fR will have these lines:
.PP
.Vb 2
\&    news/software/b/132 <1643@munnari.oz.au>
\&    comp/sources/unix/2002 <999@news.foo.com>
.Ve
.PP
the file \fImunnari\fR will have these lines:
.PP
.Vb 2
\&    news/software/b/133 <102060@litchi.foo.com>
\&    comp/sources/unix/2002 <999@news.foo.com>
.Ve
.PP
and the file \fIuunet\fR will have these lines:
.PP
.Vb 3
\&    news/software/b/132 <1643@munnari.oz.au>
\&    news/software/b/133 <102060@litchi.foo.com>
\&    comp/sources/unix/2002 <999@news.foo.com>
.Ve
.SH "HISTORY"
.IX Header "HISTORY"
Written by Rich \f(CW$alz\fR <rsalz@uunet.uu.net> for InterNetNews.  Converted to
\&\s-1POD\s0 by Russ Allbery <eagle@eyrie.org>.
.PP
\&\f(CW$Id:\fR buffchan.pod 9767 2014\-12\-07 21:13:43Z iulius $
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIctlinnd\fR\|(8), \fIfilechan\fR\|(8), \fIinn.conf\fR\|(5), \fIinnd\fR\|(8), \fInewsfeeds\fR\|(5).