OpenBSD::Ustar man page on OpenBSD

Man page or keyword search:  
man Server   11362 pages
apropos Keyword Search (all sections)
Output format
OpenBSD logo
[printable version]

OpenBSD::Ustar(3p)     Perl Programmers Reference Guide	    OpenBSD::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, $state, $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, $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;

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

       Error messages and fatal errors will be handled through the $state
       object, which should conform to "OpenBSD::State(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.

       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.

       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.12.2						       January 2, 2011
[top]

List of man pages available for OpenBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net