document the write API as well.

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.