From 016569c33b6bd825b1c7dffd7ca4d39c9ab4f2f0 Mon Sep 17 00:00:00 2001
From: Marc Espie <espie@cvs.openbsd.org>
Date: Mon, 26 Mar 2007 23:26:51 +0000
Subject: adjust documentation to simplify the common case.

---
 usr.sbin/pkg_add/pod/OpenBSD::Ustar.pod | 35 ++++++++++++++++-----------------
 1 file changed, 17 insertions(+), 18 deletions(-)

(limited to 'usr.sbin')

diff --git a/usr.sbin/pkg_add/pod/OpenBSD::Ustar.pod b/usr.sbin/pkg_add/pod/OpenBSD::Ustar.pod
index 8624cfe031c..f44820e7217 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.9 2005/09/17 10:35:27 espie Exp $
+$OpenBSD: OpenBSD::Ustar.pod,v 1.10 2007/03/26 23:26:50 espie Exp $
 
 =head1 NAME
 
@@ -9,41 +9,39 @@ OpenBSD::Ustar - simple access to Ustar C<tar(1)> archives
     use OpenBSD::Ustar;
     # for reading
 
-    open(my $in, "<", $arcname);
+    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();
     }
-    close($in);
+    $rdarc->close();
 
     # for writing
-    open(my $out, ">", $arcname);
+    open(my $out, ">", $arcnameforwriting) or die;
     $wrarc = OpenBSD::Ustar->new($fh, $destdir);
     # loop
     	my $o = $wrarc->prepare($filename);
 	# tweak some entry parameters
 	$o->write();
 
-    $wrarc->pad();
-    close($out);
+    $wrarc->close();
 
     # for copying 
-    open(my $in, "<", $arcname);
+    open(my $in, "<", $arcnameforreading) or die;
     $rdarc = OpenBSD::Ustar->new($in, $destdir);
-    open(my $out, ">", $arcname);
+    open(my $out, ">", $arcnameforwriting) or die;
     $wrarc = OpenBSD::Ustar->new($fh, $destdir);
     while (my $o = $rdarc->next()) {
     	$o->copy($wrarc);
     }
-    $wrarc->pad();
-    close($in);
-    close($out);
+    $rdarc->close();
+    $wrarc->close();
 
 =head1 DESCRIPTION
 
 C<OpenBSD::Ustar> provides an API to read, write and copy archives compatible 
-with C<tar(1)>
+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
@@ -85,8 +83,13 @@ C<$v = $o-E<gt>contents()>.
 Actual writing is performed through C<$o-E<gt>write()> and is not mandatory
 either.
 
-Writing valid archives requires calling C<$wrarc-E<gt>pad()> after archiving
-all the entries to complete the archive with blank-filled blocks.
+Archives should be closed using C<$wrarc-E<gt>close()>.
+In particular, this is mandatory for write access, since valid archives
+require blank-filled blocks.
+
+Alternately, calling C<$wrarc-E<gt>pad()> after archiving
+all the entries will complete the archive with blank-filled blocks,
+in case one wants to close the associated file handle manually.
 
 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
@@ -94,10 +97,6 @@ hold any resources and doesn't need any specific clean-up. However, client
 code is responsible for closing the underlying filehandle and 
 terminating any associated pipe process.
 
-A convenience method C<close> is provided that can be used to finish reading
-or writing to an archive, providing adequate padding and closing the 
-associated filehandle.
-
 An object C<$o> returned through C<next> or through C<prepare> holds all 
 the characteristics of the archive header:
 
-- 
cgit v1.2.3