.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "OpenBSD::Ustar 3p"
.TH OpenBSD::Ustar 3p "2008-05-30" "perl v5.8.8" "Perl Programmers Reference Guide"
.SH "NAME"
OpenBSD::Ustar \- simple access to Ustar \f(CWtar(1)\fR archives
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use OpenBSD::Ustar;
\&    # for reading
.Ve
.PP
.Vb 7
\&    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();
.Ve
.PP
.Vb 7
\&    # 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();
.Ve
.PP
.Vb 1
\&    $wrarc->close();
.Ve
.PP
.Vb 10
\&    # 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();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`OpenBSD::Ustar\*(C'\fR provides an \s-1API\s0 to read, write and copy archives compatible 
with \f(CWtar(1)\fR.
For the time being, it can only handle the \s-1USTAR\s0 archive format.
.PP
A filehandle \f(CW$fh\fR is associated with an \f(CW\*(C`OpenBSD::Ustar\*(C'\fR object through
\&\f(CW\*(C`new\*(C'\fR. For archive reading, the filehandle should support 
\&\f(CW\*(C`read\*(C'\fR. \f(CW\*(C`OpenBSD::Ustar\*(C'\fR does not rely on \f(CW\*(C`seek\*(C'\fR or \f(CW\*(C`rewind\*(C'\fR in order 
to be usable on pipe outputs. For archive writing, the filehandle should 
support \f(CW\*(C`print\*(C'\fR.
.PP
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.
.PP
Read access to an archive object \f(CW$rdarc\fR occurs through a loop that 
repeatedly calls \f(CW\*(C`$o = $rdarc\->next()\*(C'\fR to obtain the next archive entry.  
It returns an archive entry object \f(CW$o\fR that can be 
queried to decide whether to extract this entry or not.
.PP
Write access to an archive object \f(CW$wrarc\fR occurs through a user-directed
loop: obtain an archive entry through \f(CW\*(C`$o = $wrarc\->prepare($filename)\*(C'\fR,
which can be tweaked manually and then written to the archive.
.PP
Most client software will specialize \f(CW\*(C`OpenBSD::Ustar\*(C'\fR to their own needs.
Note however that \f(CW\*(C`OpenBSD::Ustar\*(C'\fR is not designed for inheritance.
Composition (putting a \f(CW\*(C`OpenBSD::Ustar\*(C'\fR object inside your class) and
forwarding methods (writing \f(CW\*(C`create\*(C'\fR or \f(CW\*(C`next\*(C'\fR methods that call the
corresponding \f(CW\*(C`OpenBSD::Ustar\*(C'\fR method) are the correct way to use this \s-1API\s0.
.PP
Note that \f(CW\*(C`OpenBSD::Ustar\*(C'\fR 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.
.PP
Actual extraction is performed through \f(CW\*(C`$o\->extract()\*(C'\fR and is not 
mandatory. Thus, client code can control whether it wants to extract archive
elements or not.
.PP
Small files can also be directly extracted to a scalar using 
\&\f(CW\*(C`$v = $o\->contents()\*(C'\fR.
.PP
Actual writing is performed through \f(CW\*(C`$o\->write()\*(C'\fR and is not mandatory
either.
.PP
Archives should be closed using \f(CW\*(C`$wrarc\->close()\*(C'\fR, 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.
.PP
This is equivalent to calling \f(CW\*(C`$wrarc\->pad()\*(C'\fR, which will
complete the archive with blank-filled blocks, then closing the
associated file handle manually.
.PP
Client code may decide to abort archive extraction early, or to run it through
until \f(CW\*(C`$arc\->next()\*(C'\fR returns false.  The \f(CW\*(C`OpenBSD::Ustar\*(C'\fR object doesn't
hold any hidden resources and doesn't need any specific clean\-up.
.PP
Client code is only responsible for closing the underlying filehandle and 
terminating any associated pipe process.
.PP
An object \f(CW$o\fR returned through \f(CW\*(C`next\*(C'\fR or through \f(CW\*(C`prepare\*(C'\fR holds all 
the characteristics of the archive header:
.ie n .IP """$o\->IsDir()""" 20
.el .IP "\f(CW$o\->IsDir()\fR" 20
.IX Item "$o->IsDir()"
true if archive entry is a directory
.ie n .IP """$o\->IsFile()""" 20
.el .IP "\f(CW$o\->IsFile()\fR" 20
.IX Item "$o->IsFile()"
true if archive entry is a file
.ie n .IP """$o\->IsLink()""" 20
.el .IP "\f(CW$o\->IsLink()\fR" 20
.IX Item "$o->IsLink()"
true if archive entry is any kind of link
.ie n .IP """$o\->IsSymLink()""" 20
.el .IP "\f(CW$o\->IsSymLink()\fR" 20
.IX Item "$o->IsSymLink()"
true if archive entry is a symbolic link
.ie n .IP """$o\->IsHardLink()""" 20
.el .IP "\f(CW$o\->IsHardLink()\fR" 20
.IX Item "$o->IsHardLink()"
true if archive entry is a hard link
.ie n .IP """$o\->{name}""" 20
.el .IP "\f(CW$o\->{name}\fR" 20
.IX Item "$o->{name}"
filename
.ie n .IP """$o\->{mode}""" 20
.el .IP "\f(CW$o\->{mode}\fR" 20
.IX Item "$o->{mode}"
\&\f(CWchmod(2)\fR mode
.ie n .IP """$o\->{mtime}""" 20
.el .IP "\f(CW$o\->{mtime}\fR" 20
.IX Item "$o->{mtime}"
\&\f(CWutime(2)\fR modification time
.ie n .IP """$o\->{uid}""" 20
.el .IP "\f(CW$o\->{uid}\fR" 20
.IX Item "$o->{uid}"
owner user \s-1ID\s0
.ie n .IP """$o\->{gid}""" 20
.el .IP "\f(CW$o\->{gid}\fR" 20
.IX Item "$o->{gid}"
owner group \s-1ID\s0
.ie n .IP """$o\->{uname}""" 20
.el .IP "\f(CW$o\->{uname}\fR" 20
.IX Item "$o->{uname}"
owner user name
.ie n .IP """$o\->{gname}""" 20
.el .IP "\f(CW$o\->{gname}\fR" 20
.IX Item "$o->{gname}"
owner group name
.ie n .IP """$o\->{linkname}""" 20
.el .IP "\f(CW$o\->{linkname}\fR" 20
.IX Item "$o->{linkname}"
name of the source link, if applicable
.PP
The fields \f(CW\*(C`name\*(C'\fR, \f(CW\*(C`mode\*(C'\fR, \f(CW\*(C`mtime\*(C'\fR, \f(CW\*(C`uid\*(C'\fR, \f(CW\*(C`gid\*(C'\fR and \f(CW\*(C`linkname\*(C'\fR
can be altered before calling \f(CW\*(C`$o\->create()\*(C'\fR or \f(CW\*(C`$o\->write()\*(C'\fR, 
and will properly influence the resulting file.
.PP
The relationship between \f(CW\*(C`uid\*(C'\fR and \f(CW\*(C`uname\*(C'\fR, and \f(CW\*(C`gid\*(C'\fR and \f(CW\*(C`gname\*(C'\fR
conforms to the \s-1USTAR\s0 format usual behavior.
.PP
In addition, client code may define \f(CW\*(C`$o\->{cwd}\*(C'\fR in a way similar
to \f(CWtar(1)\fR's \f(CW\*(C`\-C\*(C'\fR option to affect the creation of hard links.
.PP
All creation commands happen relative to the current destdir of 
the \f(CW$arc\fR \f(CW\*(C`OpenBSD::Ustar\*(C'\fR object.  This is set at creation, and can
later be changed through \f(CW\*(C`$arc\->destdir($value)\*(C'\fR.
.PP
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.
.PP
Hard links can not be copied from one archive to another unless the original
file has also been copied.  Calling \f(CW\*(C`$o\->alias($arc, $name)\*(C'\fR will trick
the destination archive \f(CW$arc\fR into believing \f(CW$o\fR has been copied under the
given \f(CW$name\fR, so that further hard links will be copied over.
.PP
Archives can be copied by creating separate archives for reading and writing.
Calling \f(CW\*(C`$o = $rdarc\->next()\*(C'\fR and \f(CW\*(C`$o\->copy($wrarc)\*(C'\fR will copy
an entry obtained from \f(CW$rdarc\fR to \f(CW$wrarc\fR.