X-Git-Url: https://git.gag.com/?p=debian%2Famanda;a=blobdiff_plain;f=perl%2FAmanda%2FXfer.pod;h=d09923c7e5c291e32fd16ec0ef95728202072448;hp=772474b0b38c970ec4e07e0c6fc2ff3658cf388f;hb=b116e9366c7b2ea2c2eb53b0a13df4090e176235;hpb=fd48f3e498442f0cbff5f3606c7c403d0566150e

diff --git a/perl/Amanda/Xfer.pod b/perl/Amanda/Xfer.pod
index 772474b..d09923c 100644
--- a/perl/Amanda/Xfer.pod
+++ b/perl/Amanda/Xfer.pod
@@ -136,7 +136,7 @@ the file for you!
 
 This source reads data from a holding file (see L<Amanda::Holding>).
 If the transfer only consists of a C<Amanda::Xfer::Source::Holding>
-and an C<Amanda::Xfer::Dest::Taper::Splitter> (with no filters), then the source
+and an C<Amanda::Xfer::Dest::Taper::Cacher> (with no filters), then the source
 will call the destination's C<cache_inform> method so that it can use
 holding chunks for a split-part cache.
 
@@ -206,11 +206,12 @@ be called before the C<start_part> method is called with a new device.
   Amanda::Xfer::Source::DirectTCPListen->new();
 
 This source is for use when the transfer data will come in via DirectTCP, with
-the data's I<source> connecting to the data's I<destination>.  Set up the
-transfer, and after starting it, call its C<get_addrs> method to get an
-arrayref of ip/port pairs, e.g., C<[ "192.168.4.5", 9924 ]>, all of which are
-listening for an incoming data connection.  Once a connection arrives, this
-element will read data from it and send those data into the transfer.
+the data's I<source> connecting to the data's I<destination>.  That is, the
+data source is the connection initiator.  Set up the transfer, and after
+starting it, call this element's C<get_addrs> method to get an arrayref of ip/port pairs,
+e.g., C<[ "192.168.4.5", 9924 ]>, all of which are listening for an incoming
+data connection.  Once a connection arrives, this element will read data from
+it and send those data into the transfer.
 
   my $addrs = $src->get_addrs();
 
@@ -219,21 +220,23 @@ element will read data from it and send those data into the transfer.
   Amanda::Xfer::Source::DirectTCPConnect->new($addrs);
 
 This source is for use when the transfer data will come in via DirectTCP, with
-the data's I<destination> connecting to the the data's I<source>.  The element
-connects to C<$addrs> and reads the transfer data from the connection.
+the data's I<destination> connecting to the the data's I<source>.  That is, the
+data destination is the connection initiator.  The element connects to
+C<$addrs> and reads the transfer data from the connection.
 
 =head2 Transfer Filters
 
 =head3 Amanda::Xfer::Filter:Process
 
-  Amanda::Xfer::Filter::Process->new([@args], $need_root);
+  Amanda::Xfer::Filter::Process->new([@args], $need_root, $log_stderr);
 
 This filter will pipe data through the standard file descriptors of the
 subprocess specified by C<@args>.  If C<$need_root> is true, it will attempt to
 change to uid 0 before executing the process.  Standard output from the process
 is redirected to the debug log.  Note that the process is invoked directly, not
 via a shell, so shell metacharcters (e.g., C<< 2>&1 >>) will not function as
-expected.
+expected.  If C<$log_stderr> is set, then the filter's standard error is sent
+to the debug log; otherwise, it is sent to the parent process's stderr.
 
 =head3 Amanda::Xfer::Filter:Xor
 
@@ -246,12 +249,14 @@ through it.
 
 =head3 Amanda::Xfer::Dest::Device (SERVER ONLY)
 
-  Amanda::Xfer::Dest::Device->new($device, $max_memory);
+  Amanda::Xfer::Dest::Device->new($device, $cancel_at_eom);
 
-This source writes data to a device.  The device should be ready for
-writing (C<< $device->start_file(..) >>).  No more than C<$max_memory>
-will be used for buffers.  Use zero for the default buffer size.  On
-completion of the transfer, the file will be finished.
+This source writes data to a device.  The device should be ready for writing
+(C<< $device->start_file(..) >>).  On completion of the transfer, the file will
+be finished.  If an error occurs, or if C<$cancel_at_eom> is true and the
+device signals LEOM, the transfer will be cancelled.
+
+Note that this element does not apply any sort of stream buffering.
 
 =head3 Amanda::Xfer::Dest::Buffer
 
@@ -268,11 +273,12 @@ returns a copy of the buffer as a perl scalar:
   Amanda::Xfer::Dest::DirectTCPListen->new();
 
 This destination is for use when the transfer data will come in via DirectTCP,
-with the data's I<destination> connecting to the data's I<source>.  Set up the
-transfer, and after starting it, call this element's C<get_addrs> method to get
-an arrayref of ip/port pairs, e.g., C<[ "192.168.4.5", 9924 ]>, all of which
-are listening for an incoming data connection.  Once a connection arrives, this
-element will write the transfer data to it.
+with the data's I<destination> connecting to the data's I<source>.  That is,
+the data destination is the connection initiator.  Set up the transfer, and
+after starting it, call this element's C<get_addrs> method to get an arrayref
+of ip/port pairs, e.g., C<[ "192.168.4.5", 9924 ]>, all of which are listening
+for an incoming data connection.  Once a connection arrives, this element will
+write the transfer data to it.
 
   my $addrs = $src->get_addrs();
 
@@ -281,8 +287,9 @@ element will write the transfer data to it.
   Amanda::Xfer::Dest::DirectTCPConnect->new($addrs);
 
 This destination is for use when the transfer data will come in via DirectTCP,
-with the data's I<source> connecting to the the data's I<destination>.  The
-element connects to C<$addrs> and writes the transfer data to the connection.
+with the data's I<source> connecting to the the data's I<destination>.  That
+is, the data source is the connection initiator.  The element connects to
+C<$addrs> and writes the transfer data to the connection.
 
 =head3 Amanda::Xfer::Dest::Fd
 
@@ -303,7 +310,7 @@ validation is performed if C<$seed> is zero.
 
 =head3 Amanda::Xfer::Dest::Taper (SERVER ONLY)
 
-This is the parent class to C<Amanda::Xfer::Dest::Taper::Splitter> and
+This is the parent class to C<Amanda::Xfer::Dest::Taper::Cacher> and
 C<Amanda::Xfer::Dest::Taper::DirectTCP>. These subclasses allow a single
 transfer to write to multiple files (parts) on a device, and even spread those
 parts over multiple devices, without interrupting the transfer itself.
@@ -372,25 +379,40 @@ to the device.
 =head3 Amanda::Xfer::Dest::Taper::Splitter
 
   Amanda::Xfer::Dest::Taper::Splitter->new($first_device, $max_memory,
+                        $part_size, $expect_cache_inform);
+
+This class splits a data stream into parts on the storage media.  It is for use
+when the device supports LEOM, when the dump is already available on disk
+(C<cache_inform>), or when no caching is desired.  It does not cache parts, so
+it can only retry a partial part if the transfer source is calling
+C<cache_inform>.  If the element is used with devices that do not support LEOM,
+then it will cancel the entire transfer if the device reaches EOM and
+C<cache_inform> is not in use.  Set C<$expect_cache_inform> appropriately based
+on the incoming data.
+
+The C<$part_size> and C<$first_device> parameters are described above for
+C<Amanda::Xfer::Dest::Taper>.
+
+=head3 Amanda::Xfer::Dest::Taper::Cacher
+
+  Amanda::Xfer::Dest::Taper::Cacher->new($first_device, $max_memory,
                         $part_size, $use_mem_cache, $disk_cache_dirname);
 
-This class caches data from each part in one of a variety of ways, and supports
-"rewinding" to retry a failed part (e.g., one that does not fit on a device).
-It assumes that when a device reaches EOM while writing, the entire file is
-corrupt.  It does not (yet) support logical EOM, which can render this
-assumption incorrect.
+This class is similar to the splitter, but caches data from each part in one of
+a variety of ways to support "rewinding" to retry a failed part (e.g., one that
+does not fit on a device).  It assumes that when a device reaches EOM while
+writing, the entire on-volume file is corrupt - that is, that the device does
+not support logical EOM.  The class does not support C<cache_inform>.
 
-The C<$first_device> is used to calculate some internal constants, notably the
-slab size, based on the device characteristics.   Subsequent devices must have
-the same block size.  The C<$part_size> and C<$first_device> parameters are
-described above.
+The C<$part_size> and C<$first_device> parameters are described above for
+C<Amanda::Xfer::Dest::Taper>.
 
 If C<$use_mem_cache> is true, each part will be cached in memory (using
 C<$part_size> bytes of memory; plan accordingly!).  If C<$disk_cache_dirname>
 is defined, then each part will be cached on-disk in a file in this directory.
 It is an error to specify both in-memory and on-disk caching.  If neither
 option is specified, the element will operate successfully, but will not be
-able to retry a part unless C<cache_inform> has been used properly (see above).
+able to retry a part, and will cancel the transfer if a part fails.
 
 =head3 Amanda::Xfer::Dest::Taper::DirectTCP