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<write_block> 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
This function ensures that C<block> 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<Amanda::Xfer>).
-
-This is a virtual method, but the default implementation in the Device class
-uses C<write_block>, so there is no need for subclasses to override it.
-
=head3 finish_file
$success = $dev->finish_file();
after an EOF, so there is no need to check C<is_eof> except when C<read_block>
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<Amanda::Xfer>).
-
-This is a virtual method, but the default implementation in the Device class
-uses C<read_block>, so there is no need for subclasses to override it.
-
=head3 finish
$success = $dev->finish();
connection object, so the caller should call C<g_object_unref> 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<undef> 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<g_object_unref> when the connection is no longer needed.
+
=head3 use_connection
my $ok = $dev->use_connection($conn);
Call this method to use a DirectTCPConnection object created with another
device. The method must be called before the device is started (so
C<access_mode> is C<$ACCESS_NULL>), as some devices cannot support switching
-connections without rewinding. Any subsequent C<read_from_connection> or
-C<write_to_connection> calls will use this connection.
+connections without rewinding. Any subsequent C<read_to_connection> or
+C<write_from_connection> 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<use_connection> or returned from C<accept> 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<use_connection> or returned from C<accept> or C<connect> 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
=head2 DirectTCPConnection objects
-The C<accept> method returns an object to represent the ongoing DirectTCP
-connection. This object is mostly useful as a "token" to be passed to
-C<write_from_connection> and C<read_to_connection>. In particular, a
+The C<accept> and C<connect> methods return an object to represent the ongoing
+DirectTCP connection. This object is mostly useful as a "token" to be passed
+to C<write_from_connection> and C<read_to_connection>. In particular, a
connection created by one device can be used with another device; this is how
DirectTCP dumps are spanned over multiple volumes.
projects / debian / amanda / blobdiff