diff options
| -rw-r--r-- | usr.sbin/pkg_add/pod/OpenBSD::Ustar.pod | 69 |
1 files changed, 47 insertions, 22 deletions
diff --git a/usr.sbin/pkg_add/pod/OpenBSD::Ustar.pod b/usr.sbin/pkg_add/pod/OpenBSD::Ustar.pod index c7be9ee9b9e..a83d01121f2 100644 --- a/usr.sbin/pkg_add/pod/OpenBSD::Ustar.pod +++ b/usr.sbin/pkg_add/pod/OpenBSD::Ustar.pod @@ -1,4 +1,4 @@ -$OpenBSD: OpenBSD::Ustar.pod,v 1.2 2005/06/12 11:24:28 espie Exp $ +$OpenBSD: OpenBSD::Ustar.pod,v 1.3 2005/06/13 12:39:14 espie Exp $ =head1 NAME @@ -7,51 +7,76 @@ OpenBSD::Ustar - simple access to Ustar C<tar(1)> archives =head1 SYNOPSIS use OpenBSD::Ustar; - open(my $fh, "<", $filename); - $arc = OpenBSD::Ustar->new($fh, $destdir); - while (my $o = $arc->next()) { + # for reading + + open(my $in, "<", $filename); + $rdarc = OpenBSD::Ustar->new($in, $destdir); + while (my $o = $rdarc->next()) { # decide whether we want to extract it, change object attributes $o->create(); } - close($fh); + close($in); + + # for writing + open(my $out, ">", $filename); + $wrarc = OpenBSD::Ustar->new($fh, $destdir); + # loop + my $o = $wrarc->prepare($filename); + # tweak some entry parameters + $o->write(); + close($out); =head1 DESCRIPTION -C<OpenBSD::Ustar> provides an API to read archives created by C<tar(1)>. +C<OpenBSD::Ustar> provides an API to read or write archives compatible with +C<tar(1)> For the time being, it can only handle the USTAR archive format. +A filehandle C<$fh> is associated with an C<OpenBSD::Ustar> object through +C<new>. For archive reading, the filehandle should support +C<read>. C<OpenBSD::UStar> does not rely on C<seek> or C<rewind> in order +to be usable on pipe outputs. For archive writing, the filehandle should +support C<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 file handle. + +Read access to an archive object C<$rdarc> occurs through a loop that +repeatedly calls C<$o = $rdarc-E<gt>next()> to obtain the next archive entry. +It returns an archive entry object C<$o> that can be +queried to decide whether to extract this entry or not. + +Write access to an archive object C<$wrarc> occurs through a user-directed +loop: obtain an archive entry through C<$o = $wrarc-E<gt>prepare($filename)>, +which can be tweaked manually and then written to the archive. + Most client software will specialize C<OpenBSD::Ustar> to their own needs. Note however that C<OpenBSD::Ustar> is not designed for inheritance. Composition (putting a C<OpenBSD::Ustar> object inside your class) and forwarding methods (writing C<create> or C<next> methods that call the corresponding C<OpenBSD::Ustar> method) are the correct way to use this API. -A filehandle C<$fh> is associated with an C<OpenBSD::Ustar> object through -C<new>. The filehandle should support C<read>. C<OpenBSD::UStar> does not -rely on C<seek> or C<rewind> in order to be usable on pipe outputs. - -On the other hand, C<OpenBSD::Ustar> does not do any caching. The client +Note that C<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. -Access to the archive object C<$arc> occurs through a loop that repeatedly -calls C<$o = $arc-E<gt>next()> to obtain the next archive entry. -It returns an archive entry object C<$o> that can be -queried to decide whether to extract this entry or not. - Actual extraction is performed through C<$o-E<gt>extract()> and is not mandatory. Thus, client code can control whether it wants to extract archive elements or not. +Actual writing is performed through C<$o-E<gt>write()> and is not mandatory +either. + Client code may decide to abort archive extraction early, or to run it through until C<$arc-E<gt>next()> returns false. The C<OpenBSD::Ustar> object doesn't hold any resources and doesn't need any specific clean-up. However, client -code is responsible for closing the filehandle and terminating any associated -pipe process. +code is responsible for closing the underlying filehandle and +terminating any associated pipe process. -An object C<$o> returned through C<next> holds all the characteristics of the -archive header: +An object C<$o> returned through C<next> or through C<prepare> holds all +the characteristics of the archive header: =over 20 @@ -110,8 +135,8 @@ name of the source link, if applicable =back The fields C<name>, C<mode>, C<mtime>, C<uid>, C<gid> and C<linkname> -can be altered before calling C<$o-E<gt>create()>, and will properly -influence the resulting file. +can be altered before calling C<$o-E<gt>create()> or C<$o-E<gt>write()>, +and will properly influence the resulting file. The relationship between C<uid> and C<uname>, and C<gid> and C<gname> conforms to the USTAR format usual behavior. |