X-Git-Url: https://git.gag.com/?p=debian%2Famanda;a=blobdiff_plain;f=perl%2FAmanda%2FDevice.pod;h=10d3f8b6540f0313d724f119636dd0513497331d;hp=48ce6134e94da5fff4197c12b68f32d6ff216a93;hb=b116e9366c7b2ea2c2eb53b0a13df4090e176235;hpb=fd48f3e498442f0cbff5f3606c7c403d0566150e diff --git a/perl/Amanda/Device.pod b/perl/Amanda/Device.pod index 48ce613..10d3f8b 100644 --- a/perl/Amanda/Device.pod +++ b/perl/Amanda/Device.pod @@ -260,10 +260,12 @@ C, C, C, and C. API users that understand LEOM should take this as a signal to complete writing to the device and move on before hitting PEOM. -Devices which do not support EOM simply return a VOLUME_ERROR when the volume +Devices which do not support LEOM simply return a VOLUME_ERROR when the volume is full. If this occurs during a C operation, then the volume may or may not contain the block - the situation is indeterminate. +Devices indicate their support for LEOM with the LEOM property. + =head2 Device Resources Some device types have a "locking" mechanism that prevents other parts of the @@ -474,23 +476,6 @@ set C whenever the situation is ambiguous. This function ensures that C is correct on exit. Even in an error condition, it does not finish the current file for the caller. -=head3 write_from_fd (DEPRECATED) - - my $qfd = Amanda::Device::queue_fd_t->new(fileno($fh)); - if (!$dev->write_from_fd($fd)) { - print STDERR $qfd->{errmsg}, "\n" if ($qfd->{errmsg}); - print STDERR $dev->status_or_error(), "\n" if ($dev->status()); - } - -This method reads from the given file descriptor until EOF, writing the data to -a Device file which should already be started, and not returning until the -operation is complete. The file is not automatically finished. This method is -deprecated; the better solution is to use the transfer architecture -(L). - -This is a virtual method, but the default implementation in the Device class -uses C, so there is no need for subclasses to override it. - =head3 finish_file $success = $dev->finish_file(); @@ -559,23 +544,6 @@ wait for the next read to fail. It is never an error to call C after an EOF, so there is no need to check C except when C returns -1. -=head3 read_to_fd (DEPRECATED) - - queue_fd_t *qfd = queue_fd_new(fd, NULL); - my $qfd = Amanda::Device::queue_fd_t->new(fileno($fh)); - if (!$dev->read_to_fd($fd)) { - print STDERR $qfd->{errmsg}, "\n" if ($qfd->{errmsg}); - print STDERR $dev->status_or_error(), "\n" if ($dev->status()); - } - -This method reads the current file from the device and writes to the given file -descriptor, not returning until the operation is complete. This method is -deprecated; new uses of devices use the transfer architecture -(L). - -This is a virtual method, but the default implementation in the Device class -uses C, so there is no need for subclasses to override it. - =head3 finish $success = $dev->finish(); @@ -652,6 +620,18 @@ connection ever occurs. The C implementation returns an already-referenced connection object, so the caller should call C when the connection is no longer needed. +=head3 connect + + $conn = $dev->connect($for_writing, $addrs); + +This method initiates a connection to one of the addresses in C<$addrs>, +returning an established DirectTCPConnection object (see below). The +C<$for_writing> parameter is TRUE if the connection will be used to write to +the device. It returns C on failure. Note that this method may block +indefinitely if no connection ever occurs. The C implementation returns an +already-referenced connection object, so the caller should call +C when the connection is no longer needed. + =head3 use_connection my $ok = $dev->use_connection($conn); @@ -659,17 +639,18 @@ connection is no longer needed. Call this method to use a DirectTCPConnection object created with another device. The method must be called before the device is started (so C is C<$ACCESS_NULL>), as some devices cannot support switching -connections without rewinding. Any subsequent C or -C calls will use this connection. +connections without rewinding. Any subsequent C or +C calls will use this connection. =head3 write_from_connection ($ok, $actual_size) = $dev->write_from_connection($size); This method reads data from the DirectTCPConnection specified with -C or returned from C and writes it to the volume. It -writes at most C<$size> bytes, and returns the number of bytes written in -C<$actual_size>. On error, C<$ok> is false. +C or returned from C or C and writes it to the +volume. It writes at most C<$size> bytes, and returns the number of bytes +written in C<$actual_size>. If C<$size> is zero, it will write until EOF, EOM, +or a device error. On error, C<$ok> is false. When an EOF is received over the connection, signalling the end of the data stream, then this method returns without error (C<$ok> is true), with @@ -712,9 +693,9 @@ or imported with the C<:constant> import tag. =head2 DirectTCPConnection objects -The C method returns an object to represent the ongoing DirectTCP -connection. This object is mostly useful as a "token" to be passed to -C and C. In particular, a +The C and C methods return an object to represent the ongoing +DirectTCP connection. This object is mostly useful as a "token" to be passed +to C and C. In particular, a connection created by one device can be used with another device; this is how DirectTCP dumps are spanned over multiple volumes.