OpenBSD::Ustar(3p) Perl Programmers Reference Guide OpenBSD::Ustar(3p)

OpenBSD::Ustar(3p) Perl Programmers Reference Guide OpenBSD::Ustar(3p) #

OpenBSD::Ustar(3p) Perl Programmers Reference Guide OpenBSD::Ustar(3p)

NNAAMMEE #

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

SSYYNNOOPPSSIISS #

     use OpenBSD::Ustar;
     # for reading

     open(my $in, "<", $arcnameforreading) or die;
     $rdarc = OpenBSD::Ustar->new($in, $state, $destdir);
     $rdarc->set_description($arcnameforreading);
     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, $state, $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, $state, $destdir);
     open(my $out, ">", $arcnameforwriting) or die;
     $wrarc = OpenBSD::Ustar->new($fh, $state, $destdir);
     while (my $o = $rdarc->next) {
         $o->copy($wrarc);
     }
     $rdarc->close;
     $wrarc->close;

DDEESSCCRRIIPPTTIIOONN #

 "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, but is
 supports the "XHDR" (x blocktype) extension for accurately representing
 long hard links and symbolic links.  It also accurately recognize some
 common extensions that it doesn't process.

 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".

 Error messages and fatal errors will be handled through the $state
 object, which should conform to "OpenBSD::BaseState(3p)" (uses "errsay"
 and "fatal").

 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 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.

 "prepare" takes an optional $destdir parameter that will override the
 archive destdination directory.  This can be used to prepare an archive
 entry from a temporary file, that will be used for the real checks and
 contents of the archive, then set the name to save before writing the
 actual entry:

     $o = $wrarc->prepare($tempfile, '');
     $o->set_name("othername");
     $o->write;

 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.

 In case of errors, the archive will call "$state->fatal" with a suitable
 error message that contains the last index name processed. The user may
 set an optional archive description with "set_description".

 The archive object can take a description through "$arc->set_description"
 which will be used in error messages related to archive extraction or
 creation.

 The archive object can be embued with a $callback through
 "$arch->set_callback", which will be called regularly while extracting
 large objects, as "&$callback($donesize)", with $donesize the number of
 bytes already extracted, for use in progressmeter-style user
 interactions.

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

 Actual file objects can also be directly extracted to a temporary file
 using "$o>extract_to_fh($fh)".

 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.

 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->{atime}"       utime(2) access time

 "$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", "atime", "mtime", "uid", "gid" and "linkname"
 can be altered before calling "$o->create" or "$o->write", and will
 properly influence the resulting file.  "atime" and "mtime" can be undef
 to set those to the current time.

 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 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.36.3 2023-05-16 OpenBSD::Ustar(3p)