=pod

=head1 NAME

B<rwappend> - Append SiLK Flow file(s) to an existing SiLK Flow file

=head1 SYNOPSIS

  rwappend [--create=[TEMPLATE_FILE]] [--site-config-file=FILENAME]
        [--print-statistics] TARGET_FILE SOURCE_FILE [SOURCE_FILE...]

=head1 DESCRIPTION

B<rwappend> reads SiLK Flow records from the specified I<SOURCE_FILE>s
and appends them to the I<TARGET_FILE>.  If C<stdin> is used as the
name of one of the I<SOURCE_FILE>s, SiLK flow records will be read
from the standard input.

When the I<TARGET_FILE> does not exist and the B<--create> switch is
not provided, B<rwappend> will exit with an error.  When B<--create>
is specified and I<TARGET_FILE> does not exist, B<rwappend> will
create the I<TARGET_FILE> using the same format, version, and
byte-order as the specified I<TEMPLATE_FILE>.  If no I<TEMPLATE_FILE>
is given, the I<TARGET_FILE> is created in the default format and
version (the same format that B<rwcat(1)> would produce).

The I<TARGET_FILE> must not be compressed (i.e., in may not end in the
C<.gz> extension).

=head1 OPTIONS

Option names may be abbreviated if the abbreviation is unique or is an
exact match for an option.  A parameter to an option may be specified
as B<--arg>=I<param> or S<B<--arg> I<param>>, though the first form is
required for options that take optional parameters.

=over 4

=item B<--create>

=item B<--create>=I<TEMPLATE_FILE>

Create the I<TARGET_FILE> if it does not exist.  The file will have
the same format, version, and byte-order as the I<TEMPLATE_FILE> if it
is provided; otherwise the defaults are used.  The I<TEMPLATE_FILE>
will B<NOT> be appended to I<TARGET_FILE> unless it also appears in
as the name of a I<SOURCE_FILE>. 

=item B<--print-statistics>

Print the number of records read from each I<SOURCE_FILE> and the
total number of records appened to the I<TARGET_FILE>.

=item B<--site-config-file>=I<FILENAME>

Read the SiLK site configuration from the named file I<FILENAME>.
When this switch is not provided, the location specified by the
C<$SILK_CONFIG_FILE> environment variable is used if that variable is
not empty.  The value of C<$SILK_CONFIG_FILE> should include the name
of the file.  Otherwise, the application looks for a file named
F<silk.conf> in the following directories: the directory specified in
the F<$SILK_DATA_ROOTDIR> environment variable; the data root
directory that is compliled into SiLK (use the B<--version> switch to
view this value); the directories F<$SILK_PATH/share/silk/>,
F<$SILK_PATH/share/>, or F<$SILK_PATH>; or in the F<share/silk/> and
F<share/> directories parallel to the application's directory.

=back

=head1 EXAMPLES

Standard usage where F<results.dat> exists:

  rwappend results.dat sample5.dat sample6.dat

To append files F<sample*.dat> to F<results.dat>, or to create
F<results.dat> using the same format as the first file argument (note
that F<sample1.dat> must be repeated):

 rwappend results.dat --create=sample1.dat \
       sample1.dat sample2.dat

If results.dat does not exist, the following two commands are
equivalent:

  rwappend --create results.dat sample1.dat sample2.dat

  rwcat sample1.dat sample2.dat > results.dat

=head1 BUGS

B<rwappend> makes some attempts to avoid appending a file to itself
(which would eventually exhaust the disk space) by comparing the names
of files it is given; it should be smarter about this.

=head1 SEE ALSO

B<rwcat(1)>

=cut

$SiLK: rwappend.pod 6791 2007-04-04 18:10:34Z mthomas $

Local Variables:
mode:text
indent-tabs-mode:nil
End: