4.0.0alpha.svn.7719
Amanda modules list
List of All Modules
All Amanda Releases

Amanda::Archive

NAME

Amanda::Archive - Perl access to the amanda archive library

SYNOPSIS

  use Amanda::Archive

  # Write to the file descriptor or file handle $fd, and
  # add /etc/hosts to it
  my $archive = Amanda::Archive->new($fd, ">");
  my $file = $archive->new_file("/etc/hosts");
  my $attr = $file->new_attr(16);
  open(my $fh, "<", "/etc/hosts");
  $attr->add_data_fd($fh, 1);
  $file->close();
  $archive->close();

  # Read from an archive
  my $archive = Amanda::Archive->new($fd, "<");
  $ar->read(
      file_start => sub {
          my ($user_data, $filenum, $filename) = @_;
          # ...
          return "foo"; # this becomes $file_data
      },
      file_finish => sub {
          my ($user_data, $file_data, $filenum, $truncated) = @_;
          # ...
      },
      21 => [ 32768,    # buffer into 32k chunks
              sub {
                  my ($user_data, $filenum, $file_data, $attrid,
                      $attr_data, $data, $eoa, $truncated) = @_;
                  return "pants"; # becomes the new $attr_data for
                                  # any subsequent fragments
              } ],
      0 => sub {        # note no buffering here; attrid 0 is "default"
          my ($user_data, $filenum, $file_data, $attrid,
              $attr_data, $data, $eoa, $truncated) = @_;
          return "shorts"; # becomes the new $attr_data for
                           # any subsequent fragments
      },
      user_data => [ "mydata" ], # sent to all callbacks
  );

WRITING

Amanda::Archive::Archive Objects

Note that Amanda::Archive->new and Amanda::Archive::Archive->new are equivalent.

new($fd, $mode)

Create a new archive for reading ("<") or writing (">") from or to file $fd (a file handle or integer file descriptor).

size()

Return the number of bytes already written to the archive.

new_file($filename, $want_posn)

Create a new Amanda::Archive::File object with the given filename (writing only). Equivalent to

  Amanda::Archive::File->new($archive, $filename, $want_posn);

if $want_posn is false, then this method returns a new Amanda::Archive::File object. If $want_posn is true, then it returns ($file, $posn) where $file is the object and $posn is the offset into the datastream at which this file begins. This offset can be stored in an index and used later to seek into the file.

read(..)

See READING, below.

close()

Flush all buffers and close this archive. This does not close the file descriptor.

Amanda::Archive::File Objects

new($archive, $filename, $want_posn)

Create a new file in the given archive. See Amanda::Archive::Archive::new_file, above.

new_attr($attrid)

Create a new Amanda::Archive::Attribute object. Equivalent to

  Amanda::Archive::Attr->new($file, $attrid);
size()

Return the size on the archive of all attributes of the file.

close()

Close this file, writing an EOF record.

Amanda::Archive::Attribute Objects

add_data($data, $eoa)

Add $data to this attribute, adding an EOA (end-of-attribute) bit if $eoa is true.

add_data_fd($fh, $eoa)

Copy data from $fh to this attribute, adding an EOA (end-of-attribute) bit if $eoa is true.

add_data_fd_in_thread($fh, $eoa)

Same as add_data_fd but the copy is done in a newly created thread. This function return immediately. Nothing should be done on the archive while it is running. The next action on the archive must be $attr->close().

size()

Return the size of the data of the attribute.

close()

Close this attribute, adding an EOA bit if none has been written already.

READING

The Amanda::Archive::Archive method read() handles reading archives via a callback mechanism. It takes its arguments in hash form, with the following keys:

    file_start => sub {
        my ($user_data, $filenum, $filename) = @_;
        # ..
    },

file_start gives a sub which is called for every file in the archive. It can return an arbitrary value which will become the $file_data for subsequent callbacks in this file, or the string "IGNORE" which will cause the reader to ignore all data for this file. In this case, no other callbacks will be made for the file (not even file_finish).

    file_finish => sub {
        my ($user_data, $file_data, $filenum, $truncated) = @_;
        # ..
    },

file_finish gives a sub which is called when an EOF record appears. $file_data comes from the return value of the file_start callback. $truncated is true if the file may be missing data (e.g., when an early EOF is detected).

    user_data => $my_object,

user_data gives an arbitrary value which is passed to each callback as $user_data.

    13 => sub {
        my ($user_data, $filenum, $file_data, $attrid,
            $attr_data, $data, $eoa, $truncated) = @_;
        # ...
    },
    19 => [ 10240, sub { ... } ],

Any numeric key is treated as an attribute ID, and specifies the handling for that attribute. Attribute ID zero is treated as a wildcard, and will match any attribute without an explicit handler. The handler can be specified as a sub (as for attribute ID 13 in the example above) or as an arrayref [$minsize, $sub]. In the latter case, the sub is only called when at least $minsize bytes of data are available for the attribute, or at the end of the attribute data.

The parameters to the callback include $file_data, the value returned from file_start, and $attr_data, which is the return value of the last invocation of this sub for this attribute. If this is the last fragment of data for this attribute, then $eoa is true. The meaning of $truncated is similar to that in file_finish.

EXAMPLE

    sub read_to_files {
        my ($arch_fh, $basedir) = @_;

        my $arch = Amanda::Archive->new(fileno($arch_fh), "<");
        $arch->read(
            file_start => sub {
                my ($user_data, $filenum, $filename) = @_;
                return "$basedir/$filenum"; # becomes $file_data
            },
            0 => [ 32768, sub {
                my ($user_data, $filenum, $file_data, $attrid,
                    $attr_data, $data, $eoa, $truncated) = @_;
                warn("file $filename attribute $attrid is truncated")
                    if ($truncated);
                # store the open filehandle in $attr_data
                if (!$attr_data) {
                    open($attr_data, "$file_data.$attrid", ">")
                        or die("open: $!");
                }
                print $attr_data $data;
                if ($eoa) {
                    close($attr_data);
                }
                return $attr_data;
            },
        );
    }

Amar default attribute: $AMAR_ATTR_FILENAME $AMAR_ATTR_EOF $AMAR_ATTR_GENERIC_DATA $AMAR_ATTR_RMAN_DATA

ABOUT THIS PAGE

This page was automatically generated Tue Mar 19 07:08:15 2019 from the Amanda source tree, and documents the most recent development version of Amanda. For documentation specific to the version of Amanda on your system, use the 'perldoc' command.


4.0.0alpha.svn.7719