


OpenBSD::Ustar(3pPerl Programmers Reference GuiOpenBSD::Ustar(3p)


NAME
       OpenBSD::Ustar - simple access to Ustar tar(1) archives

SYNOPSIS
           use OpenBSD::Ustar;
           # for reading

           open(my $in, "<", $arcnameforreading) or die;
           $rdarc = OpenBSD::Ustar->new($in, $destdir);
           while (my $o = $rdarc->next) {
               # decide whether we want to extract it, change object attributes
               $o->create;
           }
           $rdarc->close;

           # for writing
           open(my $out, ">", $arcnameforwriting) or die;
           $wrarc = OpenBSD::Ustar->new($fh, $destdir);
           # loop
               my $o = $wrarc->prepare($filename);
               # tweak some entry parameters
               $o->write;

           $wrarc->close;

           # for copying
           open(my $in, "<", $arcnameforreading) or die;
           $rdarc = OpenBSD::Ustar->new($in, $destdir);
           open(my $out, ">", $arcnameforwriting) or die;
           $wrarc = OpenBSD::Ustar->new($fh, $destdir);
           while (my $o = $rdarc->next) {
               $o->copy($wrarc);
           }
           $rdarc->close;
           $wrarc->close;

DESCRIPTION
       "OpenBSD::Ustar" provides an API to read, write and copy
       archives compatible with tar(1).  For the time being, it
       can only handle the USTAR archive format.

       A filehandle $fh is associated with an "OpenBSD::Ustar"
       object through "new". For archive reading, the filehandle
       should support "read". "OpenBSD::Ustar" does not rely on
       "seek" or "rewind" in order to be usable on pipe outputs.
       For archive writing, the filehandle should support
       "print".

       Note that read and write support are mutually exclusive,
       though there is no need to specify the mode used at
       creation time; it is implicitly provided by the underlying
       filehandle.

       Read access to an archive object $rdarc occurs through a



perl v5.10.1                2009-12-17                          1





OpenBSD::Ustar(3pPerl Programmers Reference GuiOpenBSD::Ustar(3p)


       loop that repeatedly calls "$o = $rdarc->next" to obtain
       the next archive entry.  It returns an archive entry
       object $o that can be queried to decide whether to extract
       this entry or not.

       Write access to an archive object $wrarc occurs through a
       user-directed loop: obtain an archive entry through "$o =
       $wrarc->prepare($filename)", which can be tweaked manually
       and then written to the archive.

       Most client software will specialize "OpenBSD::Ustar" to
       their own needs.  Note however that "OpenBSD::Ustar" is
       not designed for inheritance.  Composition (putting a
       "OpenBSD::Ustar" object inside your class) and forwarding
       methods (writing "create" or "next" methods that call the
       corresponding "OpenBSD::Ustar" method) are the correct way
       to use this API.

       Note that "OpenBSD::Ustar" does not do any caching. The
       client code is responsible for retrieving and storing
       archives if it needs to scan through them multiple times
       in a row.

       Actual extraction is performed through "$o->create" and is
       not mandatory. Thus, client code can control whether it
       wants to extract archive elements or not.

       The "create" method can take an optional $callback
       argument, which will be called regularly while extracting
       large objects, as "&$callback($donesize)", with $donesize
       the number of bytes already extracted.

       Small files can also be directly extracted to a scalar
       using "$v = $o->contents".

       Actual writing is performed through "$o->write" and is not
       mandatory either.

       Archives should be closed using "$wrarc->close", which
       will pad the archive as needed and close the underlying
       file handle.  In particular, this is mandatory for write
       access, since valid archives require blank-filled blocks.

       This is equivalent to calling "$wrarc->pad", which will
       complete the archive with blank-filled blocks, then
       closing the associated file handle manually.

       Client code may decide to abort archive extraction early,
       or to run it through until "$arc->next" returns false.
       The "OpenBSD::Ustar" object doesn't hold any hidden
       resources and doesn't need any specific clean-up.

       Client code is only responsible for closing the underlying
       filehandle and terminating any associated pipe process.



perl v5.10.1                2009-12-17                          2





OpenBSD::Ustar(3pPerl Programmers Reference GuiOpenBSD::Ustar(3p)


       An object $o returned through "next" or through "prepare"
       holds all the characteristics of the archive header:

       "$o->IsDir"         true if archive entry is a directory

       "$o->IsFile"        true if archive entry is a file

       "$o->IsLink"        true if archive entry is any kind of
                           link

       "$o->IsSymLink"     true if archive entry is a symbolic
                           link

       "$o->IsHardLink"    true if archive entry is a hard link

       "$o->{name}"        filename

       "$o->{mode}"        chmod(2) mode

       "$o->{mtime}"       utime(2) modification time

       "$o->{uid}"         owner user ID

       "$o->{gid}"         owner group ID

       "$o->{uname}"       owner user name

       "$o->{gname}"       owner group name

       "$o->{linkname}"    name of the source link, if applicable

       The fields "name", "mode", "mtime", "uid", "gid" and
       "linkname" can be altered before calling "$o->create" or
       "$o->write", and will properly influence the resulting
       file.

       The relationship between "uid" and "uname", and "gid" and
       "gname" conforms to the USTAR format usual behavior.

       In addition, client code may define "$o->{cwd}" in a way
       similar to tar(1)'s "-C" option to affect the creation of
       hard links.

       All creation commands happen relative to the current
       destdir of the $arc "OpenBSD::Ustar" object.  This is set
       at creation, and can later be changed through
       "$arc->destdir($value)".

       During writing, hard link status is determined according
       to already written archive entries: a name that references
       a file which has already been written will be granted hard
       link status.

       Hard links can not be copied from one archive to another



perl v5.10.1                2009-12-17                          3





OpenBSD::Ustar(3pPerl Programmers Reference GuiOpenBSD::Ustar(3p)


       unless the original file has also been copied.  Calling
       "$o->alias($arc, $name)" will trick the destination
       archive $arc into believing $o has been copied under the
       given $name, so that further hard links will be copied
       over.

       Archives can be copied by creating separate archives for
       reading and writing.  Calling "$o = $rdarc->next" and
       "$o->copy($wrarc)" will copy an entry obtained from $rdarc
       to $wrarc.















































perl v5.10.1                2009-12-17                          4


