=head1 NAME

buffchan - Buffered file-writing backend for INN

=head1 SYNOPSIS

B<buffchan> [B<-bru>] [B<-c> I<lines>] [B<-C> I<seconds>] [B<-d>
I<directory>] [B<-f> I<num-fields>] [B<-l> I<lines>] [B<-L> I<seconds>]
[B<-m> I<map>] [B<-p> I<pid-file>] [B<-s> I<format>]

=head1 DESCRIPTION

B<buffchan> reads lines from standard input and copies the initial fields
in each line to the files named by the remaining fields on the line.
B<buffchan> is intended to be called by B<innd> as an exploder feed.

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.

For each line of input, B<buffchan> 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 B<-c>, B<-C>, B<-l>, and B<-L>
options.

As an exploder feed (see newsfeeds(5) for an explanation), B<buffchan>
interprets lines beginning with an exclamation point as commands.  Besides
C<!begin> (which only marks the start of the feed), there are three
supported commands:

=over 4

=item !flush [I<site>]

The flush command closes and reopens all open files.  An optional site can
be specified, in which case B<buffchan> flushes only that file.  This
command is analogous to the C<ctlinnd flush> command.  This command can be
sent via B<innd> using C<ctlinnd send I<buffchan-site> 'flush I<site>'>.

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 fchmod(3) is available, B<buffchan> 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.

=item !drop [I<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.)

When a C<ctlinnd drop site> command is sent, B<innd> will automatically
forward the command to B<buffchan> if the site is listed as a funnel
feeding into the B<buffchan> exploder.  To drop all sites, use C<ctlinnd
send I<buffchan-site> drop>.

=item !readmap

The map file specified with the B<-m> option, if given, will be reloaded.

=back

Once B<buffchan> 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.

=head1 OPTIONS

=over 4

=item B<-b>

Force the output to be buffered.  (This is generally the default, but it
may depend on the operating system.)  If B<-b> is given, a buffer size of
BUFSIZ (a constant of the system standard I/O library) is used.

=item B<-c> I<lines>

If the B<-c> flag is given, B<buffchan> will close and reopen a file after
every I<lines> lines are written to the file.

=item B<-C> I<seconds>

If the B<-C> flag is given, B<buffchan> will close and reopen a file if it
has been open for more than I<seconds> seconds.

=item B<-d> I<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 B<-s> flag
(see below) is changed to be a simple C<%s> (in other words, output files
are considered to be relative to I<directory>).

=item B<-f> I<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, I<num-fields> will
be used as the number of initial fixed fields.

=item B<-l> I<lines>

If the B<-l> flag is given, B<buffchan> will flush the output after every
I<lines> lines are written to a file.

=item B<-L> I<seconds>

If the B<-L> flag is given, B<buffchan> will flush each output file every
I<seconds> seconds.

=item B<-m> I<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 F<newsfeeds>, but the output files should use the full
domain names of remote peers.

In the map file, blank lines and lines starting with a number sign (C<#>)
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:

    # This is a comment
    uunet:news.uu.net
    foo:foo.com
    munnari:munnari.oz.au

=item B<-p> I<pid-file>

If the B<-p> option is given, B<buffchan> will write a line containing its
process ID (in text) to the specified file when it starts.

=item B<-r>

By default, B<buffchan> sends its error messages to I<pathlog>/errlog.  To
suppress this redirection and send error messages to standard error, use
the B<-r> flag.

=item B<-s>

The B<-s> 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 sprintf(3) format string that should contain a single instance of
C<%s>, which will be replaced with the value of the filename field
(possibly after mapping with the map file from B<-m>).  The default value
is I<pathoutgoing>/C<%s>.

=item B<-u>

If the B<-u> flag is used, the output will be unbuffered.

=back

=head1 EXAMPLES

If B<buffchan> is invoked with C<-f 2> and given the following input:

    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

Then the file F<foo> will have these lines:

    news/software/b/132 <1643@munnari.oz.au>
    comp/sources/unix/2002 <999@news.foo.com>

the file F<munnari> will have these lines:

    news/software/b/133 <102060@litchi.foo.com>
    comp/sources/unix/2002 <999@news.foo.com>

and the file F<uunet> will have these lines:

    news/software/b/132 <1643@munnari.oz.au>
    news/software/b/133 <102060@litchi.foo.com>
    comp/sources/unix/2002 <999@news.foo.com>

=head1 HISTORY

Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.  Converted to
POD by Russ Allbery <eagle@eyrie.org>.

$Id: buffchan.pod 9767 2014-12-07 21:13:43Z iulius $

=head1 SEE ALSO

ctlinnd(8), filechan(8), inn.conf(5), innd(8), newsfeeds(5).

=cut
